构建自己文档网站

2021年12月29日 17:55 by wst

文档开发

---

当我们开发好系统之后，为了用户友好使用，一般会给出使用文档。

对于程序员来说，markdown是最顺手的写文档的工具。

下面就来介绍两个生成文档的方法：

基于（react）docusaurus的方法

简介

Docusaurus 能够帮助你建立并发布 美观的文档网站。

自行搭建技术栈是非常昂贵的。而使用 Docusaurus 可以让你专注于内容 并只需编写 Markdown 文件即可。

为更多功能做好准备了吗？大量 高级功能 （例如版本化、i18n、搜索和自定义主题）来了。

请查看 最佳 Docusaurus 网站 列表以获得灵感，还有一些 用户心得 请做参考。

Docusaurus 是一个 静态网站生成器。它发挥了 React 的全部功能来构建具有快速客户端导航的 单页应用，从而赋予你的网站交互性。它提供了开箱即用的 文档功能，还能用于创建 任何类型的网站 （例如个人网站、产品介绍、博客、营销页等等）。

步骤

1. 安装node.js

2. 创建my-website网站

npx create-docusaurus@latest my-website classic

3. 启动网站

cd my-website && npm start

4. 访问网站

http://localhost:3000/

基于（python）MkDocs的方法

简介

MkDocs 是一个基于 Python 构建的静态网站生成器，其价值主张与 Docusaurus 类似。

如果你不需要单页应用并且不打算使用 React 的话，MKDocs 是一个不错的选择。

Material for MkDocs 是一个漂亮的主题。

步骤

1. 安装python3.8

2. 安装mkdocs

pip install mkdocs

3. 创建项目

mkdocs new my-project
cd my-project

4. 启动项目

mkdocs serve

5. 访问网站

http://127.0.0.1:8000/

6. 设置不同的主题

pip install mkdocs-material

然后修改 mkdocs.yml 中的内容：theme: material

---