原文： https://rebootcat.com/2020/09/20/wiki/

why wiki

博客通常是用来记录一些完整的文章，每篇文章有一个主题。但是我想把平日里的一些笔记也记录到我的博客里，但笔记是零散的，随时的，不是完整的一个主题。所以打算构建一个 wiki 页面，专门用来存放我的笔记，wiki 页面类似于维基百科的形式。

我的博客采用的是 hexo 构建的，如果打算 DIY 一个类似于 维基百科 的 wiki 页面的话，对于我来说，也许有点难度，毕竟我只会写简单的网页。那么有没有现成的方案或者替代的方案呢？

答案是有的，那就是 mkdocs。

mkdocs 使用

什么是 Mkdocs 呢？

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introduction below, then check the User Guide for more info.

mkdocs 是一个用 python 编写的静态站点生成工具，主要是用来编写项目文档，文档使用 Markdown 编写，只需要配合一个 YAML 配置文件，就能快速生成一个站点。

毫无疑问，对于我来说，它有以下几个优点：

使用 python 编写（说明有 DIY 的可能）
源文件使用 Markdown 编写
只需要一个 Yaml 文件，非常简单了
主题可选（当然目前来说不是特别多）

可以先看一下我的wiki.

快速开始

可以参考官方文档：mkdocs.org，或者直接往下看：

首先安装 mkdocs:

$ pip install mkdocs

安装完成之后直接生成一个项目：

$ mkdocs new mysite                                                                    [23:33:49]
INFO    -  Creating project directory: mysite
INFO    -  Writing config file: mysite/mkdocs.yml
INFO    -  Writing initial docs: mysite/docs/index.md

看看都生成了啥：

$ cd mysite
$ tree                                                                                    [23:34:59]
.
├── docs
│   └── index.md
└── mkdocs.yml1 directory, 2 files

默认生成了一个 yml 配置文件以及一个默认的 markdown 文件。

看看 mkdocs 支持哪些命令：

$ mkdocs -h                                                                               [23:36:21]
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 documentationgh-deploy  Deploy your documentation to GitHub Pagesnew        Create a new MkDocs projectserve      Run the builtin development server

构建站点：

$ mkdocs build

然后生成了一个 site 目录：

$ tree                                                                                    [23:37:23]
.
├── docs
│   └── index.md
├── mkdocs.yml
└── site├── 404.html├── css│   ├── base.css│   ├── bootstrap.min.css│   └── font-awesome.min.css├── fonts│   ├── fontawesome-webfont.eot│   ├── fontawesome-webfont.svg│   ├── fontawesome-webfont.ttf│   ├── fontawesome-webfont.woff│   ├── fontawesome-webfont.woff2│   ├── glyphicons-halflings-regular.eot│   ├── glyphicons-halflings-regular.svg│   ├── glyphicons-halflings-regular.ttf│   ├── glyphicons-halflings-regular.woff│   └── glyphicons-halflings-regular.woff2├── img│   ├── favicon.ico│   └── grid.png├── index.html├── js│   ├── base.js│   ├── bootstrap.min.js│   └── jquery-1.10.2.min.js├── search│   ├── lunr.js│   ├── main.js│   ├── search_index.json│   └── worker.js├── sitemap.xml└── sitemap.xml.gz7 directories, 28 files

可以看到 site 目录下就是站点的源码了，那么本地测试一下：

$ mkdocs serve

然后访问 http://127.0.0.1:8000，能看到默认的站点了：

是不是超级超级简单？

那么这个是 mkdocs 最简单的使用，接下来分享下我的使用，经过了一些定制化，包括主题的选择，域名的绑定，站点的发布等。

使用 github pages 发布 wiki

我的博客使用了 github pages 进行托管（目前不是，目前已经迁移到香港虚拟空间），但是如何把上面 mkdocs 生成的站点源码和博客源码放到一起呢？

有很多方法，比如可以手动把 wiki 站点源码放到博客根目录下；

