MkDocs是一个静态站点生成器，可用于构建项目文档。文档文件使用Markdown语法编写，本文记录如何使用MkDocs生成项目文档，并部署到Read the Docs上。

安装mkdocs
搭建文档项目
- 创建项目
- 启动项目
- 编写文档
- - Markdown语法
  - 站内链接
  - 图片
- 文档结构
配置文档项目
- 项目信息
- 更改图标
- 主题配置
部署文档到readthedocs
- 准备github项目
- 注册登录Read the Docs
- 导入github项目到 Read the Docs

安装mkdocs

先在本地搭建MkDocs站点。

安装Python虚拟环境，我电脑Python环境是使用Anaconda安装的，使用conda命令创建一个虚拟环境：

$ conda create  --prefix=python38 python=3.8
$ conda activate C:\Users\10287\python38

在虚拟环境python38中使用pip命令安装mkdocs：

$ pip install mkdocs
$ mkdocs --version
mkdocs, version 1.4.3 from C:\Users\10287\python38\lib\site-packages\mkdocs (Python 3.8)

搭建文档项目

创建项目

创建博客项目

$ D:\ProgramWorkspace\blog
$ mkdocs new mkdocsProject

创建完成后目录结构如下：

D:\PROGRAMWORKSPACE\BLOG\MKDOCSPROJECT
│  mkdocs.yml
│
└─docsindex.md

mkdocs.yml 为配置文件

docs目录中存放Markdown文档及文档图片。index.md 文件为博客的索引页。

启动项目

启动服务：

$ cd D:\ProgramWorkspace\blog\mkdocsProject
$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.11 seconds
INFO     -  [17:45:25] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [17:45:25] Serving on http://127.0.0.1:8000/

浏览器打开http://127.0.0.1:8000/，将会显示如下页面：

编写文档

Markdown语法

博客文章使用Markdown语法编写，基本语法介绍可参考markdown基本语法介绍。

MkDocs的文章标题默认使用第一行的一级标题。

站内链接

MkDocs可以通过Markdown链接来实现站内链接文档：

请查看 [关于我](about/about.md) 获取我的联系方式。

图片

使用Markdown图像语法在文档中添加图片：

![Screenshot](about/wechat.png)

文档结构

假设文档目录结构如下：

D:\PROGRAMWORKSPACE\BLOG\MKDOCSPROJECT
│  mkdocs.yml
└─docs│  index.md├─about│  │  about.md│  ││  └─about│          wechat.png├─img│      favicon.ico └─python│  python-library-for-json.md│└─python-library-for-jsonjson_dump.png

在mkdocs.yml 配置文件的nav中设置文章布局：

nav: - 主页: index.md    - python:- "Python json文件读写": python/python-library-for-json.md    - 关于我: about/about.md

效果如下图：

配置文档项目

项目信息

站点名称：

site_name: My Docs
# site_url: http://127.0.0.1:8000
repo_url: https://github.com/example/repository/  # 仓库地址
repo_name: GitHub # 仓库名称
edit_uri: blob/main/docs/ # 编辑路径
site_description: # 站点描述
site_author: # 作者
copyright: # 版权声明

更改图标

可以修改MkDocs使用的默认图标，在docs目录中创建一个img子目录，然后将自定义favicon.ico文件复制到该目录中。MkDocs将自动检测并使用该文件作为你的图标。

D:\PROGRAMWORKSPACE\BLOG\MKDOCSPROJECT
│  mkdocs.yml
└─docs│  index.md    └─imgfavicon.ico

主题配置

mkdocs默认有两个主题：

mkdocs，默认主题
readthedocs

theme: readthedocs
# theme: mkdocs

mkdocs主题配置：

theme: name: mkdocshighlightjs: truehljs_languages:- yamlanalytics:gtag: G-ABC123shortcuts:       # 快捷键help: 191    # ?next: 78     # nprevious: 80 # psearch: 83   # snavigation_depth: 2 # 侧边栏导航标题最大层级nav_style: primary     # 顶部导航栏样式，可设置为 primary、dark 或者 lightlocale: zh_CN # 语言配置，需要安装mkdocs[i18n]：pip install mkdocs[i18n]

readthedocs主题配置：

