30分钟(零成本)快速搭建markdown个人github博客

零成本-30分钟快速搭建markdown个人github博客

摘要：本文以mkdocs 开源文档工具 + markdown预发编写文档，最终生成简易个人github博客。最终效果如：https://smilemrlee.github.io/

1.准备工作

• 学习markdown 语法，写好文档必备
• 学习mkdocs 基本原理和规范，以便合理规划好建站导航
• 安装好python或安装好homebrew

2.安装mkdocs

2.1 phyton原生安装mkdocs

需要 Python 和 Python package manager pip 来安装 MkDocs . 可以通过以下命令查看是否安装了上述依赖:

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

MkDocs 支持 Python 2.6, 2.7, 3.3 和 3.4.

使用 pip 安装 mkdocs :

$ pip install mkdocs

mkdocs已经安装到你的系统. 运行 mkdocs help 以检查是否正确安装.

$ mkdocs help
mkdocs [help|new|build|serve|gh-deploy] {options}

备注：本人mac在安装时，由于pip3 是3.8版本，所以在安装时报错无法安装成功，所以采用下面的brew 方式。不得不说brew真的是极大的方便了开发提效。

2.2 brew 方式安装mkdocs

brew 安装最为简洁

brew install mkdocs

等待几分钟，就自动安装好了。

leedeMacBook-Pro:github lee$ mkdocs
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...

  MkDocs - Project documentation with Markdown.

Options:
  -V, --version  Show the version and exit.
  -q, --quiet    Silence warnings
  -v, --verbose  Enable verbose output
  -h, --help     Show this message and exit.

Commands:
  build      Build the MkDocs documentation
  gh-deploy  Deploy your documentation to GitHub Pages
  new        Create a new MkDocs project
  serve      Run the builtin development server

3.准备github工程

在该步骤，我们需要创建两个github工程。一个是编写源文档的库，在该库下进行文档编写。另一个是mkdocs编译后的部署仓库，博客的html仓库。当我们编写好源文档库后，对源文档库执行mkdocs build命令进行编译，将编译后的site站点部署文档拷贝到github站点仓库。

具体步骤如下。

3.1 准备源码工程

准备好一个编写markdown文档的源文档仓库。

参考：https://github.com/smileMrLee/smilemrlee-source

1）首先在工作空间建立一个mkdocs仓库，比如我选择在~/workspace/github/ 下创建目录

mkdocs new ${your-docs-name}

这里建议仓库名字用个人博客的站点+"-source"，比如我的github站点是：smileMrLee.github.io 那我的源文档仓库名字就用：smilemrlee-source

创建好改目录后，会自动生成mkdocs 博客目录，如下：

leedeMacBook-Pro:github lee$ ls smilemrlee-source/
docs mkdocs.yml

2）当我们创建好mkdocs 源文档库后，就可以在docs目录下进行编写markdown文档。

然后执行：mkdocs build

此时会根据docs中的markdown文档生成对应的站点静态文件site

leedeMacBook-Pro:github lee$ ls smilemrlee-source/
docs		mkdocs.yml         site

site目录下就是html静态文件。例如：

leedeMacBook-Pro:github lee$ ls smilemrlee-source/site/
404.html	index.html	sitemap.xml.gz	学习ing
css		js		实践
fonts		search		总结
img		sitemap.xml	推荐

3.2 准备部署工程

经过3.1准备源码工程步骤后，我们得到一个可以作为github个人博客部署的站点html静态文件。

1）创建个人博客站点仓库

此时我们根据自己的github账户名称，创建一个【个人github账号.github.io】的仓库，此仓库就是github为每个账号生成的默认博客站点，比如我的个人博客站点仓库地址是这个：https://github.com/smileMrLee/smileMrLee.github.io 我的博客访问地址：https://smilemrlee.github.io/

2）部署博客站点

将3.1步骤使用mkdocs 编译得到的site 路径下的html静态文件拷贝到【个人github账号.github.io】仓库下。

cp -rf smilemrlee-source/site/* smileMrLee.github.io

lirongdeMacBook-Pro:github lirong$ ls
	smileMrLee.github.io	smilemrlee-source

然后提交smileMrLee.github.io 仓库内容。

3）访问博客

比如我的建成后的博客访问地址是：https://smilemrlee.github.io/

不出意外，你的博客访问地址应该是：https://你的github账号.github.io

自己动手试试吧。

备注：参照本教程搭建好一个博客，还需要你熟悉编写markdown文档的语法，以及学会使用mkdocs 建站的基本语法。mkdocs建站命令

## Commands

* `mkdocs new [dir-name]` - Create a new project.  初始化一个mkdocs博客项目
* `mkdocs serve` - Start the live-reloading docs server. 启动本地预览
* `mkdocs build` - Build the documentation site. 构建源码为html静态资源
* `mkdocs -h` - Print help message and exit. 查看帮助

## Project layout

    mkdocs.yml    # The configuration file.   mkdocs的配置文件，用来编辑菜单等
    docs/
        index.md  # The documentation homepage.   站点首页
        ...       # Other markdown pages, images and other files.  自定义目录，存放图片等其他文件

3.3 git自动部署命令

鉴于每次部署都要做很多重复的步骤，所以我写了个自动部署的脚本。该脚本主要做x件事：

1.编译源文档库

2.拷贝html静态文件到个人博客仓库

3.自动提交部署个人博客站点

#!/usr/bin/env bash
cd  /Users/lee/workspace/github/smilemrlee-source
mkdocs build
cp -rf /Users/lee/workspace/github/smilemrlee-source/site/ /Users/lee/workspace/github/smileMrLee.github.io/
cd /Users/lee/workspace/github/smileMrLee.github.io
git add .
git commit -m "发布提交"
git push
echo "发布github完成"

有需要的按照自己的源文档库和个人博客仓库名称进行修改即可。