美文网首页
Mkdocs 项目文档简易制作

Mkdocs 项目文档简易制作

作者: wkevin27 | 来源:发表于2018-12-13 16:04 被阅读66次

    markdown 写的文档,在项目组内外分享时不能要求读者也将就着读markdown,最好还是读网页的友好形式 —— mkdocs 是个不错的选择。

    mkdocs 之前,我都是 git push md 文档后,触发http server 上的 git pull,然后利用一些零散的js脚本实现md->html的动态编译,包括:TOC(目录)、CSS、Theme…… mkdocs 则方便且优雅的完成这一切。

    安装

    > sudo apt install mkdocs
    

    创建新项目

    > mkdocs new k-project
    

    启动自带的http-server

    > mkdocs serve
    
    INFO    -  Building documentation... 
    [I 181213 15:43:02 server:271] Serving on http://127.0.0.1:8000
    

    撰写和预览

    下图左边是 VSCode 打开的 k-project,右边是浏览器打开 http://127.0.0.1:8000
    新建的项目只有2个文件:

    • mkdocs.yml —— 配置文件
    • docs/index.md —— 自动生成的官方宣传页
      下图配置了网站的名字(site_name)
    snapshot1.png

    docs 目录下就自由的写文档吧,我随手创建了几个:

    • about.md
    • foo/bar.md
    • develop/hello.md
    • develop/world.md
    • img/ 几张图片

    mkdocs 会自动把所有 md 文件编译到网站的导航栏里,官方说是:

    • index.md 永远是第一个
    • 其余的按字母顺序排列 —— 但我自己的操作貌似是按创建时间顺序
    • img 只有图片,不列入导航栏

    效果如下图,可看到导航栏有了 Home、About、Foo、Develop,没有 img

    snapshot3.png

    用自动生成的导航栏基本不会是我们想要的,顺序、显示肯定要调一调。
    新增和修改 mkdocs.yml 的 pages(以前是nav)可以实现。
    如下图:

    snapshot4.png

    编译

    在有 mkdocs.yml 文件的目录下执行

    > mkdocs build
    

    会生成 site 文件夹,其中是编译好的静态 html 文件,利于部署。

    总结

    • 适合做项目文档的展示,没法做Blog。
    • 把 site 加入 .gitignore ,能和git项目完美融合。
    • mkdocs build 命令使其可以融入CI。

    相关文章

      网友评论

          本文标题:Mkdocs 项目文档简易制作

          本文链接:https://www.haomeiwen.com/subject/aphbhqtx.html