Fork me on GitHub

曾经自建博客的回忆

字数统计: 4.4k字   |   阅读时长≈ 18分

自毕业以来，尝试过各种基于markdown格式自建博客的搭建，不同的技术实现的博客主题不同，不同的主题又各自有它们独有的优势，所以都记录了下来。后来在发布博文的时候，因为技术实现不同，所以需要的环境不同导致无法快速发布文件，所以在这进行记录。

一、基于GitBook实现

1.1 简述

GitBook网站是一个简单的个人在线书籍网站，在这里可以把自己的文档整理成书籍发布出来，便于阅读。

1.2 环境准备

1
2
3
4
5
6
7
8
9
10
11
12
13
# 安装gitbook,安装失败可以尝试+ --force  即：npm install gitbook -g --force
$npm install gitbook -g

# 安装失败可以尝试+ --force  即：npm install -g gitbook-cli --force
$npm install -g gitbook-cli 

--- 如果没有安装gitbook,此命令会默认同时安装 GitBook
$gitbook -V
--- 列出本地所有的gitbook版本
$gitbook ls

# 安装插件
$gitbook install

1.3 使用指南

运行和发布

1
2
3
4
5
6
7
8
9
10
11
$gitbook init   # 初始化一本书,如果已有，不必执行
$gitbook serve  # 本地启动服务查看效果
$gitbook build  # 打包文档

# 运行gitbook&发布
$sh deploy.sh

## push源代码
$git add .
$git commit - m "提交内容注释"
$git push

