MkDocs+Github搭建个人博客

写在前面

在尝试过Hugo、Jekyll等博客框架后，我最终选择了MkDocs+Github的方案，主要出于以下几点考虑：

1. 博客内容可基于Markdown写作，不需要掌握html等其它语法。

2. 发布简单，只需几个命令就可以部署好本地框架，更新也很方便。

3. 页面简洁，可能对追求美观的用户而言还有提升空间，但对我完全足够了。

• markdown语法
• 命令行操作
• python环境
• github使用

什么是MkDocs

MkDocs是一个静态网站生成器，它专门为构建项目文档而设计。它的核心优势在于速度、简单性和美观度。想象一下，你有一个项目，需要为它创建文档，而MkDocs能帮你轻松搞定这一切。

• 官网地址：https://www.mkdocs.org/
• 新手教程：https://www.mkdocs.org/getting-started/
• 用户手册：https://www.mkdocs.org/user-guide/

搭建本地页面

安装

首先，请确保你的电脑已安装python环境，之后就可以基于pip安装mkdocs:

pip install mkdocs

接下来运行mkdocs --version确认安装是否成功。

创建站点

运行以下命令：（dir_name可以自由命名）

mkdocs new dir_name

这行命令将会在当前目录下创建一个新文件夹dir_name,文件夹中包括：

• 子目录docs: 博客的核心内容（.md文件）就包含在此目录下
• 配置文件mkdocs.yml:暂时不用动它

然后进入dir_name文件夹，运行mkdocs serve，命令行中会显示Serving on http://...,即可在本地访问该站点。

配置文件修改

可以通过编辑mkdocs.yml来修改页面格式，示例如下：

site_name: Elsy's Blog
theme:
        name: readthedocs
nav:
        - 主页: index.md     
        - 关于: aboutme.md

使用Github发布在线网页

1. 在dir_name下运行mkdocs build,这会生成一个新文件夹site，其中包含了静态站点的页面内容。

2. 在Github上新建一个仓库。

3. 将本地dir_name文件夹与Github新建仓库连接。

4. 在dir_name下运行mkdocs gh-deploy，成功运行后命令行会显示"Your documentation should shortly be available at : ..."

网络不好时可能需要多运行几次,而且很可能有点延迟2333

5. 更新网页：在本地docs文件夹下编辑完md文档后，命令行中执行mkdocs gh-deploy即可

版权声明：本文采用知识共享 4.0 许可证 (署名-非商业性使用-禁止演绎)

热门相关：最狂神医赘婿   神医钓王   神君之上   漂流欲室   超萌迷糊妻：BOSS大人别这样