由于项目中可能会有那种对外的项目,那么就需要写一些类似操作文档的东西,有的项目是弄好一个word文档,谁看就直接下载下去,体验不佳;
那么如何做到与项目一致,在线浏览呢?
今天为大家带来一个 可以生成文档的工具,生成后,就是一个静态页面,可以直接部署到自己的服务器上,与项目页面浏览无异;
官网地址: https://squidfunk.github.io/mkdocs-material/getting-started/
由于我不熟悉python,所以这里直接采用docker 安装 构建
第一步: 下载
docker pull squidfunk/mkdocs-material
第二步: 运行命令初始化,运行的时候要记住自己当前所在的文件位置,因为会在当前位置生成必要的bin doc等重要文件
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
运行后,当前所在位置会出现如下文件结构
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
其中 mkdocs.yml 是 mkdoc的配置文件,可以设置文档名称,主题等
index.md 可以扩展页面具体后续描述
第三步: 运行
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
运行后会出现可以访问的路径
可以直接在浏览器访问 : http://10.0.59.65:8000 (ip:8000)
第四步: 配置
1 配置设置文档名称,主题等 修改 mkdocs.yml
2 增加页面 进入docs 文件夹中
a: 更改index.md 增加文件(页面)名称
b: 创建相应名称放到与index.md同位置下
至此, 就可以实现如图的效果了
由于docs文件夹中的文件都是md结尾的,也就是markdown文件,可以用相应的编译器先编写好,然后粘贴进来,就可以实现效果了;
附加: 打包
其次上面是相当于运行了一个mkdoc服务,也可以这样,将之前的东西打包好,然后像部署vue项目一样,部署也可以;
在安装位置找到bin文件夹,然后运行 mkdoc build
执行后,会出现一个site文件夹,熟悉吧? 直接发布到nginx 上就好了!!!
第二种部署方式 pip 方式
第一步:
pip install mkdocs
第二步 选择一个位置 运行,简历一个test 文件名称
mkdocs new test
mkdocs运行主要需要两个部分：
一个yml配置文件用来进行配置
一个存放markdown文件的地址
在这里 mkdocs 生成了一个 docs 文件夹和 mkdocs.yml 配置文件
第三步 进入test 启动 服务
mkdocs serve
第四步配置
mkdocs会默认将 docs 文件夹下的 index.md 或者 readme.md 作为首页。同时，我们也可以通过自己的配置来决定页面布局。下面是一个完整的 mkdocs.yml
site_name: NAME
nav:
- Home: index.md
- About: about.md
- Other: other.md
theme:
name: readthedocs
dev_addr: 10.0.59.161:8000
plugins:
- search:
lang:
- en
- ja
separator: '[\s\-\.]+'
dev_addr: 10.0.59.161:8000 ip : 端口 默认是 127.0.0.1:8000 必须改成这样 才能正常访问
plugins 实现中文搜索