1.4 附件材料

  1. gitbook出现if (args[ii] == null) throw missingRequiredArg(ii 解决

二、基于readthedocs实现

1.1 简述

首先说一下这款博客的一个发布流程： Sphinx+GitHub+ReadtheDocs 作为一个文档写作工具，利用pandoc文本转换，用Sphinx生成文档，GitHub托管文档，再导入到ReadtheDocs。我们可以使用这个工具写文档、记笔记等。

  • Read the Docs是一个在线文档托管系统， 你可以从各种版本控制系统中导入文档，如果你使用webhooks，那么每次提交代码后可以自动构建并上传至readthedocs网站，非常方便。
  • Sphinx 是一个基于Python的文档生成项目，最早只是用来生成 Python 官方文档，随着工具的完善， 越来越多的知名的项目也用他来生成文档，甚至完全可以用他来写书采用了reStructuredText作为文档写作语言, 不过也可以通过模块支持其他格式，待会我会介绍怎样支持MarkDown格式。

博客主页：

  1. 《Go深入浅出》：https://go.iswxw.com/
  2. 《Pyhthon 深入浅出》：https://python.iswxw.com/
  3. 《PHP 深入浅出》：https://php.iswxw.com/

博客源码：

  1. https://github.com/iswxw/wxw-go
  2. https://github.com/iswxw/wxw-python
  3. https://github.com/iswxw/wxw-php

1.2 环境准备

环境安装是在有python环境的前提下进行。

安装sphinx

1
pip install sphinx sphinx-autobuild sphinx_rtd_theme

这一步时间会安装很多python依赖，耐心等等..

安装指南

  1. https://www.sphinx-doc.org/en/master/usage/installation.html

1.3 使用指南

（1）本地文本编写

初始化

1
2
3
4
5
# 创建文档根目录
mkdir -p /root/work/wxw-go
cd wxw-go/
# 可以回车按默认配置来写
sphinx-quickstart

下面是我填写的，其他基本上默认即可：

1
2
3
4
5
6
> Separate source and build directories (y/n) [n]:y
> Project name: wxw-go
> Author name(s): iswxw
> Project version []: 0.2
> Project release [1.0]: 0.2.2
> Project language [en]: zh_CN

安装软件tree查看目录树结构：

1
yum install tree

然后运行 tree -C . 查看生成的sphinx结构:

1
2
3
4
5
6
7
8
9
.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

添加一篇文章，在source目录下新建hello.rst，内容如下:

1
2
hello,world
=============

index.rst 修改如下:

1
2
3
4
5
Contents:
.. toctree::
   :maxdepth: 2

   hello

更改主题 sphinx_rtd_theme

更改source/conf.py:

1
2
3
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

然后在更目录执行 make html，进入 build/html目录后用浏览器打开 index.html

toctree 支持多级目录

比如要想将python.rst,java.rst笔记在不同的目录,toctree这样设置:

1
2
3
4
5
6
Contents:

.. toctree::

   python/python
   swift/swift

注意中间的空行

支持markdown编写

通过recommonmark 来支持markdown

1
pip install recommonmark

然后更改conf.py:

1
2
3
4
5
from recommonmark.parser import CommonMarkParser
source_parsers = {
    '.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

如果想使用高级功能，可以添加AutoStructify配置，在 conf.py中添加:

1
2
3
4
5
6
7
8
9
10
11
# At top on conf.py (with other import statements)
import recommonmark
from recommonmark.transform import AutoStructify

# At the bottom of conf.py
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

网上有个详细配置: https://github.com/rtfd/recommonmark/blob/master/docs/conf.py

然后修改刚刚的 hello.rst，改用熟悉的 hello.md编写:

1
2
3
## hello world

### test markdown

再次运行 make html后看效果，跟前面一样。

（2）GitHub托管

一般的做法是将文档托管到版本控制系统比如github上面，push源码后自动构建发布到readthedoc上面， 这样既有版本控制好处，又能自动发布到readthedoc，实在是太方便了。

先在GitHub创建一个仓库名字叫wxw-go， 然后在本地.gitignore文件中添加 build/目录，初始化git，commit后，添加远程仓库。

具体几个步骤非常简单，参考官方文档：https://github.com/rtfd/readthedocs.org:

  1. 在Read the Docs上面注册一个账号
  2. 登陆后点击 “Import”.
  3. 给该文档项目填写一个名字比如 “wxw-go”, 并添加你在GitHub上面的工程HTTPS链接, 选择仓库类型为Git
  4. 其他项目根据自己的需要填写后点击 “Create”，创建完后会自动去激活Webhooks，不用再去GitHub设置
  5. 一切搞定，从此只要你往这个仓库push代码，readthedoc上面的文档就会自动更新.

注：在创建read the docs项目时候，语言选择”Simplified Chinese”

1.4 附件材料

  1. readthedoc官方教程

三、基于vuepress实现

1.1 简述

我相信每一个程序员入门时，都经历过搭建一个个人博客这样的阶段。确实这是一个好的练手项目，而搭建博客难度也可高可低，取决于个人目标。本文提供了一个选择，可基于 GitHub 的 GitHub Pages 功能 和 Vuepress 框架快速地搭建免费的markdown博客：对于文档编写者来说，能更专注于写文章；对于文档开发者来说，一切皆Vue组件，能方便地自定义主题。

1.2 环境准备

前提是环境依赖于node.js以及npm包管理工具。

构建基本目录结构

  1. 新建一个名为 blog-demo 的文件夹，命令行进入到该文件夹目录，输入命令：
1
2
# 按默认配置初始化一个项目，此时会在当前目录下生成 package.json 文件
npm init -y
  1. 将 VuePress 作为一个本地依赖安装
1
npm install -D vuepress
  1. 在 package.json 里的 scripts 中添加如下代码，不需要修改其它代码
1
2
3
4
5
6
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
  1. 在项目根目录下，新建 docs 文件夹
1
mkdir docs
  1. 新建一个 markdown 文件
    1
    echo '# Hello VuePress!' > docs/README.md
  2. 输入命令启动项目，在浏览器中访问 http://localhost:8080/ 即可预览效果
1
npm run docs:dev

1.3 使用指南

基本配置

现在我们已经构建出了最基本的项目结构，并且可以在浏览器中预览到 docs 目录下的 README.md 文件的效果，该文件即是我们网站的首页，如图所示：

然而如果没有任何配置，用户将无法在网站上自由导航。因此，为了更好地自定义我们的网站，我们接着在 docs 目录下新建 .vuepress 文件夹，执行命令如下：

1
2
# 新建 .vuepress 文件夹
mkdir docs\.vuepress

接着在 .vuepress 文件夹下新建 config.js 文件,这里的 config.js 便是一个 Vuepress 网站必要的配置文件，在其中添加如下代码：

1
2
3
4
5
module.exports = {
  base: '/blog-demo/',
  title: 'blog-demo',
  description: 'Vuepress blog demo'
}

其中配置项的含义为：

  • base：站点的基础路径，它的值应当总是以斜杠开始，并以斜杠结束。这里设置为 /blog-demo/ ，我们再次在本地运行项目，访问路径就需要变更为 http://localhost:8080/blog-demo/
  • title：网站的标题
  • description：网站的描述

默认主题配置

Vuepress 提供了一个默认主题，让我们不必自己去从零实现复杂的 markdown 文件渲染、目录结构等，直接按照规则去使用它即可。如果你想自定义自己的主题，请查看官方文档：Vuepress-开发主题。

首页配置

默认主题提供了一个首页的布局，想要使用它，需要在你的根级 README.md 以格式 YAML front matter 指定 home: true。因此，将我们最初创建的 README.md 修改一下：

1
2
3
4
5
6
7
8
9
10
11
12
13
home: true
heroImage: /vue-logo.png
heroText: blog-demo
tagline: 博客示例
actionText: 快速上手 →
actionLink: /
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
  • heroImage: 首页图片，图片放置在 .vupress/public 文件夹下，若没有该文件夹则自己创建一个，保存一张你想要的首页图片，并在此处引用。
  • 其它参数请参考官方文档：Vuepress-默认主题首页

导航栏

导航栏可能包含你的页面标题、搜索框、 导航栏链接、多语言切换、仓库链接，它们均取决于你的配置。在 .vupress/config.js 文件添加一些导航栏链接：

1
2
3
4
5
6
7
8
9
10
11
12
module.exports = {
    themeConfig: {
        // 你的GitHub仓库，请正确填写
        repo: 'https://github.com/xxxxxxx/blog-demo',
        // 自定义仓库链接文字。
        repoLabel: 'My GitHub',
        nav: [
            { text: 'Home', link: '/' },
            { text: 'FirstBlog', link: '/blog/FirstBlog.md' }
        ]
    }
}

接着，我们在 docs 目录下新建 blog 文件夹，在 blog 目录下创建 /blog/FirstBlog.md 作为我们第一篇博客的内容：

1
2
3
# 我的第一篇博客

My First Blog

我们再在项目根目录，即 blog-demo 下，输入命令 npm run docs:dev ，浏览器中访问 http://localhost:8080/blog-demo/ 查看页面效果，点击页面右上角的FirstBlog 可以看到我们第一篇博客：

侧边栏

最后我们配置侧边栏，让用户体验更好一些，在 .vupress/config.js 文件添加一些代码：

1
2
3
4
5
6
7
8
module.exports = {
  themeConfig: {
    sidebar: [
      ['/', '首页'],
      ['/blog/FirstBlog.md', '我的第一篇博客']
    ]
  }
}

本地预览

至此我们已经完成了一个最简单的博客，再次运行项目，点击首页的按钮 快速上手 ，我们可以看到：

部署

最后一步，我们需要将代码部署到GitHub Pages，具体请参照文档：Vupress-部署。

（1）首先确定你的项目是否满足以下条件：

  • 文档放置在项目的 docs 目录中
  • 使用的是默认的构建输出位置
  • VuePress 以本地依赖的形式被安装到你的项目中，在根目录的 package.json文件中有如下两段代码：
1
2
3
4
5
6
7
8
9
10
// 配置npm scripts
"scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
 }

// VuePress 以本地依赖的形式被安装
"devDependencies": {
    "vuepress": "^0.14.8"
}

（2）在github上创建一个名为 blog-demo 的仓库，并将你的代码提交到github上。如果你对git不熟悉，请先阅读：Git教程-廖雪峰的官方网站

（3）在 docs/.vuepress/config.js 文件中设置正确的 base。

如果打算发布到 https://.github.io//（也就是说你的仓库在 https://github.com//），则将 base 设置为 //，此处我设置为 /blog-demo/ 。

（4）在项目根目录中，创建一个如下的 deploy.sh 脚本文件，请自行修改github仓库地址

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -

（5）双击 deploy.sh 运行脚本，会自动在我们的 GitHub 仓库中，创建一个名为 gh-pages 的分支，而我们要部署到 GitHub Pages 的正是这个分支。

（6）这是最后一步了，在 GitHub 项目点击 Setting 按钮，找到 GitHub Pages - Source，选择 gh-pages 分支，点击 Save 按钮后，静静地等待它部署完成即可。

1.4 附件材料

  1. vuepress官方文档
  2. node.js
  3. npm

四、基于docsify实现

1.1 简述

docsify 是一个神奇的文档网站生成器。它可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档。

1.2 环境准备

安装docsify-cli之前，我们需要安装npm包管理器，而安装了node.js就会自动安装npm。

推荐全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。

1
2
#用npm安装全局工具
npm i docsify-cli -g

1.3 使用指南

初始化项目

如果想在项目的 . 当前目录里写文档，直接通过 init 初始化项目

1
docsify init .

初始化成功后，可以看到 . 目录下创建的几个文件

  • index.html 入口文件
  • README.md 会做为主页内容渲染
  • .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

如果不喜欢 npm 或者觉得安装工具太麻烦，我们可以直接手动创建一个 index.html 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

本地预览

通过运行 docsify serve . 启动一个本地服务器，这里的点就是当前目录的意思，可以方便地实时预览效果。默认访问地址 http://localhost:3000 。也可以用-p指定端口。

1
docsify serve -p 80 .

as

Loading 提示

初始化时会显示 Loading… 内容，你可以自定义提示信息。直接修改index.html文件。

1
<div id="app">加载中</div>

如果更改了 el 的配置，需要将该元素加上 data-app 属性。

1
2
3
4
5
6
7
8
9
<!-- index.html -->
  <div data-app id="main">加载中</div>

  <script>
    window.$docsify = {
      el: '#main'
    }
  </script>

更多详细的配置可以参见官网 docsify。

1.4 附件材料

  1. https://docsify.js.org/#/?id=docsify
  2. 工具docsify详解

五、基于hexo实现

1.1 简述

Hexo 是基于NodeJs的静态博客框架，简单、轻量，它生成的静态站点可以托管在Github和Gitee上。Hexo还支持MarkDown语法，是很多程序猿的福音，它可以一键部署，支持超多插件，拥有超多主题，是个不错的选择。

1.2 环境准备

因为hexo是基于NodeJs的，所以需要安装NodeJs。

去NodeJs官网下载长期支持版，然后打开安装程序，安装选项全部默认，一路点击Next。安装好了之后，打开cmd输入node -v，如果显示的是下载的版本号那就是安装成功了。

安装hexo

1
npm install -g hexo-cli

安装好了以后输入hexo -v 检查安装，如果输出的是一堆版本号那就安装成功了。

详细安装教程参见 hexo官网

1.3 使用指南

安装好后,初始化博客目录

  1. 输入 hexo init blog 初始化文件夹
  2. 接着输入cd blog将目录切换到blog文件夹里
  3. 然后输入npm install就会在文件夹里生成一些需要的文件。

这样就配置好了，可以输入hexo g生成静态网页，然后输入hexo s打开本地服务器来查看网页，

相关指令说明：

1
2
3
4
5
6
7
8
npm install hexo-cli -g                                        // 安装hexo
hexo init iswxw                                                // 初始化博客目录： 
cd iswxw                                                       // 初始化完成后，我们就进入我们的目录
npm install                                                    // 安装 依赖包
hexo clean                                                     // 清除缓存文件 (db.json) 和已生成的静态文件 (public)
hexo g                                                         // 生成静态页面 
hexo s                                                         // 把你的网站本地运行起来
hexo d                                                         // 发布服务到指定的服务器

项目维护

项目预览

1
2
3
4
5
6
7
8
# 1. 请求历史文件
hexo clean

# 2. 生成静态页面
hexo g

# 3. 发布本地服务
hexo s

项目发布

1
2
3
4
5
6
7
8
9
10
11
# 1. 请求历史文件
hexo clean

# 2. 生成静态页面
hexo g

# 3. 发布 到码云 https://gitee.com/iswxw/iswxw.git
hexo d 

# 4. push 到指定仓库
git push git@github.com:iswxw/iswxw.github.io.git main

1.4 附件材料

  1. hexo官网
  2. node.js
  3. npm
赏

谢谢你请我吃糖果

支付宝
微信
置顶

扫一扫，分享到微信

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia-plus根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

主要涉及技术：
Java后端开发、
公众号开发、开源爱好者、Linux

联系QQ:1550518923

很惭愧

只做了一点微小的工作
谢谢大家