用Python写静态博客

MkDocs

使用Markdown的项目文档。

概观

MkDocs是一个快速简单彻头彻尾的华丽静态站点生成器,旨在构建项目文档。文档源文件以Markdown编写,并使用单个YAML配置文件进行配置。

主持任何地方

MkDocs构建完全静态的HTML网站,您可以在GitHub页面,Amazon S3或您选择的任何其他地方托管。

很棒的主题

MkDocs有一堆很好看的主题。在内置主题:mkdocs和readthedocs之间进行选择,在MkDocs wiki中选择第三方主题之一,或者构建自己的主题。

在您工作时预览您的网站

内置的开发服务器允许您在编写文档时预览文档。每当您保存更改时,它甚至会自动重新加载并刷新您的浏览器。

易于定制

通过自定义主题,让您的项目文档以您希望的方式查找。


(假设大家已经安装Python)

安装MkDocs

mkdocs使用pip 安装包:

pip install mkdocs

您现在应该mkdocs在系统上安装该命令。运行mkdocs --version以检查一切正常。

$ mkdocs --version
mkdocs, version 0.15.3

入门

入门非常简单。

mkdocs new my-projectcd my-project

花一点时间来回顾一下为您创建的初始项目。

有一个名为的配置文件mkdocs.yml,以及一个名为的文件夹 docs,其中包含您的文档源文件。现在,该docs 文件夹只包含一个名为的文档页面index.md

MkDocs附带一个内置的开发服务器,可以让您在处理文档时预览文档。确保您与mkdocs.yml 配置文件位于同一目录中,然后通过运行以下mkdocs serve 命令启动服务器:

$ 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

http://127.0.0.1:8000/在浏览器中打开,您将看到显示的默认主页:

dev-server还支持自动重新加载,并且只要配置文件,文档目录或主题目录中的任何内容发生更改,都将重建文档。

docs/index.md在您选择的文本编辑器中打开文档,将初始标题更改为MkLorum,并保存更改。您的浏览器将自动重新加载,您应该立即看到更新的文档。

现在尝试编辑配置文件:mkdocs.yml。将site_name设置更改 为MkLorum并保存文件。

site_name: MkLorum

您的浏览器应立即重新加载,您将看到新的站点名称生效。

添加页面

现在在文档中添加第二页:

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

由于我们的文档站点将包含一些导航标题,您可能需要编辑配置文件,并通过添加pages 设置在导航标题中添加有关每个页面的顺序,标题和嵌套的一些信息:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md

保存更改,现在您会看到一个导航栏HomeAbout 项目左侧以及SearchPreviousNext右边的项目。

尝试菜单项并在页面之间来回导航。然后点击 Search。将出现一个搜索对话框,允许您搜索任何页面上的任何文本。请注意,搜索结果包括网站上每次出现的搜索字词,并直接链接到搜索字词所在页面的部分。您无需付出任何努力或配置即可完成所有这些工作!

主题我们的文档

现在更改配置文件以通过更改主题来更改文档的显示方式。编辑mkdocs.yml文件并添加theme设置:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

保存更改,您将看到正在使用的ReadTheDocs主题。

更改Favicon图标

默认情况下,MkDocs使用MkDocs favicon图标。要使用其他图标,请img在您的子目录中创建一个子目录,docs_dir然后将自定义favicon.ico文件复制到该目录。MkDocs将自动检测并使用该文件作为您的favicon图标。

建立网站

那看起来不错。您已准备好部署MkLorum 文档的第一个过程。首先构建文档:

mkdocs build

这将创建一个名为的新目录site。看一下目录:

$ ls site
about  fonts  index.html  license  search.html
css    img    js          mkdocs   sitemap.xml

请注意,您的源文档已输出为两个名为index.html和的HTML文件 about/index.html。您还有各种其他媒体已site作为文档主题的一部分复制到目录中。你甚至有一个sitemap.xml文件和mkdocs/search_index.json

如果您正在使用源代码控制,例如git您可能不希望将文档构建检查到存储库中。添加包含 site/在您的.gitignore文件中的行。

echo "site/" >> .gitignore