但其实 github pages 是可以支持多个站点的，不知道有没有同学还不知道？

简单来说，使用一个 github 账号，能创建一个 用户站点，格式为 <user>.github.io，比如我的博客源码仓库： smaugx.github.io;

但是除了一个用户站点之外，还能创建任意多个 普通站点，仓库名字任意，没有要求。

也就是说一个 github 账户其实是可以创建多个博客站点的。

关于如何创建一个普通站点，可以参考 github 官方文档：创建 GitHub Pages 站点.

或者往下看。

wiki 仓库设置

这里以我的 wiki 为例： https://github.com/smaugx/wiki，站点效果可以直接查看我的 wiki: https://rebootcat.com/wiki。

1 在 github 上创建一个仓库，命名为 wiki 或者其他的任意名字

2 克隆我的项目： git clone https://github.com/smaugx/wiki.git

3 更改仓库 remote-url 为你刚创建的 wiki 的 github url

cd wiki
git remote rm origin
git remote add origin  https://github.com/yourname/your-wiki.git

上面改成你自己的 wiki 地址（或者使用 ssh 的方式）

4 推送本地仓库 wiki 到远程 wiki

git push -u origin master

至此，你的 github 上应该有一个和我的 wiki 仓库一样的仓库了。

接下来讲一下怎么设置仓库。

5 首先去到刚创建好的 wiki 仓库 https://github.com/yourname/your-wiki

6 点击设置，往下拉到 GiHub Pages 配置项，选择 master 分支，选择 /docs 目录，然后点击 save 保存

7 上面一部之后，再次回到 Github Pages 配置项，找到下面的 Custom domain，填入你的域名或者 url 地址，比如我直接写了： http://rebootcat.com/wiki

8 不出意外，你就能正常访问了。

上面的前提当然是你已经有了个人博客，也就是已经有了一个命名为 <user>.github.io 的仓库了，不然是不会成功了，你要先创建一个这样的仓库。

编写wiki，更新 wiki