theme: name: readthedocshighlightjs: truehljs_languages:- yaml- rustanalytics:gtag: G-ABC123include_homepage_in_sidebar: True  # 在侧边栏菜单中列出主页。prev_next_buttons_location: both # 设置 “Next” 和 “Previous” 按钮的位置：bottom, top, both , or nonenavigation_depth: 4 # 侧边栏导航标题最大层级，默认4collapse_navigation: True # 只在当前页面的侧边栏中包含页面标题。titles_only: False # 只在侧边栏中包括文章标题，不包括所有子标题。默认值:False。sticky_navigation: True #侧边栏在滚动页面时随主页内容滚动locale: zh_CN # 语言配置，需要安装mkdocs[i18n]：pip install mkdocs[i18n]

第三方主题参考这里：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

更多功能配置方法请参考官方文档：https://www.mkdocs.org/

部署文档到readthedocs

前面介绍的只是在本地运行，如果需要让其他人可以访问，需要部署到云服务器上，部署方式有很多，这里介绍如何部署到Read the Docs上。

准备github项目

登录github，创建一个公开项目mkdocsDemo：

在项目根目录打开git bash执行如下命令将博客push到新创建的github仓库：

git init
git add --all
git commit -m "mkdocs demo"
git branch -M main
git remote add origin https://github.com/hiyongz/mkdocsDemo.git
git push -u origin main

注册登录Read the Docs

Read the Docs注册地址：https://readthedocs.org/accounts/signup/

Read the Docs登录成功后的页面：

导入github项目到 Read the Docs

点击“导入一个项目”

点击添加创建的github项目

点击“下一页”

点击【管理】，进入高级设置，设置文档类型为Mkdocs，Python解释器选择CPython 2.x：

点击“Build version”构建版本

等待构建完成…

点击“阅读文档”，会跳转到文档页面

只要本地提交修改到GitHub项目，就会自动构建更新文档。

--THE END--

在线电子书创建：MkDocs + Github + ReadTheDocs相关推荐

【小沐学Python】Python实现在线电子书（MkDocs + readthedocs + github + Markdown）
文章目录 1.简介 2.安装 3.创建新项目 4.添加页面 5.编辑导航页 6.设置主题 7.更改图标图标 8.构建网站 9.部署 9.1 准备github项目 9.2 注册登录Read the Do ...
使用gitee+gitbook搭建个人在线电子书
GitBook是一个简单的个人在线书籍网站,在这里可以把自己的文档整理成书籍发布出来,便于阅读,现在使用gitee+gitbook搭建个人在线电子书! 官方示例:https://blog.gitboo ...
springboot毕设项目在线电子书阅读系统t7atu（java+VUE+Mybatis+Maven+Mysql）
springboot毕设项目在线电子书阅读系统t7atu(java+VUE+Mybatis+Maven+Mysql) 项目运行环境配置: Jdk1.8 + Tomcat8.5 + Mysql + H ...
永久免费在线电子书网站搭建系统
该在线电子书系统永久免费. 支持 Windows 和 Linux 两个操作系统. 1.安装包下载 Windows版本下载地址:https://download.csdn.net/download/wo ...
Webydo：一款在线自由创建网站的 Web 应用
Webydo 是一款专业的在线建站应用,使平面设计师可以创建和管理 HTML 网站,而无需编写代码.设计人员可以设计任何类型网站,只需要点击按钮,就能够发布先进的 HTML 网站. 你可以控制所有的设 ...
在线电子书阅读小程序,微信小程序电子书阅读,微信小程序小说阅读器毕业设计作品
项目背景和意义目的:本课题主要目标是设计并能够实现一个基于微信小程序在线电子书阅读系统,前台用户使用小程序,后台管理使用基Java+MySql技术:通过后台录入电子书信息.书目录信息,用户通过小程序 ...
微信小程序毕业设计基于微信小程序在线电子书阅读系统开题报告
(1)登录功能:注册普通账号登录:也可以直接使用微信登录:登录后可以修改用户的基本信息,也可以退出. (2)资讯功能:后台录入资讯,在微信小程序在线电子书阅读系统的资讯模板展示,用户可以任意浏览资讯列 ...
基于Java+SpringBoot+Thymeleaf+Mysql在线电子书阅读系统学习系统设计与实现
项目背景和意义目的:本课题主要目标是设计并能够实现一个基于web网页的电子书阅读系统,整个网站项目使用了B/S架构,基于java的springboot框架下开发:管理员通过后台录入信息.管理信息,设 ...
基于微信在线电子书阅读小程序设计与实现开题答辩PPT
基于微信在线电子书阅读小程序设计与实现开题答辩PPT

在线电子书创建：MkDocs + Github + ReadTheDocs

目录