无需编译、快速生成 Vue 风格的文档网站

介绍

在做个人项目时，能有一份精致的文档网站或是 landingpage 能给项目带来不少 star。通常我们会选择 GitBook 或者 GitHub Pages 等编译静态文档工具，但是有时候我们并不喜欢一堆编译的文件「污染」 commit 以及项目仓库，同时每次提交前都要编译显得繁琐。

docsify 同样也是一个文档生成工具，只不过它是直接加载 Markdown 文件并动态渲染。同时还可以生成封面页。所以以后我们只需要写完 Markdown 文档，直接推到仓库上就完成了。

快速开始

先在项目下创建 docs/ 目录，因为现在 GitHub 支持直接将仓库下的 docs/ 目录作为 GitHub Pages 的目录，当然你也可以放在 gh-pages 分支里。

创建 index.html 文件

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>标题</title>
  <meta name="description" content="简介，方便 SEO">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
</head>
<body>
  <div id="app"></div>
</body>
<script
  src="//unpkg.com/docsify/lib/docsify.min.js"
  data-router>
</script>
</html>

如果访问不了 UNPKG，可以尝试 jsDelivr cdn。

最后创建 README.md 作为文档的入口文件

# 标题

内容

```html
<h1>支持代码高亮</h1>
```

提交并推送仓库后，到 Settings 里开启 GitHub Pages 功能就可以预览到效果了。

生成封面

无需写一行代码，我们也可以只写 Markdown 就可以生成封面页。首先将 index.html 里的 script 标签加上 data-coverpage 参数。

<script
  src="//unpkg.com/docsify/lib/docsify.min.js" 
  data-coverpage
  data-router>
</script>

创建 .nojekyll 防止 GitHub Pages 忽略掉下划线开头的文件

创建 _coverpage.md 处理逻辑是 h1 标签会识别成项目名、a 标签在文档末尾会被渲染成按钮。

![logo](_media/icon.svg)

# docsify <small>1.3.3</small>

> A magical documentation site generator.

- Simple and lightweight (~12kb gzipped)
- Multiple themes
- Not build static html files


[GitHub](https://github.com/QingWei-Li/docsify/)
[Get Started](#quick-start)

最终一份带封面的文档网站就做好了 ?

链接

GitHub: QingWei-Li/docsify
Website: docsify.js.org
类似项目: egoist/docute