上面如果顺利的话，你能看到和我的 wiki 一样的内容：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-uQ6zJqkk-1601038121725)(https://cdn.jsdelivr.net/gh/smaugx/MyblogImgHosting_2/rebootcat/wiki/1.png)]

那么如何编写你自己的 wiki 文章呢？

我们回到本地的 wiki 仓库：

cd wiki

注意，我的文档都放在了 source 目录下：

$ ls source
git.md    index.md  other.md  python.md rsync.md

所以你只需要删除我的 Markdown文档，把你的 Markdown 文档放到该目录，然后执行：

$ python run.py
warning: found not support file type:.DS_Store
############### begin dump mkdocs.yml ###############
copyright: "Copyright \xA9 2020-2020 smaug"
docs_dir: source
extra:article_nav_bottom: truehistory_buttons: trueversion: v1.0.4
markdown_extensions:
- admonition
nav:
- Home: index.md
- python: python.md
- rsync: rsync.md
- git: git.md
- "\u5176\u4ED6": other.md
repo_url: https://github.com/smaugx/wiki
site_author: smaugx
site_description: "My Wiki | \u6797\u5915\u6C34\u5171"
site_dir: docs
site_name: "My Wiki | \u6797\u5915\u6C34\u5171"
site_url: http://rebootcat.com/wiki
theme:custom_dir: mkdocs_windmillinclude_search_page: truename: nullsearch_index_only: truestatic_templates:- 404.html############### update mkdocs.yml done ############################## begin mkdocs build ###############
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/smaug/centos7/SmaugDemo/wiki/docs
INFO    -  Documentation built in 0.18 seconds
############### mkdocs build done in dir:docs ############################## begin git push:git add --all . && git commit -m "update mkdocs site" && git push ###############
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 443 bytes | 443.00 KiB/s, done.
Total 5 (delta 4), reused 0 (delta 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
To github.com:smaugx/wiki.gitba3b15e..4131b86  master -> master
[master 4131b86] update mkdocs site2 files changed, 1 insertion(+), 1 deletion(-)
############### git push done ###############

这个脚本的功能是根据 source 目录下的 Markdown 文档，更新 yaml 站点配置文件，然后生成站点源码，然后推送站点源码到 github 上。

如果执行出错，可以自行调试一下，一般问题不大。

博客首页引导栏添加 `维基`栏

这个过程就省略了。

The End

wiki 站点搭建完毕，

Blog:

rebootcat.com
email: linuxcode2niki@gmail.com

2020-09-20 于杭州
By 史矛革

使用 mkdocs 搭建个人 wiki 站点相关推荐

wiki服务器网页地址,搭建个人wiki站点
写blog确实是一种消化和深入理解知识的方式,但往往要整理一个完整的主题相当的耗时间. 平时我也想记一记一些有用然而散乱的tips,慢慢积累起来. 作为一位Vim忠实粉,我理所当然找到了大名鼎鼎的Vi ...
搭建一个jupyter站点做数据分析吧
jupyter jupyter 是一个非常适合做数据分析的工作台.为了可以使得jupyter可以运行在服务器上访问生产环境的数据,今天我要在服务器上搭建一个jupyter站点. 容器为了不和线上的其 ...
Dreamweaver （DW）结合 Tomcat 服务器搭建动态jsp 站点
目录一.Dreamweaver (DW)结合 Tomcat 服务器搭建动态jsp站点所需软件: 二.站点搭建过程: 1).Tomcat 服务器的安装: 2).Tomcat的测试 3).Tomcat ...
BBS（仿博客园系统）项目03（主页搭建、个人站点搭建（侧边栏分类展示、标签展示、日期归档）、文章详情页相关功能实现）...
摘要: 主页面的搭建(导航条下面的区域) 个人站点侧边栏分类展示侧边栏标签展示侧边栏日期归档文章详情页文章内容文章点赞点踩文章评论一.主页面home.html的搭建(进一步完善) ho ...
Linux 搭建Web虚拟机，单台机搭建多web站点
一.基础知识虚拟web主机,指的是在同一台服务器中运行多个web站点,其中的每一个站点实际上并不独自占用整个服务器,可以充分利用服务器的硬件资源,从而大大减低网站构建及运行成本.使用httpd可以非 ...
Linux 下搭建 WordPress 个人站点
WordPress是基于在LAMP 环境下搭建.这里用的是CentOS 7 wordpress 对php 和mysql 有版本要求.wordpress版本 4.7.4的数据库mariadb-5.5. ...
Apache搭建多个站点方法详解
www.111cn.net 编辑:Bolshevik 来源:转载 Apache的虚拟主机是一种允许在同一台机器上配置多个不同站点的web服务器环境的,就是iis一样可以创建多站点了,但是apache需 ...
wordpress linux位置,Linux 下搭建 WordPress 个人站点
WordPress是基于在LAMP 环境下搭建.这里用的是CentOS 7 wordpress 对php 和mysql 有版本要求.wordpress版本 4.7.4的数据库mariadb-5.5. ...
使用 simiki 搭建个人 wiki(简易的博客)
注意安装simiki以及其他模块的时候,使用pip安装,因为simiki使用python2开发的. 快速开始使用 python 环境安装: pip install simiki 新建目录 myWi ...

使用 mkdocs 搭建个人 wiki 站点

why wiki

mkdocs 使用

快速开始

使用 github pages 发布 wiki

wiki 仓库设置

编写wiki，更新 wiki

博客首页引导栏添加 `维基`栏

The End

使用 mkdocs 搭建个人 wiki 站点相关推荐

最新文章

热门文章

使用 mkdocs 搭建个人 wiki 站点

why wiki

mkdocs 使用

快速开始

使用 github pages 发布 wiki

wiki 仓库设置

编写wiki，更新 wiki

博客首页引导栏添加 维基栏

The End

使用 mkdocs 搭建个人 wiki 站点相关推荐

最新文章

热门文章

博客首页引导栏添加 `维基`栏