(一)MkDocs 学习——快速开始
mkdocs学习笔记系列
- (一)MkDocs 学习——快速开始
- (二)MkDocs学习笔记——撰写文档
- (三)MkDocs学习——配置主题
- (四)MkDocs学习——自定义主题
- (五)MkDocs学习——配置文件
- (六)MkDocs学习——部署文档
- (七)mkdocs学习——其他技巧
MkDocs 中文文档
Overview - MkDocs
概述
MkDocs 是一个用于创建项目文档的 快速, 简单 , 完美华丽 的静态站点生成器. 文档源码使用 Markdown 来撰写, 用一个 YAML 文件作为配置文档.
任意托管
构建完全的静态 HTML 站点 , 可以将它托管到 GitHub pages, Amazon S3 等任意地方.
大量主题
默认包含大量美观的主题. 可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择.
即时预览
内建的开发服务器使你在撰写文档的时候就即时预览. 它甚至能在保存更改时自动载入, 只需刷新浏览器就可以查看更改.
易于配置
可以配置文档主题.
交叉索引
使用 MkDocs 链接语法创建交叉索引.
安装
需要最近版本的 Python 和 Python package manager pip 来安装 MkDocs . 可以通过以下命令查看是否安装了上述依赖:
$ python --version
Python 3.8.2
$ pip --version
pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8)
使用 pip 安装 mkdocs
:
$ pip install mkdocs
mkdocs
已经安装到你的系统. 运行 mkdocs help
以检查是否正确安装,也可查看mkdocs
版本.
$ mkdocs help
mkdocs [help|new|build|serve|gh-deploy] {options}
$ mkdocs --version
mkdocs, version 1.2.0 from /usr/local/lib/python3.8/site-packages/mkdocs (Python 3.8)
简单开始
输入以下命令以开始一个新项目.
$ mkdocs new my-project
$ cd my-project
我们看一下已经创建的初始化项目.
有一个配置文件 mkdocs.yml
, 和一个包含文档源码的 docs
文件夹. 在 docs
文件夹里包含了一个名为 index.md
的文档.
MkDocs 包含了一个内建的服务器以预览当前文档. 控制台切换当前目录到 mkdocs.yml
配置文件相同文件夹, 输入 mkdocs serve
命令以启动内建服务器:
$ mkdocs serve
Running at: http://127.0.0.1:8000/
在浏览器中打开 http://127.0.0.1:8000/ , 你将看到以下页面:
内建服务器支持在配置文件,文档目录或主题发生改变时自动载入并重新生成文档.
编辑 docs/index.md
文件并保存. 刷新浏览器你将看到文档被同步更新.
现在可以开始编辑配置文件 mkdocs.yml
了. 把 site_name
改成其他内容并保存文档.
刷新浏览器你将看到网页标题已发生改变.
添加页面
编辑 doc/index.md
文档, 将默认标题改为 MkLorum
, 刷新浏览器即可看到标题变化.
现在为文档添加第二个页面:
$ curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
要为文档添加导航条, 只需在配置文件中添加导航条需要的标题和排序即可:
site_name: MkLorum
site_url: https://example.com/
nav:- Home: index.md- About: about.md
刷新浏览器即可看到 Home
和 About
导航栏目.
配置主题
可以在配置文件中修改文档主题. 在 mkdocs.yml
中添加如下内容:
site_name: MkLorum
site_url: https://example.com/
nav:- Home: index.md- About: about.md
theme: readthedocs
刷新浏览器即可看到 ReadTheDocs 主题已被应用.
改变图标
默认情况下,MkDocs使用MkDocs favicon图标。要使用不同的图标,请在docs目录中创建一个img子目录,并复制自定义favicon.ico文件到其中。MkDocs将自动检测该文件并将其用作favicon图标。
自动刷新页面显示为
站点生成
我们现在已经可以发布文档了. 通过以下命令生成文档.
$ mkdocs build
该命令创建了一个 site
新目录. 可以通过以下命令浏览该目录内容:
$ ls site
about fonts index.html license search.html
css img js mkdocs sitemap.xml
注意源码被分别输出为 index.html
和 about/index.html
. 主题中的其他文件也被复制到了 site
目录中.
如果你使用 git
等版本控制系统, 你可能不希望提交构建之后的文档到版本库. 在 .gitignore
中添加 site/
即可忽略该目录.
$ echo "site/" >> .gitignore
如果你使用其他版本控制系统则需要查阅相关文档以确定如何忽略指定目录.
一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site
目录中. 在构建命令中添加 --clean
参数即可移除这些文档.
$ mkdocs build --clean
发布
MkDocs 生成的文档只包含静态文件, 因此你可以将文档部署到任意地方. GitHub project pages 和 Amazon S3 是不错的选择. 只需上传 site
目录到你需要发布的位置即可.
(一)MkDocs 学习——快速开始相关推荐
- (三)MkDocs学习——配置主题
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (五)MkDocs学习——配置文件
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (二)MkDocs学习笔记——撰写文档
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (六)MkDocs学习——部署文档
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- (四)MkDocs学习——自定义主题
mkdocs学习笔记系列 (一)MkDocs 学习--快速开始 (二)MkDocs学习笔记--撰写文档 (三)MkDocs学习--配置主题 (四)MkDocs学习--自定义主题 (五)MkDocs学习 ...
- 150页书籍《PyTorch 深度学习快速入门指南》附PDF电子版
为什么说是极简教程,首先本书只涵盖了150页.内容比较精简,特别适合作为 PyTorch 深度学习的入门书籍.为什么这么说呢?因为很多时候,一份厚重的书籍往往会削弱我们学习的积极性,在学习一门新的语言 ...
- 深度学习快速参考 | iBooker·ApacheCN
原文:Deep Learning Quick Reference 协议:CC BY-NC-SA 4.0 自豪地采用谷歌翻译 不要担心自己的形象,只关心如何实现目标.--<原则>,生活原则 ...
- 使用强化学习快速让AI学会玩贪食蛇游戏(轻量级二十分钟训练+代码)
如何让AI玩会贪食蛇,甚至比你厉害 概述 构建问题(强化学习求解的一般步骤) 环境 动作定义 状态定义 奖励设计 训练奖励值收敛图 采用第4种状态定义方法 初步训练效果 最终训练效果 模型泛化迁移能力 ...
- Python深度学习-快速指南
Python深度学习-快速指南 (Python Deep Learning - Quick Guide) Python深度学习-简介 (Python Deep Learning - Introduct ...
最新文章
- 如何创建企业转型路线图
- linux tee 命令 输出的同时写入文件
- 8张图带你深入理解Java
- 编译其他mysql客户程_mysql编译模块
- glib 2.0 arm linux,为ARM编译Glib
- corda_使用Spring WebFlux从Corda节点流式传输数据
- PL/SQL 08 异常 exception
- objective-C CollectionView 加深(添加注册头部View)
- GCD(Grand Central Dispatch)和Block 使用-浅析
- linux勒索病毒如何恢复数据,勒索病毒和相应的解密工具
- MATLAB 绘图函数总结
- android 5.0 ble demo,Android BLE蓝牙例子(包括android版Lightblue)实例源码
- EPLAN插入符号为空的解决方法
- ps软件抠图、去除图片背景
- A good article :csi cameras on the TX2 (the easy Way)
- USB billboard
- c++ 箭头符号怎么打_C++编程基础知识二
- 小程序开发之瀑布流布局
- VSCODE+EIDE开发STM32
- 写代码这条路,能走多远?阿里算法专家告诉你