【小沐学Python】Python实现在线电子书（MkDocs + readthedocs + github + Markdown）
文章目录
- 1、简介
- 2、安装
- 3、创建新项目
- 4、添加页面
- 5、编辑导航页
- 6、设置主题
- 7、更改图标图标
- 8、构建网站
- 9、部署
- 9.1 准备github项目
- 9.2 注册登录Read the Docs
- 9.3 导入github项目到 Read the Docs
- 10、Markdown语法
- 10.1 横线
- 10.2 标题
- 10.3 段落
- 10.4 文字高亮
- 10.5 换行
- 10.6 斜体、粗体、删除线
- 10.7 引用
- 10.8 列表
- 10.9 代码块
- 10.11 链接
- 10.12 锚点
- 10.13 图片
- 10.14 表格
- 10.15 复选框
- 10.16 表情
- 10.17 diff语法
- 10.18 字符转义
- 11、其他
- 结语
1、简介
官网地址：
https://www.mkdocs.org/
MkDocs是一个快速、简单、华丽的静态网站生成器，适用于构建项目文档。文档源文件以Markdown编写，并使用一个YAML文件来进行配置。
- 在任何地方部署
MkDocs生成完全静态的HTML网站，你可以将其部署到GitHub pages、Amzzon S3或你自己选择的其它任意地方。 - 很棒的主题
MkDocs有一堆很好看的主题。 官方内置了两个主题：mkdocs和readthedocs，也可以从MkDocs wiki中选择第三方主题，或者自定义主题。 - 实时预览你的网站
当你写作时，内置的开发服务可以帮助你预览显示效果。当文档有改动时，甚至还可以自动载入并刷新你的浏览器。 - 易于定制
通过自定义主题，让你的项目文档以你希望的方式呈现。
2、安装
要安装 MkDocs，请从命令行运行以下命令：
pip install mkdocs
3、创建新项目
入门非常简单。若要创建新项目，请运行以下命令 命令行中的命令：
mkdocs new my-project
cd my-project
（1）有一个名为mkdocs.yml的配置文件，
（2）以及一个名为docs的文件夹，该文件夹将包含您的文档源文件index.md。
（3）现在，my-project该文件夹仅包含一个名为index.md 的文档页面。
MkDocs 带有一个内置的开发服务器，可让您预览文档 当你在工作时。确保您与配置文件位于同一目录中，然后通过运行以下命令启动服务器：
mkdocs serve
在浏览器中打开，您将看到默认 正在显示的主页：http://127.0.0.1:8000
开发服务器还支持自动重新加载，并将重新构建您的文档 只要配置文件、文档目录或主题中的任何内容 目录更改。
在您选择的文本编辑器中打开文档，将 初始标题为 ，然后保存更改。您的浏览器将 自动重新加载，您应该会立即看到更新的文档。
现在尝试编辑配置文件mkdocs.yml：将site_name设置更改为自己的，并保存文件。
site_name: MkLorum
site_url: https://example.com/
site_name和site_url配置 选项是配置文件中唯一必需的两个选项。
浏览器预览如下：
4、添加页面
现在向文档添加第二页：
将在线的一个文件下载为第二个页面。
curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
当然我们也可以自己编辑这个关于页about.md：
@[toc]# 《海的女儿》
小人鱼为了能和自己所爱的陆地上的王子在一起．用自己美妙的嗓音和三百年的生命换来了巫婆的药酒，于是，她有了一双美丽的脚，每走一步就像走在碎玻璃上一样疼痛。眼看着王子和别人结婚，她宁可牺牲自己的生命，也要为王子祝福。# 《丑小鸭》
丑小鸭历经千辛万苦、重重磨难之后变成了白天鹅，那是因为它心中有着梦想。# 《屎壳郎》
皇宫马厩的一只屎壳郎竟然要求和皇帝的战马享有一样的待遇——钉上金掌。为此，他不惜游历一番，以证明自己和那匹马一样，是个不可小看的人物。在他最为得意，认为梦想成真的那刻．却被皇帝压在马鞍底下。# 《野天鹅》
这是一场善与恶的斗争。艾丽莎是个柔弱的女子，但她却战胜了比她强大得多、有权有势的王后和主教。救出了被王后的魔法变成天鹅的十一位哥哥。她可以成功靠的是她的勇气、决心和毅力。面对荨麻的刺痛和一年不能说话的痛苦，这需要多大的勇气去面对啊。即使面对主教对她的诬陷和把她烧死的惩罚，她也没有放弃，一直坚持到最后一分钟，终于完成了她的工作。
浏览器预览如下：
5、编辑导航页
由于我们的文档网站将包含一些导航标题，因此您可能需要 编辑配置文件mkdocs.yml，并添加有关订单、标题和 通过添加导航设置在导航页眉中嵌套每个页面：
site_name: 爱看书的小沐的笔记
site_url: https://小沐.com/
nav:- 首页: index.md- 关于: about.md
保存更改，浏览器预览后，您现在将看到一个导航栏。
6、设置主题
现在更改配置文件以更改文档的显示方式 更改主题theme。
MkDocs 包括两个内置主题（mkdocs 和 readthedocs）。同时，许多第三方 主题也可供选择。编辑文件mkdocs.yml，添加主题设置：
site_name: 爱看书的小沐的笔记
site_url: https://小沐.com/
nav:- 首页: index.md- 关于: about.md
theme: readthedocs
保存更改，您将看到正在使用的 ReadTheDocs 主题。
主题还可以支持代码高亮、键盘快捷键、视觉样式、区域设置等。
site_name: 爱看书的小沐的笔记
site_url: https://小沐.com/
nav:- 首页: index.md- 关于: about.md
theme: name: mkdocshighlightjs: truehljs_languages:- yaml- rust- pythonlocale: zh_CNmarkdown_extentions:- admonitionplugins:- searchextra_css:- resources/css/extra.css
7、更改图标图标
默认情况下，MkDocs使用MkDocs favicon图标。 要使用不同的图标，请在docs_dir中创建一个img子目录，并将自定义的favicon.ico文件复制到该目录。 MkDocs将自动检测并使用该文件作为你的favicon图标。
浏览器预览如下：
8、构建网站
生成文档：
mkdocs build
# or
mkdocs build --clean
生成的网站部署文件夹如下：
9、部署
你刚刚生成的文档站点仅使用静态文件，因此你几乎可以在任何地方托管它。 GitHub project pages和Amazon S3是个很不错的托管地方，具体取决于你的需求。 将整个site目录的内容上传到你托管网站的地方，然后就完成了。 有关常见主机的具体说明，请参阅部署文档页面。
9.1 准备github项目
登录github，创建一个公开项目mkdocsDemo：
在项目根目录打开git bash执行如下命令将博客push到新创建的github仓库：
git init
git branch -M main
git remote add origin https://github.com/fxyublib/mkdocsDemo.git
git pull origin main
git add --all
git commit -m "mkdocs demo"
git push -u origin main
9.2 注册登录Read the Docs
Read the Docs注册地址：https://readthedocs.org/accounts/signup/
9.3 导入github项目到 Read the Docs
点击“导入一个项目”，点击添加创建的github项目，点击“下一页”
点击【管理】，进入高级设置，设置文档类型为Mkdocs，Python解释器选择CPython 2.x， 点击最下面的“Save”按钮：
接着，点击按钮“Build version”，
可以自动从GitHub下载项目代码，并编译成网站页面，
浏览器预览网址：
只要本地提交修改到GitHub项目，就会自动构建更新文档。
10、Markdown语法
10.1 横线
***、—、___可以显示横线效果，注意横线前后要加一个空行。
10.2 标题
# 一级标题 <h1>一级标题</h1>
## 二级标题 <h2>二级标题</h2>
### 三级标题 <h3>三级标题</h3>
#### 四级标题 <h4>四级标题</h4>
##### 五级标题 <h5>五级标题</h5>
###### 六级标题 <h6>六级标题</h6>
一级标题和二级标题也可以分别通过在标题文字下面添加==和–来实现。=和-个数大于等于2就可以。
一级标题
==二级标题
--
10.3 段落
分段使用空行就行。
10.4 文字高亮
可以使用一对反引号来突出部分文字，也可以通过一对==来实现：
# （1）
==高亮==：typora中的markdown扩展语法，
需要开启才可使用# （2）
`linux`
10.5 换行
在上一行文本后面补两个空格（大于2个空格），
这样下一行的文本就换行了。
在两行文本直接加一个空行会分段。
<p>第一行<br>第二行</p>
10.6 斜体、粗体、删除线
粗体和斜体建议使用星号。
Markdown语法 HTML语法
*斜体1* <em>斜体</em>
_斜体2_
**粗体1** <strong>粗体</strong>
__粗体2__
这是一个 ~~删除线~~
***斜粗体1*** <strong><em>斜粗体</em></strong>
___斜粗体2___
__*斜粗体3*__
**_斜粗体4_**
***~~斜粗体删除线1~~***
~~***斜粗体删除线2***~~
Markdown没有下划线语法 <u>下划线</u>
10.7 引用
在引用段落前面添加符号>。
引用嵌套：
> 不要回答！
>> 不要回答！！
>>> 不要回答！！！
10.8 列表
- 无序列表
无序列表可以使用短横杠 (-), 星号 (*), 或者加号 (+)
* 不要回答！
- 不要回答！
+ 不要回答！
<ul>
<li>不要回答！</li>
<li>不要回答！！</li>
<li>不要回答！！！</li>
</ul>
- 多级无序列表
* 不要回答！* 不要回答！！
- 有序列表
在数字后面加一个点，再加一个空格。
我：
1. 不要回答！
2. 不要回答！
3. 不要回答！
<ol>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ol>
- 多级有序列表
1. 不要回答！1. 不要回答！
2. 不要回答！！！
10.9 代码块
缩进四个空格或一个Tab制表符。
在列表中时，缩进八个空格或两个Tab制表符。
三个反引号后面加上编程语言的名字（也可以不加），另起一行开始写代码，最后一行再加上三个反引号。
print("hello world")
要将文字表示为代码，用单个反引号将其括起来。
`hello world，爱看书的小沐！`
hello world，爱看书的小沐！
html语法：
<code>Linux</code>
如果代码块内有反引号，可以使用两个反引号来转义：
要将文字表示为代码，用单个反引号将其括起来。
10.11 链接
URL中如果有空格，使用%20进行URL编码。链接地址可以是URL链接，也可以是本地文件路径。
[CSDN地址](https://blog.csdn.net/123456"悬停显示：我的CSDN博客")<a href="https://blog.csdn.net/123456" title="悬停显示：我的CSDN博客">CSDN地址</a>[我的文档](./example/testfile.md)
也可以直接在URL或者邮箱地址两边加尖括号将地址快速转化为链接：
<https://blog.csdn.net/123456>
- 链接格式化
[](https://blog.csdn.net/123456)<a href="https://blog.csdn.net/123456" ><img src="https://img-blog.csdnimg.cn/20210612184436459.png" alt="csdn" title="我的CSDN"></a>
- 参考链接
参考链接包括两部分：与文本保持内联的部分；存储在文件其他地方以使文本易于阅读的部分。
[blog]:https://123456.github.io/ "我的博客"[我的博客][blog]
# 或者
[blog][]
10.12 锚点
每一个标题都是一个锚点，和HTML的锚点（#）类似，可以用它来实现页面内跳转。
[目录](#目录 "悬停显示")
<a href="#目录" title="悬停显示">目录</a>
也可以使用和参考链接一样的方式：
[文章目录]: #目录[目录][文章目录]
[文章目录][]
10.13 图片
alt和title对应HTML中的alt和title属性（都可省略）
<img src="https://img-home.csdnimg.cn/images/20201124032511.png" alt="CSDN" title="CSDN logo">
10.14 表格
| 表头1 | 表头2 | 表头3 |
| ----- | ----- | ----- |
| value | value | value |
| value | value | value |
- 指定对齐方式
| 左对齐 | 居中 | 右对齐 |
| :---- |:---------:| -----:|
| left | entered | right |
| left | centered | right |
| left | centered | right |
表格单元中的内容可以可以使用其Markdown语法，如： 加粗、斜体、删除线等
10.15 复选框
- [x] Python
- [ ] Java
10.16 表情
Github的Markdown语法支持添加emoji表情，每个表情对应一个符号码（两个冒号包围的字符），比如
【小沐学Python】Python实现在线电子书（MkDocs + readthedocs + github + Markdown）相关推荐
- 【小沐学Python】Python实现在线电子书（Sphinx + readthedocs + github + Markdown）
文章目录 1.简介 2.安装 3.创建测试工程 4.项目文件结构 5.编译为本地文件 6.编译为http服务 7.更改样式主题 8.支持markdown 9.修改文档显示结构 10.项目托管到gith ...
- 【小沐学python】（一）Python开发准备
<爱看书的小沐和爱发呆的戈戈>第一季 目录 1.<出生篇> 1.1 python历史背景 1.2 python职业方向 1.3 python语言排名 2.<巡山篇> ...
- 【小沐学C#】WPF中嵌入web网页控件（WebBrowser、WebView2、CefSharp）
文章目录 1.简介 1.1 WPF简介 1.2 WPF 体系结构 1.3 WPF入门开发 2.WebBrowser 2.1 WebBrowser特点 2.2 WebBrowser常用的属性.方法和事件 ...
- 【小沐学Unity3d】Unity3d导入3D模型
文章目录 1.简介 1.1 标准文件格式 1.2 专有文件格式 1.3 从 Autodesk® 3ds Max® 导入对象 1.4 从 Blender 导入对象 2.测试 2.1 新建项目 2.2 导 ...
- 【小沐学Python】Python实现在线英语翻译功能
文章目录 1.简介 2.在线翻译接口 2.1 Google Translate API 2.2 Microsoft Translator API 2.2.1 开发简介 2.2.2 开发费用 2.2.3 ...
- 【小沐学C++】C++ OpenSSL库编译及使用（VS2017，Python）
文章目录 1.简介 2.下载openssl 2.1 下载openssl源码(github) 2.2 下载openssl源码(官网压缩包) 2.3 下载openssl二进制库 2.4 下载perl工具 ...
- 【小沐学NLP】Python实现聊天机器人（ELIZA）
- 【小沐学NLP】Python实现图片文字识别
- 【小沐学NLP】Python实现词云图
最新文章
- C#中String对象转换为Font对象的方法
- 查找文本（grep）
- c# 遍历文件夹深度,C＃遍历文件夹，直到找到正确的文件
- AtCoder AGC036E ABC String
- javascript中0级DOM和2级DOM事件模型浅析
- 使用ST05分析IBASE search identical select
- NET问答: 如何将 ASP.NET Core WebAPI 中抛出的异常封装成对象？
- 树莓派python gpio 模仿iic_Adafruit的树莓派教程：GPIO配置
- linux无法找到网卡6,CentOS 6/7克隆主机网卡无法启动解决
- 用Windows Live Writer在博客园发布Post
- mysql 自定义排序函数_MySQL自定义排序函数FIELD()
- win11的drivers文件可以删除吗 windows11drivers文件是否可以删除的详细介绍
- java 封装log4j_Java项目 切片实现log4j的终极封装
- mybatis的mysql分页_使用MyBatis+Mysql实现分页的插件PageInfo使用介绍
- VS2015/VS2017必须在WINDOWS10上安装
- 酒店管理系统c语言课程设计,基于C语言的酒店管理系统课程设计.doc
- 互联网巨头竞逐客户端软件
- 寒霜3引擎再造经典极品飞车18
- 详解区块链（很详很长）
- etoken显示连接服务器失败,etoken