MkDocs+Github搭建个人博客

写在前面

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

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

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

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


本博客所需基础:
  • markdown语法
  • 命令行操作
  • python环境
  • github使用

什么是MkDocs

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


搭建本地页面

安装

首先,请确保你的电脑已安装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

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


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

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