苟家宁
如何使用MkDocs制作软件或者项目文档
2021-8-3 23:58
阅读:350


摘要:本文介绍如何使用Mkdocs工具制作软件项目文档

简介

MkDocs是一个快速、简单和非常华丽的静态网站生成器,类似于hugohexoSphinx等静态网页生成器,能够非常方面地构建静态网站,如博客、项目网站等。+

特点

  • MkDocs拥有许多漂亮的主题,如Bootstrap主题、readthedocs(这个主题在很多软件文档中有用到)、还有一些第三方的主题都能够集成在MkDocs中使用

  • 易于个性化,通过配置文件mkdocs.yml的修改,用户可以方便地根据自己的喜好修改为自己喜欢的样式,不需要懂前端的知识(如html、css等)

  • 方便部署,其通过内置的dev-server,快速在云端部署网站的更新内容

  • 部署环境多样,用户可以在很多平台上部署网站,如github page(推荐)、亚马逊 S3,用户可以通过Read the Docs免费host他们的网站,该网站由公益基金资助,提供文档托管的免费服务

快速开始

网站的创建与部署非常简单,首先需要python环境,使用命令

pip install mkdocs

安装软件包,在建站目录下运行

mkdocs new my-project
cd my-project

生成如下文件夹

Screenshot


随后运行

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

发布离线网站,在线预览

doc文件夹中写入文档(markdown)即可


转载本文请联系原作者获取授权,同时请注明本文来自苟家宁科学网博客。

链接地址:https://wap.sciencenet.cn/blog-3465931-1298228.html?mobile=1

收藏

分享到:

下一篇
当前推荐数:0
推荐到博客首页
网友评论0 条评论
确定删除指定的回复吗?
确定删除本博文吗?