实现一个简单的静态博客生成器

作为一名程序员，写博客是积累知识、提升水平必不可少的一个方法。我们写博客主要有三种方法，一种是使用掘金、博客园、CSDN等博客网站，第二种是自己搭建网站，存放自己的博客，第三种就是使用静态博客生成器，将生成的网页部署到服务器或者github pages、gitee pages等服务上。

这三种方法中，第一种自由度太低，并且定制样式很麻烦；第二种每写一篇博客都要新建个页面，非常麻烦。因此我选择了第三种方法，在使用了hexo、vuepress，gridea等多种静态博客生成器后，我决定自己写一个来提升自己的能力。

项目地址：https://github.com/Tuzilow/CoinRailgun

明确需求

首先我们要明确需求，确定我们想要的效果

1. 初始化博客文件夹，载入模板crn init
2. 根据模板创建markdown文件，crn new "Hello CoinRailgun"
3. 根据markdown文件生成html文件，crn build
4. 本地运行网站，crn server

开始编写

安装依赖

根据上面我们分析出来的需求，确定出我们所需要的依赖，并且安装好他们

• art-template编写模板所用的模板引擎
• commander用来编写cli
• dayjs处理时间
• front-matter处理markdown顶部的yml声明
• fs-extrafs的扩充模块
• glob匹配指定文件名
• highlight.js高亮代码块
• koa和koa-static启动本地服务
• markdown-it、markdown-it-anchor、markdown-it-toc-done-right解析markdown
• uslug解析锚点的汉字

"dependencies": {
  "art-template": "^4.13.2",
  "commander": "^7.0.0",
  "dayjs": "^1.10.4",
  "front-matter": "^4.0.2",
  "fs-extra": "^9.1.0",
  "glob": "^7.1.6",
  "highlight.js": "^10.5.0",
  "koa": "^2.13.1",
  "koa-static": "^5.0.0",
  "markdown-it": "^12.0.4",
  "markdown-it-anchor": "^7.0.1",
  "markdown-it-toc-done-right": "^4.2.0",
  "uslug": "^1.0.4"
}

搭建项目结构

.
├─ bin
│    └─ crn.js  # 执行文件
├─ lib# crn.js调用的各个函数
│    ├─ build.js
│    ├─ clean.js
│    ├─ new.js
│    ├─ preview.js
│    └─ init.js
├─ package.json
└─ template # 模板
       ├─ site.config.json # 配置文件
       └─ theme # 主题
              └─ default # 默认主题
                     ├─ assets
                     └─ layout

crn.js

同样，根据需求将各个命令、命令的参数和说明先写出来

关于commander具体如何使用，可以查看commander文档

#! /usr/bin/env node

const program = require('commander');
const version = require('../package.json').version;

program
  .version(version)
  .command('init [dir]')
  .description('初始化博客')
  .action(require('../lib/init'));

program
  .command('new <name>')
  .description('创建新的文章')
  .action(require('../lib/new.js'));

program
  .command('server [dir]')
  .description('本地预览网站')
  .option('-d, --dir <dir>', 'build时输出的目录')
  .action(require('../lib/preview.js'));

program
  .command('build [dir]')
  .description('将文章渲染为html')
  .option('-o, --output <dir>', '输出目录')
  .action(require('../lib/build'));

program
  .command('clean')
  .description('清空build出来的静态文件')
  .option('-d, --dir <dir>', 'build时输出的目录')
  .action(require('../lib/clean.js'));

program.parse(process.argv);

init

初始化的时候可以传入一个目录，表示准备初始化的目录，这里我用了ES2020的新语法dir = dir ?? '.'，当dir为null或undefined时，使用问号右边的值。

在初始化的时候，需要明确好用户使用的目录应该是什么样的

Blog
├─ build
├─ site.config.json
├─ source
│    └─ _posts
│           └─ blog.md
└─ theme
       └─ default
              ├─ assets
              └─ layout

将预先准备好的模板根据设计的目录拷贝到目标目录下，而不是直接调用项目中的，因为拷贝到目标目录下后，使用者就可以更方便的自定义模板，可以更方便的写自己的样式。

关于fs-extra模块的各种API可以查看fs-extra文档

关于dayjs可以查看dayjs文档

const path = require('path');
const fs = require('fs-extra');
const dayjs = require('dayjs');

module.exports = (dir) => {
  dir = dir ?? '.';

  const templateDir = path.resolve(__dirname, '..', 'template');
  fs.copySync(templateDir, path.resolve(dir));
  fs.ensureDirSync(path.resolve(dir, 'source'));

  newPost(dir);
};

function newPost(dir) {
  const firstPost = [
    '---',
    'title: Hello World',
    'date: ' + dayjs().format('YYYY/MM/DD HH:mm:ss'),
    'tags: ' + '[blog,CoinRailgunn]',
    'category: ' + 'welcome',
    '---',
    '',
    'Welcome to my blog, this is my first post',
    '<!-- more -->'
  ].join('\n');

  const file = path.resolve(dir, 'source', '_posts', 'hello.md');
  fs.outputFileSync(file, firstPost);

  console.log("博客初始化完成，键入'crn new <postName>'即可创建新的文章");
}

new

创建新文章的函数和初始化函数有部分的逻辑是相同的，这里我没有将他们封装起来，如果感兴趣的话你们可以试试。创建文章需要传入一个name，为创建的文章名，然后将其保存至source/_post下