如果您正在使用其他源代码控制工具,则需要检查其文档,了解如何忽略特定目录。

一段时间后,文件可能会从文档中删除,但它们仍将驻留在site目录中。要删除这些陈旧文件,只需mkdocs 使用--clean开关运行即可。

mkdocs build --clean

其他命令和选项

还有其他各种命令和选项。有关命令的完整列表,请使用--help标志:

mkdocs --help

要查看给定命令上可用的选项列表,请使用--help带该命令的标志。例如,要获取该build命令可用的所有选项的列表,请 运行以下命令:

mkdocs build --help

部署

您刚刚构建的文档站点仅使用静态文件,因此您几乎可以在任何地方托管它。GitHub项目页面和Amazon S3可能是很好的托管选项,具体取决于您的需求。将整个site目录的内容上传到您托管网站的任何地方,然后您就完成了。有关许多常见主机的具体说明,请参阅部署您的文档页面。

获得帮助

要获得有关MkDocs的帮助,请使用讨论组,GitHub问题或#mkdocsfreenode上的MkDocs IRC频道。


有兴趣的朋友可以阅读原文跳转到MkDocs网站浏览

本文分享自微信公众号 - 萌海无涯(mhwyhtwa)

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2019-07-20

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏明丰随笔

对称加密和解密

.NET提供了一组类型来实现对称加密和解密。这些类型拥有共同的基类SymmetricAlgorithm,如图所示。

9420
来自专栏汪宇杰博客

关于WinForms的跨显示器DPI自适应

WinForms 是运行在Windows上的传统.NET桌面应用技术框架。由于历史原因,它对高DPI以及跨不同DPI屏幕的支持有些问题,本文将探索尽可能的解决方...

12420
来自专栏卯金刀GG

【IIS7.5服务器问题】未能加载文件或程序集“Oracle.DataAccess”或它的某一个依赖项.试图加载格式不正确的程序

NET:Microsoft Visual Studio 2010 + .NET Framework 3.5

52130
来自专栏Eureka伽罗的技术时光轴

如何使用DotfuscatorPro_4.9对软件进行加密

DotfuscatorPro_4.9可以防止你的.NET软件被反编译,可以在一定程度上防止你的软件被反编译。现在很多软件都有被反编译的现象,虽然不能做到百分百的...

6620
来自专栏DotNet程序园

《ASP.NET Core 高性能系列》致敬伟大的.NET斗士甲骨文!

 三年前,曾写过一篇文章:从.NET和Java之争谈IT这个行业,当时遭到某些自认为懂得java就了不起的Javaer抨击,

14320
来自专栏微卡智享

.net Core中Vue.js里使用Element-UI

每次自己尝试用新东西时,所花的时间真的不是一般的多,以前刚开始学Vue的时候用VSCode直接引入ElementUI比较简单,这次项目因为用.net Core生...

13630
来自专栏.Net框架学苑

.NET开发框架(八)-服务器集群之网络负载平衡(视频)

【视频教程在文章底部】,本文讲解Windows服务器集群的网络负载平衡NLB的作用,以及在.NET开发框架的架构设计中,如何应用NLB与ARR,使用它们各有什么...

11840
来自专栏架构师

c#基础系列1---值类型和引用类型

不知不觉已经踏入坑已10余年之多,对于c#多多少少有一点自己的认识,写出来渴求同类抨击,对自己也算是个十年之痒的一个总结。

8310
来自专栏DotNet Core圈圈

【译】.NET Core 3.0 发布小尺寸 self-contained 单体可执行程序

.NET Core 提供的发布应用程序选项 self-contained 是共享应用程序的好方法,因为应用程序的发布目录包含所有组件、运行时和框架。您只需要告诉...

12020
来自专栏网站漏洞修复

网站被攻击怎么办 如何查找网站漏洞攻击源

很多企业网站被攻击,导致网站打开跳转到别的网站,尤其一些彩票等非法网站上去,甚至有些网站被攻击的打不开,客户无法访问首页,给客户造成了很大的经济损失,很多客户找...

18830

扫码关注云+社区

领取腾讯云代金券

年度创作总结 领取年终奖励