{"id":17504363,"url":"https://github.com/orionxer/mkdocs_foam_template","last_synced_at":"2025-07-01T06:32:47.178Z","repository":{"id":258460965,"uuid":"873965105","full_name":"Orionxer/mkdocs_foam_template","owner":"Orionxer","description":"📘 基于MkDocs和Foam的个人知识管理仓库模板","archived":false,"fork":false,"pushed_at":"2025-02-06T07:18:34.000Z","size":22587,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T20:14:56.109Z","etag":null,"topics":["foam","mkdocs","mkdocs-material"],"latest_commit_sha":null,"homepage":"https://orionxer.github.io/mkdocs_foam_template/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Orionxer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-17T02:52:16.000Z","updated_at":"2025-02-06T07:18:04.000Z","dependencies_parsed_at":"2025-02-03T02:40:27.428Z","dependency_job_id":null,"html_url":"https://github.com/Orionxer/mkdocs_foam_template","commit_stats":null,"previous_names":["orionxer/mkdocs_foam_template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orionxer%2Fmkdocs_foam_template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orionxer%2Fmkdocs_foam_template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orionxer%2Fmkdocs_foam_template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orionxer%2Fmkdocs_foam_template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Orionxer","download_url":"https://codeload.github.com/Orionxer/mkdocs_foam_template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246093180,"owners_count":20722402,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["foam","mkdocs","mkdocs-material"],"created_at":"2024-10-20T00:15:11.754Z","updated_at":"2025-03-28T20:15:08.311Z","avatar_url":"https://github.com/Orionxer.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# MkDocs Foam Template\r\n\r\n![Build Workflow](https://github.com/orionxer/mkdocs_foam_template/actions/workflows/ci.yml/badge.svg)\r\n![Website](https://img.shields.io/website?url=https%3A%2F%2Forionxer.github.io/mkdocs_foam_template)\r\n![GitHub License](https://img.shields.io/github/license/orionxer/mkdocs_foam_template)\r\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs)\r\n\r\n一款自动管理并部署个人知识库的模板仓库。基于[Foam](https://github.com/foambubble/foam)管理个人笔记，通过[MkDocs](https://www.mkdocs.org/getting-started/)部署至云端。\r\n\r\n[在线预览](https://orionxer.github.io/mkdocs_foam_template)\r\n\r\n知识图谱预览\r\n\r\n![foam_graph](docs/images/foam_graph.gif)\r\n\r\n- [ ] 压缩图片体积，加快访问README的速度\r\n\r\n## 1.快速开始\r\n\u003e [!IMPORTANT]  \r\n\u003e 使用该仓库默认你已经熟悉`VSCode`并了解`Git`的相关知识以及操作。\r\n\r\n### 1.1 安装VSCode插件\r\n- Foam\r\n- Markdown All in One\r\n- Markdown Footnotes\r\n- Markdown Preview Enhanced\r\n- Markdown Preview Github Styling\r\n- Prettier - Code formatter\r\n- Flutter Color\r\n\r\n### 1.2 下载仓库\r\n```sh\r\ngit clone https://github.com/Orionxer/mkdocs_foam_template\r\n```\r\n也可以选择`Fork`或者使用模板创建自己的仓库，再下载到本地\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e点击查看图片\u003c/summary\u003e \r\n\r\n![通过模板创建仓库](docs/images/use_template.png)\r\n\u003c/details\u003e\r\n\r\n### 1.3 环境依赖\r\n进入项目\r\n```sh\r\ncd mkdocs_foam_template\r\n```\r\n安装依赖\r\n```sh\r\npip install -U -r requirements.txt\r\n```\r\n\r\n### 1.4 Foam知识图谱\r\n通过`VSCode`打开该项目，`Ctrl + Shift + P`调出命令控制器，输入`Show graph`，选择`Foam: Show graph`查看知识图谱。同时打开Markdown预览，点击图谱中的**节点**或者笔记中的**双向链接**，就可以跳转到对应的笔记。\r\n\r\n![foam_graph](docs/images/foam_graph.png)\r\n\r\n### 1.5 MkDocs本地部署\r\n\r\n\u003e [!TIP]  \r\n\u003e 默认使用[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)主题，如果需要更换主题则需要修改`requirements.txt`和`mkdocs.yml`以及`.github/workflows/ci.yml`对应的内容\r\n\r\n部署命令\r\n```sh\r\nmkdocs serve\r\n```\r\n成功部署后，控制台会输出`http://127.0.0.1:8000`地址，`Ctrl`+单击该地址就会在默认浏览器中打开该地址查看部署效果\r\n\r\n![mkdocs_graph](docs/images/mkdocs_graph.gif)\r\n\r\n\r\n## 2.在线部署(可选)\r\n\u003e [!NOTE]  \r\n\u003e 当Github检测到代码推送的时候，通过配置好的Github Actions和Pages就能实现自动化部署网站。[在线部署效果预览](https://orionxer.github.io/mkdocs_foam_template)\r\n\r\n### 2.1 设置Actions权限\r\n- 点击仓库中的`Settings`选项卡\r\n- 展开`Actions`，选择`General`\r\n- 找到`Workflow permissions`，选择`Read and write permissions`，并勾选`Allow GitHub Actions to create and approve pull requests`\r\n- 点击`Save`保存\r\n   \r\n\u003cdetails\u003e\r\n\u003csummary\u003e点击查看图片\u003c/summary\u003e\r\n\r\n![设置Workflow权限](docs/images/workflow_permissions.png)\r\n\u003c/details\u003e\r\n\r\n### 2.2 推送代码\r\n适当修改内容，尝试向Github推送一次代码。等待几分钟，确保仓库主页存在`gh-pages`分支。\r\n\u003e Github会根据`.github/workflows/ci.yml`配置自动执行`mkdocs gh-deploy --force`命令，也就是Github Actions会创建一个`gh-pages`分支，并将`mkdocs build`的内容上传至该分支。\r\n\r\n### 2.3 部署分支\r\n- 点击仓库中的`Settings`选项卡\r\n- 点击`Pages`，在`Build and deployment`下的Branch，选择`gh-pages`, 路径选择`/root`\r\n- 点击`Save`保存\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e点击查看图片\u003c/summary\u003e\r\n\r\n![部署分支](docs/images/pages_branch.png)\r\n\u003c/details\u003e\r\n\r\n等待页面出现`Your site is live at https://xxxx`就说明部署成功了，点击`Visit site`按钮就可以访问该网站\r\n\r\n![预览网站](docs/images/live_site.png)\r\n\r\n### 2.4 自定义域名\r\n\r\n\u003e [!WARNING]\r\n\u003e 如果DNS设置了泛域名的A记录解析，则需要取消该设置。否则泛域名的A记录解析的优先级会高于CNAME记录，任何的CNAME记录都无法生效，也就导致二级域名无法重定向到github pages的域名。\r\n\r\n#### 2.4.1 设置DNS解析记录\r\n假设需要自定义一个二级域名`note.gogo.uno`作为网站域名，此处以`Godaddy`的DNS控制台为例，设置二级域名`note`的CNAME记录为`orionxer.github.io.`，**注意：最后的.不能忽略**，TTL设置为600秒以加快DNS记录生效时间。\r\n\r\n![设置DNS解析记录](docs/images/set_dns.png)\r\n\r\n#### 2.4.2 修改仓库名称\r\n确保你的仓库名称是`$username.github.io`，比如`orionxer.github.io`\r\n\r\n![修改仓库名称](docs/images/rename_repository.png)\r\n\r\n#### 2.4.3 Pages设置域名\r\n- 点击`Settings`的`Pages`项\r\n- 在`Custom domain`输入二级域名`note.gogo.uno`（替换你自己的二级域名）\r\n- 点击`Save`保存，域名下方会提示`DNS Check in Progress`直至`DNS check successful`\r\n- 勾选`Enforce HTTPS`以启用https，示例：[https://note.gogo.uno](https://note.gogo.uno)\r\n\r\n![自定义域名](docs/images/custom_domain.png)\r\n\r\n## 3.协议说明\r\n本项目遵守`GPL 3.0`协议。你可以自由复制、修改。如果你将代码分享给别人（比如在 GitHub 上公开），需要继续遵守`GPL 3.0`协议，并提供源代码。如果只是自己使用(比如个人离线使用或者将自己的仓库设置为私有)，则不受协议的公开要求限制。感谢各位同学支持开源共享🍻\r\n\r\n## 4.参考\r\n- [Foam](https://github.com/foambubble/foam)\r\n- [Getting Started with MkDocs](https://www.mkdocs.org/getting-started/)\r\n- [Foam/Obsidian-mkdocs-template](https://github.com/Jackiexiao/foam-mkdocs-template)\r\n- [VS Code 中的双链笔记：Foam 使用体验分享](https://sspai.com/post/70956)\r\n- [Foam使用说明](https://www.onekbase.com/kb-km/2dn-km-vsc-foam.html)\r\n- [MkDocs中文文档](https://hellowac.github.io/mkdocs-docs-zh/)\r\n- [🏆 📚 A list of awesome MkDocs projects and plugins.](https://github.com/mkdocs/catalog)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forionxer%2Fmkdocs_foam_template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forionxer%2Fmkdocs_foam_template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forionxer%2Fmkdocs_foam_template/lists"}