MkDocs | 超简单的文档生成器

简介: MkDocs | 超简单的文档生成器

前言


最近啊,我比较迷恋文档和静态站点生成,今天我们再分享一个基于 PythonMarkdown 的文档生成器。它就是 MkDocs


关于 MkDocs


MkDocs 是一个快速、简单、完全华丽的静态站点生成器,用于构建项目文档。文档源文件以 Markdown 格式编写,并使用单个 YAML 配置文件进行配置。


呆猫


安装 MkDocs


pip install mkdocs
复制代码


创建 MkDocs 项目


PS C:\> mkdocs.exe new my-demo
INFO     -  Creating project directory: my-demo
INFO     -  Writing config file: my-demo\mkdocs.yml
INFO     -  Writing initial docs: my-demo\docs\index.md
PS C:\> cd .\my-demo\
PS C:\my-demo> ls
    目录: C:\my-demo
Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----          22-2-9  下午 09:00                docs
-a----          22-2-9  下午 09:00             20 mkdocs.yml
PS C:\my-demo>
复制代码


启动项目


命令:mkdocs.exe serve


网络异常,图片无法展示
|


网络异常,图片无法展示
|


如上,我们可以发现两个亮点。第一 MkDocs 生成的文档自带 ico;第二 MkDocs 默认支持搜索。


打造我们自己的在线文档


MkDocs 不同于 Pelican 等站点生成器,其类似 Docsify+Pelican,即可以在访问过程中动态渲染,也可以编译为静态资源。我们只需要维护自己的 docs 目录即可。


创建自己的文档


我们在 docs 目录下创建我们自己的文档mydemo.md,内容太长,就不做展示了。

然后我们访问http://localhost:8000/,就可以看到我们的站点已经发生了变化。没错,MkDocs 是支持热加载的。


网络异常,图片无法展示
|


网络异常,图片无法展示
|


下拉菜单


我们需要在mkdocs.yml中进行 nav 配置,假设我们想把我们的文章 Mydemo 放到一个 Blog 下拉菜单中,起名为 Pelican 入门。


site_name: My Docs
nav:
    - Home: '../'
    - 'Blog':
      - 'Pelican入门': 'mydemo.md'
复制代码


再次查看http://localhost:8000/


网络异常,图片无法展示
|


不得不说,秒啊。


编译文档


mkdos.exe build
复制代码


网络异常,图片无法展示
|


我们进入 site 目录,用 pythonhttp.server 模块启动我们能的静态站点。


网络异常,图片无法展示
|


网络异常,图片无法展示
|


为了方便展示,我们直接使用 pythonhttp.server 工具启动了我们的站点,实际生产中建议你选择 nginx 之类的 web 服务器来托管你的静态站点。


更多内容详见:www.mkdocs.org/

相关文章
|
运维 持续交付 网络安全
|
12月前
Erlang匿名函数示例
Erlang匿名函数示例
60 1
|
前端开发 JavaScript API
MkDocs是一个用Python编写的快速、简单且易于定制的静态网站生成器
MkDocs是一个用Python编写的快速、简单且易于定制的静态网站生成器
|
JSON JavaScript 前端开发
借助Python神器,快速get上市公司财务数据
借助Python神器,快速get上市公司财务数据
445 0
|
数据采集 数据挖掘 数据处理
Pandas如何安装在Windows系统?
【7月更文挑战第8天】Pandas如何安装在Windows系统?
778 2
|
安全 Java 数据安全/隐私保护
构建高效网站后台:权限管理系统设计与实现
【7月更文挑战第5天】在现代Web应用开发中,权限管理是后台系统不可或缺的一部分,它确保了系统的安全性与用户数据的隐私。良好的权限管理系统能够精细控制不同用户角色对功能模块及数据资源的访问权限,从而提升系统的灵活性和安全性。本文将深入探讨权限管理的基本概念、设计思路,并通过一个简单的代码示例展示如何在Web后台中实现基本的权限控制逻辑。
744 2
|
Android开发
Android studio 2021.3.1不生成iml文件
Android studio 2021.3.1不生成iml文件
510 5
|
存储 监控 JavaScript
10G PON部署在企业接入中的应用
在当今数字化时代,随着企业接入需求不断增长,对更高带宽和高速率的网络连接提出了挑战。10G PON作为一种新一代光纤接入网络技术,正逐渐成为企业接入领域的选择。
184 0
|
网络协议 C++ Docker
Docker pull拉取镜像报错“Error response from daemon: Get "https://registry-1.docker.io/v2”解决办法
Docker pull拉取镜像报错“Error response from daemon: Get "https://registry-1.docker.io/v2”解决办法
54259 1
|
安全 前端开发 索引
谈一谈|MkDocs介绍及应用
谈一谈|MkDocs介绍及应用
492 0