const fs = require('fs-extra');
const path = require('path');
const dayjs = require('dayjs');

module.exports = (name) => {
  const post = [
    '---',
    `title: ${name}`,
    'date: ' + dayjs().format('YYYY/MM/DD HH:mm:ss'),
    'tags: ' + '[blog]',
    'category: ' + 'code',
    '---',
    '',
  ].join('\n');

  const file = path.resolve('source', '_posts', `${name}.md`);
  fs.outputFileSync(file, post);

  console.log(`source/_posts/${name}.md 创建成功！`);
};

build

生成静态页是整个项目最关键的部分，因为代码很多这里讲一下我的思路，详细代码可以查看项目仓库

首先我们要设计好各个页面的url，以下为我的设计：

• 首页：/index.html和/page/1/index.html
• 不同页码：/page/页码/index.html
• 文章页：/categories/分类名/文章名/index.html
• 关于我页面：/about/index.html
• 归档页：/archives/index.html
• 分类页：/categories/index.html
• 标签页：/tags/index.html
• 404页：/404/index.html（这个我忘了做了

目前的浏览器会自动隐藏index.html，因此使用目录名/index.html的方式可以美化页面的地址栏

第一步，根据设计好的url编写好各个页面模板，这里我使用的是art-template

• template/theme/default/layout/layout.art
• template/theme/default/layout/page.art
• 其他请查看CoinRailgun默认主题模板

然后，一些网站的基础数据，比如author、keywords、description等，是不会发生改变的，因此需要将他们写在统一的配置文件里site.config.json，下面是我的部分配置文件

{
  "basic": {
    "icon": "",
    "avatar": "",
    "title": "",
    "author": "",
    "description": "",
    "keywords": []
  },
  "theme": {
    "name": "default",
    "highlight": "github-gist",
    "pageSize": 7,
    "exclude": [
      "life"
    ],
    "friends": [],
    "about": {
      "label": "about me.",
      "url": "/about"
    },
    "nav": [
      {
        "name": "archives",
        "label": "归档",
        "url": "/archives"
      },
      {
        "name": "categories",
        "label": "分类",
        "url": "/categories"
      },
      {
        "name": "tags",
        "label": "标签",
        "url": "/tags"
      }
    ],
    "links": [],
    "footer": {
      "beian": "",
      "copyright": {
        "year": "2019-2021"
      }
    }
  },
  "dev_server": {
    "port": 3000
  }
}

在根据markdown和模板生成html时，我们要确定模板上需要的数据，并且将配置文件和markdown的内容转换为模板上的数据

<!-- layout/post_item.art -->
<div class="post-item__title">
  <a href="{{url}}">
    {{title}}
  </a>
</div>
<div class="post-item__desc">
  <p class="post-item__desc-date">
    <i class="fa fa-calendar" aria-hidden="true"></i>
    {{date}}
  </p>
  <p class="post-item__desc-category">
    <i class="fa fa-folder-o" aria-hidden="true"></i>
    <a href="/categories">
      {{category || ''}}
    </a>
  </p>
</div>
<div class="post-item__abstract">
  <p class="post-item__abstract-content">{{@ abstracts}}</p>
  <p class="more" style="display:none;">
    <a href="{{url}}">查看更多</a>
  </p>
</div>
<div class="post-item__tags">
  {{each tags}}
  <a href="/tags">
    <i class="fa fa-tag" aria-hidden="true"></i>
    {{$value}}
  </a>
  {{/each}}
</div>

以文章列表项为例，这个模板需要title、date、category、url、abstracts和tags，其中url是根据设计好的/categories/分类名/文章名/index.html生成出来的，其他的参数都是从markdown文件中解析出来的，并且这些参数都写在文件头部的yml配置中，而abstracts一般是使用<!--more-->分割出来。

明确了以上内容后，我们就需要获取这些参数然后传递给模板渲染出来

const template = fs.readFileSync(postTemplate, 'utf-8');
const content = fs.readFileSync(fullPath, 'utf-8');
const fm = require('front-matter');

function renderAbstracts() {
  // ....
}

const postItem = art.render(template, {
  ...fm(content).attributes,
  abstracts: renderAbstracts(),
});

这样我们就得到了渲染后的文章列表项，然后再传入post_list.art 渲染出来文章列表后传入page.art中，与其他的数据相组合拿到完整的一个页面。渲染出页面后使用fs.outputFileSync将页面保存到一开始设计好的目录中build/page/1/index.html

大致思路就是这样，更多具体实现可以查看项目仓库

server

生成所有页面后，就可以开启本地预览了，这里我使用的是koa，使用express或者其他的框架都是大差不差的。直接将build目录设置为静态资源即可访问。

const Koa = require('koa');
const staticServe = require('koa-static');
const path = require('path');

module.exports = (dir, options) => {
  dir = dir ?? '.';
  const app = new Koa();

  const siteConfig = require(path.resolve(dir, 'site.config.json'));

  const outputDir = path.resolve(dir, options.dir ?? 'build');
  app.use(staticServe(outputDir));

  app.listen(siteConfig.dev_server.port, () => {
    console.log(
      `在浏览器中打开 http://localhost:${siteConfig.dev_server.port} 以预览网页`
    );
  });
};

这样我们就了解了制作一个静态博客生成器的思路和过程。

参考文章

• 手摸手教你撸一个静态网站生成器
• 自己动手撸一个静态博客生成器