0
点赞
收藏
分享

微信扫一扫

2022-08-01 在线文档生成


由于项目中可能会有那种对外的项目,那么就需要写一些类似操作文档的东西,有的项目是弄好一个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)




2022-08-01 在线文档生成_配置文件


image.png


第四步: 配置
1 配置设置文档名称,主题等 修改 mkdocs.yml




image.png


2 增加页面 进入docs 文件夹中
a: 更改index.md 增加文件(页面)名称




image.png


b: 创建相应名称放到与index.md同位置下



image.png


至此, 就可以实现如图的效果了




image.png


由于docs文件夹中的文件都是md结尾的,也就是markdown文件,可以用相应的编译器先编写好,然后粘贴进来,就可以实现效果了;

附加: 打包
其次上面是相当于运行了一个mkdoc服务,也可以这样,将之前的东西打包好,然后像部署vue项目一样,部署也可以;
在安装位置找到bin文件夹,然后运行 mkdoc build




image.png


执行后,会出现一个site文件夹,熟悉吧? 直接发布到nginx 上就好了!!!




image.png


第二种部署方式 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 实现中文搜索

举报

相关推荐

0 条评论