前言

网上关于文档的生成工具很多，像VuePress、GitBook 、Hexo这些都是一些非常优秀的文档生成工具，本文主要讲述Docsify搭建和使用。Docsify 是一个动态生成文档网站的工具，不同于 GitBook 的地方是它不会将 .md 转成 .html 文件，所有转换工作都是在运行时进行。

官方站点

https://docsify.js.org

搭建一个轻量级的个人团队文档平台-docsify

特性

没有静态构建的 html 文件
简单轻便
智能全文搜索插件
多个主题
有用的插件 API
表情符号支持
兼容IE11
支持服务端渲染

配置文件

index.html 网站入口文件
_sidebar.md 侧边栏目录文件，markdown语法编写
_navbar.md 导航目录文件，markdown语法编写
home.md 主面板默认页面，不配置则默认加载中

侧边栏配置

window.$docsify = {
    loadSidebar: true,
    alias: {
        '/.*/_sidebar.md': '/_sidebar.md', // See #301
    },
}

<script src="./docsify/docsify.js"></script>

创建：_sidebar.md

<!-- docs/_sidebar.md -->

* [Home](/)
* [Guide](guide.md)

文档化仅在当前文件夹中搜索，并使用该文件夹，否则会回回使用配置配置的文件夹。
_sidebar.mdwindow.$docsify.loadSidebar

文件结构

└── docs/
    ├── _sidebar.md
    ├── _navbar.md
    ├── index.html
    ├── home.md
    ├── _coverpage.md

边栏设置页面标题

页面的标记从选定的边栏项名称生成。为了更好的 SEO，可以通过在文件名后指定字符串来自定义标题

<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

自定义导航栏

如果需要自定义导航，可以创建一个基于 HTML 的导航栏。文档链接以开始。#/

<!-- index.html -->

<body>
  <nav>
    <a href="#/">EN</a>
    <a href="#/zh-cn/">中文</a>
  </nav>
  <div id="app"></div>
</body>

侧边栏多级配置

可以通过缩进属于特定父项下的项来创建子列表

<!-- _sidebar.md -->

* Getting started

  * [Quick start](quickstart.md)
  * [Writing more pages](more-pages.md)
  * [Custom navbar](custom-navbar.md)
  * [Cover page](cover.md)

* Configuration
  * [Configuration](configuration.md)
  * [Themes](themes.md)

封面

设置为true，并创建： _coverpage.md

<!-- index.html -->

<script>
  window.$docsify = {
    coverpage: true
  }
</script>

<!-- _coverpage.md -->

![logo](../images/ngxcode.svg)

# 编程驿站

> 编程驿站内部文档，项目使用docsify开源搭建

[开始](#docsify)

右上角角标GITHUB配置

window.$docsify = {
    repo: 'docs/',
    // or
    repo: 'https://www.ngxcode.com/docs',
};

隐藏侧边栏

此选项将完全隐藏侧边栏，不会呈现侧面的任何内容。

window.$docsify = {
  hideSidebar: true,
};

网页

默认情况下，home.md 将被视为网站的主页，但也可以通过配置设定主页

window.$docsify = {
    // Change to /home.md
    homepage: 'home.md',

    // Or use the readme in your repo
    homepage: 'https://www.ngxcode.com/docs.md',
};

主题颜色

自定义主题颜色

window.$docsify = {
    themeColor: '#3F51B5',
};

执行脚本

在页面上执行脚本。默认情况下会打开

window.$docsify = {
  executeScript: true,
};

## This is test

<script>
    console.log(2333)
</script>

notfoundpage

加载文件：_404.md

window.$docsify = {
    notFoundPage: true,
};

加载 404 页的自定义路径：

window.$docsify = {
    notFoundPage: 'my404.md',
};

根据本地化加载正确的 404 页

window.$docsify = {
    notFoundPage: {
        '/': '_404.md',
        '/de': 'de/_404.md',
    },
};

全文搜索

默认情况下，将识别当前页面上的超链接，并将内容保存在中。您还可以指定文件的路径。localStorage

<script>
    window.$docsify = {
        search: {
            maxAge: 86400000, // Expiration time, the default one day
            paths: 'auto', // or 'auto'
            placeholder: 'Type to search',

            // Localization
            placeholder: {
                '/zh-cn/': '搜索',
                '/': 'Type to search'
            },

            noData: 'No Results!',

            // Localization
            noData: {
                '/zh-cn/': '找不到结果',
                '/': 'No Results'
            },
        }
    }
</script>
<script src="../docsify/search.js"></script>

嵌入文件

您可以将这些文件嵌入为视频、音频、iframe 或代码块，甚至标记文件甚至可以直接嵌入到文档中。

例如，下面是一个嵌入的标记文件。您只需这样做：

[filename](_media/example.md ':include')

然后，的内容将直接显示在这里;example.md

嵌入式文件类型

目前，文件扩展名会自动识别并以不同的方式嵌入

支持以下类型：

iframe ，.html.htm
记价，.markdown.md
音频 .mp3
视频，.mp4.ogg
代码其他文件扩展名

当然，您可以强制指定类型。例如，可以通过设置来嵌入标记文件作为代码块。:type=code

[filename](_media/example.md ':include :type=code')