【极简教程】用 Mkdocs 库发布你的网站
Mkdocs
大家应该对这样页面风格的网站并不陌生:
这是Keras文档的中文文档网站, 还有大名鼎鼎的爬虫库Selenium的中文文档
以及许许多多的知名库/包的官方网站, 都是这样的页面风格。 这是因为, 他们都出自一个python库: Mkdocs 之手。 这个库就是支持以Markdown语法(名字也是mkdocs)来写文档, 并帮助你流水线般地生产成网页。
正如markdwon语法的初衷是希望人们更专注于内容而非格式, Mkdocs也是如此。 你可以用Django, 用Flask 生成更精美的网页, 但没有必要。 因此, Mkdocs来负责把文档生成为网页, 你则专注于内容, 而非排版,布局, 调色…
这篇博客就用最简单的教程讲解下从零上手Mkdocs的简单实用。
安装 和 起步
首先, 用 pip install mkdocs
命令下载Mkdocs库。
我用的是 Pycharm, 就以此为例了。
随便新建一个工程:我随便起了一个名字Mybook,这个随意, 在pycahrm下打开。
点击Pycharm页面下方的terminal或者Alt+F12, 唤起命令行终端。
在命令行输入mkdocs nwe my-project
, 其中my-project
是你自定义的项目名,得到:
目录则变为:
这是mkdocs自带的默认文档页面, 现在我们可以看看他对应生成的html文件长啥样:
先进入项目目录下: 输入cd my-project
继续在命令行输入: mkdocs serve
, 得到效果如下:
OK, 现在已经可以通过打开 http://127.0.0.1:8000/ 来看看文档网页了,下图就是Mkdocs的默认页面。
显然,我们可以通过修改项目下的内容, 对网页进行修改, 例如:
- 修改网页名称:
打开mydocs.yml
文件, 修改site-name
:
你会发现,刚刚的网页马上对应的修改了。 注意, 这个过程中不需要你重新启动服务器什么的,这是自动检测到的, 非常方便, 所见即所得。
同理, 可以通过修改.md文件来改进内容什么的, 这里先不赘述, 可以取官方教程里看看, 我们现在要完成把它发布到网上,而非自娱自乐。
发布到Github Pages
首先,在github网站上新建一个库,
将其clone到本地。 然后,**把刚刚my-project下的所有文件复制到B417_blogs目录下。
在pycharm中打开 B417_blogs, 目录如图:
我们通过git, 把我们的操作commit并push到github上(这个网上教程很多, 就不赘述了)。我用的是github桌面版进行同步。
回到pycharm下, 按Alt +F12打开命令行终端, 输入mkdocs gh-deploy
:
等待mkdocs自动把文档生成网页文件(html,css等, 存放在site目录下)同步到github。 完成后为:
此时,点击该网址, 就得到和刚刚在 127.0.0.1下看到的一样的网页啦, 但区别在于, 这次的是发布在了外网上, 所有人都能通过网址进行访问。 https://TianLin0509.github.io/B417_blogs/
结束
想把自己的文档发布成网页, 最简单的流程就是用mkdcos, 然后通过markdown语法书写。 在自己本地端确认网页后, 再通过github pages发布即可。
后续修改
已经发布到github pages的网页, 如果还想修改,仍在pycharm的命令行下, 输入 mkdocs build --clean
(很重要!否则页面看上去没有修改)来清除过期的页面。
然后再次运行
mkdocs gh-deploy
发布到外网。
latex 输入
比如我们的博客要发布到github pages中, 需要有许多的数学公式。 如何让本地的markdown支持?
- 下载相关包
在pycharm命令行输入
pip install pymdown-extensions
- 修改mcdocs.yml文件
extra_javascript:- javascripts/config.js- https://polyfill.io/v3/polyfill.min.js?features=es6- https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.jsmarkdown_extensions:- pymdownx.arithmatex:generic: true
如上, 加入下面两段代码即可。
然后创建javascripts
文件夹, 并在文件夹下新建config.js
文件。
window.MathJax = {tex: {inlineMath: [["\\(", "\\)"]],displayMath: [["\\[", "\\]"]],processEscapes: true,processEnvironments: true},options: {ignoreHtmlClass: ".*|",processHtmlClass: "arithmatex"}
};
然后发现, 在markdown文档中可以直接使用latex语法输入公式了。
原攻略参考官方网站: https://squidfunk.github.io/mkdocs-material/reference/mathjax/
【极简教程】用 Mkdocs 库发布你的网站相关推荐
- 《Kotlin极简教程》第1章 Kotlin简介
第1章 Kotlin简介 最新上架!!!< Kotlin极简教程> 陈光剑 (机械工业出版社) 可直接打开京东,淘宝,当当===> 搜索: Kotlin 极简教程 http://ww ...
- ES6 极简教程(ES6 Tutorial) 文 / 东海陈光剑
ES6 极简教程(ES6 Tutorial) 文 / 东海陈光剑 ECMAScript简介 JavaScript是ECMAScript的实现和扩展,由ECMA(一个类似W3C的标准组织)参与进行标准化 ...
- 《Kotin 极简教程》第14章 使用 Kotlin DSL
第14章 使用 Kotlin DSL 最新上架!!!< Kotlin极简教程> 陈光剑 (机械工业出版社) 可直接打开京东,淘宝,当当===> 搜索: Kotlin 极简教程 htt ...
- 《Kotin 极简教程》第9章 轻量级线程:协程(2)
<Kotlin极简教程>正式上架: 点击这里 > 去京东商城购买阅读 点击这里 > 去天猫商城购买阅读 非常感谢您亲爱的读者,大家请多支持!!!有任何问题,欢迎随时与我交流~ ...
- 前端自动化测试框架 Jest 极简教程
前端自动化测试框架 Jest 极简教程 Delightful JavaScript Testing. https://jestjs.io Jest是由Facebook发布的开源的.基于Jasmine的 ...
- 《 Kotlin极简教程 》陈光剑 编著(机械工业出版社,2017.9)
<Kotlin极简教程> 点击这里 > 去京东商城购买阅读 点击这里 > 去天猫商城购买阅读 正式预售: < Kotlin极简教程 > image.png imag ...
- 【编程实践】Google Guava 极简教程
前言 Guava 工程包含了若干被 Google 的 Java 项目广泛依赖 的核心库,我们希望通过此文档为 Guava 中最流行和最强大的功能,提供更具可读性和解释性的说明. 适用人群 本教程是基础 ...
- 《Node.js 极简教程》 东海陈光剑
Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境. Node.js 使用了一个事件驱动.非阻塞式 I/O 的模型,使其轻量又高效. https://nodejs. ...
- CentOS安装使用.netcore极简教程(免费提供学习服务器)
本文目标是指引从未使用过Linux的.Neter,如何在CentOS7上安装.Net Core环境,以及部署.Net Core应用. 仅针对CentOS,其它Linux系统类似,命令环节稍加调整: 需 ...
最新文章
- 【译】如何精确判断最终用户响应时间过长的原因?
- html怎么将页面放到中间,HTML – 如何将div放在另外两个(左和右)div之间?
- 今天开始参加ORACLE PERFORMANCE TUNING 原厂培训.
- 20170908-构建之法:现代软件工程-阅读笔记
- 银联支付java代码实现_Java后端实现三方支付集成支付宝、微信、银联、光大、邮政支付...
- java session 例子_JavaWeb——HttpSession常用方法示例
- JAVA作业 随机抽取
- Nifi从入门到精通(一)之 数据存储
- 电脑遇到某某dll文件缺失、某某OCX缺失怎么办?
- Ubuntu修改/home下各目录为英文
- PHP 获取格式化的日期和时间
- mysql判断当前日期是否为节假日_java 判断日期是否是节假日
- 这篇不讨好任何人的回忆录,记录了我从双非学校到BAT/TMD六offer的原因
- C++统计代码执行耗时
- 泵站和水闸无人值守系统
- React + Koa2打造『官方管理后台』10 总结
- matplotlib——pyplot和pylab区别
- 美元霸权·《看懂世界格局的第一本书·2》
- linux定时删除文件,如何操作Linux 定时删除指定目下N天前的文件
- C语言函数大全--c开头的函数之复数篇
热门文章
- WebView显示网页出现Uncaught TypeError: Cannot call method 'getItem' of null异常
- Nextcloud 内部服务器错误解决
- 读《人生不设限》 有感
- 运城达内java毕业生分享如何提高网站优化效率
- AndroidStudio 使用ADB命令进行 WIFI调试
- 算法复杂度及渐进符号
- android软件开发之webView.addJavascriptInterface循环渐进【一】
- 如何把生活过程升级打怪?
- JAVAWeb学习笔记2020/5/15——JavaScript高级笔记
- 额温枪为什么老是测不准 额温枪调节方法