树洞剪藏#剪藏#树洞剪藏

为技术项目量身定做的文档工具MkDocs

2024 年 11 月 15 日约 1 分钟

分享Twitter / X Telegram 微博

同步来源：树洞剪藏源站剪藏 ID：13 原文地址：https://mp.weixin.qq.com/s/zqN4dtH9GOI6NrEBdS3ABA

打开原文 · 打开源站剪藏快照

原创

杨浦老苏

各种折腾

2024年08月16日 19:00 上海

各种折腾聚沙成塔，集腋成裘 751篇原创内容

公众号，

什么是 MkDocs ？

MkDocs 是一款快速、简单且极其出色的静态网站生成器，专门用于构建项目文档。文档源文件以 Markdown 编写，并使用单个 YAML 配置文件进行配置。它易于使用，并且可以使用第三方主题、插件和 Markdown 扩展进行扩展。软件的主要特点：

Markdown 支持： MkDocs 支持标准的 Markdown 语法，使得编写文档变得简单快捷。

主题丰富： MkDocs 提供了多种预设主题，用户可以选择一个主题来定制文档的外观和感觉。

导航栏： MkDocs 可以自动生成一个导航栏，方便用户在不同页面间导航。

版本控制： MkDocs 支持文档的版本控制，可以为不同版本的项目维护不同的文档集。

插件系统： MkDocs 拥有一个插件系统，允许用户扩展其功能，例如添加自定义的导航栏、搜索功能等。

国际化： MkDocs 支持多语言文档，可以为不同语言的用户提供本地化的文档。

部署简单：生成的文档是静态 HTML 文件，可以部署在任何静态文件服务器上，包括 GitHub Pages 。

实时预览： MkDocs 提供了一个开发服务器，可以在编写文档时提供实时预览，方便查看文档效果。

配置灵活： MkDocs 的配置文件（通常是 mkdocs.yml ）允许用户定制网站的各种设置，如标题、描述、 URL 等。

社区支持：作为一个流行的开源项目， MkDocs 拥有一个活跃的社区，提供帮助和支持。

易于使用： MkDocs 的安装和使用都非常简单，通过 Python 的包管理器 pip 即可安装。

扩展性：用户可以通过编写自定义脚本或使用社区提供的扩展来进一步定制 MkDocs 的行为。什么是 Material for MkDocs ?

Material for MkDocs 是基于 MkDocs 的强大文档框架。支持 docker 部署方式。新建文档在群晖上以 Docker 方式运行。首先要在指定的目录中，创建项目文档及配置文件

新建文件夹 mkdocs 和子目录

mkdir -p /volume1/docker/mkdocs/docs

进入 mkdocs 目录

cd /volume1/docker/mkdocs

新建站点

docker run -it
--rm
-v $( pwd )/:/docs
squidfunk/mkdocs-material new .

注意最后的那个点别漏了这将创建以下结构 . ├─ docs/ │ └─ index.md └─ mkdocs.yml

根目录下会生成 mkdocs.yml docs 目录中会生成 index.md 新建的 mkdocs.yml 只有一行 site_name: My Docs

我们可以根据需要进行修改，例如下面👇这样 site_name: My Docs site_url: https://laosu.tech/ site_description: Markdown 写的项目文档。 site_author: laosu

nav:

Home: index.md

plugins:

theme: material

因为包含了了中文，所以记得采用 UTF-8 格式保存实时预览 MkDocs 包含一个实时预览服务器，因此您可以在编写文档时预览更改。

边写边预览

docker run -it
--rm
-p 5065:8000
-v $( pwd )/:/docs
squidfunk/mkdocs-material

在浏览器中输入 http://群晖IP:5065 就能看到主界面你在 index.md 上做的任何修改，不需要刷新页面，会显示出来接下来我们要做的是研究 MkDocs 的高级配置，https://squidfunk.github.io/mkdocs-material/creating-your-site/#advanced-configuration，来研究如何改颜色、改字体、设置版本控制等生成站点完成编辑后，你可以使用以下命令从 Markdown 文件构建静态站点 docker run -it
--rm
-v $( pwd )/:/docs
squidfunk/mkdocs-material build

会在根目录生成 site 子目录此目录的内容构成了您的项目文档。无需操作数据库或服务器，因为它是完全独立的。该网站可以托管在 GitHub Pages 、 GitLab Pages 、您选择的 CDN 或您的私人网络空间上参考文档

mkdocs/mkdocs: Project documentation with Markdown. 地址：https://github.com/mkdocs/mkdocs MkDocs 地址：https://www.mkdocs.org/ squidfunk/mkdocs-material - Docker Image | Docker Hub 地址：https://registry.hub.docker.com/r/squidfunk/mkdocs-material/ Creating your site - Material for MkDocs 地址：https://squidfunk.github.io/mkdocs-material/creating-your-site/

各种折腾聚沙成塔，集腋成裘 751篇原创内容

公众号， @所有人：写文不易，如果你都看到了这里，请点个赞和在看，分享给更多的朋友；为确保你能收到每一篇文章，请主页右上角设置星标。

预览时标签不可点

群晖 656 docker 663 markdown 11 在线文档 8

群晖 · 目录

上一篇开源网络评论引擎Comentario 下一篇 Linux服务器运维管理面板1panel

个人观点，仅供参考阅读原文

关闭

小程序广告

搜索「undefined」网络结果

微信扫一扫关注该公众号

当前内容可能存在未经审核的第三方商业营销信息，请确认是否继续访问。

继续访问取消微信公众平台广告规范指引

：，。

视频小程序赞，轻点两下取消赞在看，轻点两下取消在看分享留言收藏

新建文件夹 mkdocs 和 子目录

进入 mkdocs 目录

新建站点

边写边预览

相关文章

新建文件夹 mkdocs 和子目录