MkDocs+Github搭建个人博客
写在前面
在尝试过Hugo、Jekyll等博客框架后,我最终选择了MkDocs+Github的方案,主要出于以下几点考虑:
-
博客内容可基于Markdown写作,不需要掌握html等其它语法。
-
发布简单,只需几个命令就可以部署好本地框架,更新也很方便。
-
页面简洁,可能对追求美观的用户而言还有提升空间,但对我完全足够了。
本博客所需基础:
- 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发布在线网页
-
在
dir_name
下运行mkdocs build
,这会生成一个新文件夹site
,其中包含了静态站点的页面内容。 -
在Github上新建一个仓库。
-
将本地
dir_name
文件夹与Github新建仓库连接。 -
在
dir_name
下运行mkdocs gh-deploy
,成功运行后命令行会显示"Your documentation should shortly be available at : ..."
网络不好时可能需要多运行几次,而且很可能有点延迟2333
- 更新网页:在本地docs文件夹下编辑完md文档后,命令行中执行
mkdocs gh-deploy
即可
版权声明:本文采用知识共享 4.0 许可证 (署名-非商业性使用-禁止演绎)
热门相关:最狂神医赘婿 神医钓王 神君之上 漂流欲室 超萌迷糊妻:BOSS大人别这样