文档工具 docsify

docsify 介绍

doscifyopen in new window(和 GitBook 一样的好东西) 是一个动态生成文档网站的工具。不同于 GitBookopen in new window、Hexoopen in new window 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。

接下来我们将使用doscifyopen in new window写一本属于自己的电子书。

快速开始

1. 安装

推荐安装 docsify-cli 工具，可以方便创建及本地预览文档网站。

    npm i docsify-cli -g

2. 初始化项目

建议在项目的 ./docs 目录里写文档，可以通过下面的方式初始化项目：

    docsify init ./docs

3. 开始写文档

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

index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件直接编辑 docs/README.md 就能更新网站内容，当然也可以写多个页面。

4.本地预览网站

运行一个本地服务器通过 docsify serve 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。

   docsify serve

?> 至此你已经编辑自己的电子书了。

docsify 常用插件

打开你的docs文件夹，找到index.html,可以看到如下代码，其中name是文档名称，repo是 GitHub 地址：

<div id="app"></div>
<script>
  window.$docsify = {
    name: "",
    repo: ""
  };
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

?> 接下来配置常用的插件,在index.html文件中添加对应的代码：

1. 封面

封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。渲染效果如本文档。

<script>
  window.$docsify = {
    coverpage: true
  };
</script>
<script src="//unpkg.com/docsify"></script>

系统自动创建的_coverpage.md就是你的封面，内容如下：

    ![logo](_media/icon.svg)

    # docsify

    > A magical documentation site generator.

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

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

!> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。

2. 侧边栏

默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，效果如当前的文档的侧边栏。首先配置 loadSidebar选项，具体配置规则见配置项#定制侧边栏open in new window。

<script>
  window.$docsify = {
    loadSidebar: true
  };
</script>
<script src="//unpkg.com/docsify"></script>

接着创建 _sidebar.md 文件，内容如下:

* [首页](zh-cn/) * [指南](zh-cn/guide)

!> 需要在文档根目录创建 .nojekyll 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。

_sidebar.md 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages 则从 /zh-cn/_sidebar.md 获取文件，如果不存在则从 /_sidebar.md 获取。

当然你也可以配置 alias 避免不必要的回退过程。

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      "/.*/_sidebar.md": "/_sidebar.md"
    }
  };
</script>

3. 代码高亮

内置的代码高亮工具是 Prism，默认支持 CSS、JavaScript 和 HTML。如果需要高亮其语言——例如 PHP——可以手动引入代码高亮插件。

<script src="//unpkg.com/docsify"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
<script src="//unpkg.com/prismjs/components/prism-php.js"></script>

4. 复制到剪贴板

在所有的代码块上添加一个简单的 Click to copy 按钮来允许用户从你的文档中轻易地复制代码。由@jperasmus 提供。

<script src="//unpkg.com/docsify-copy-code"></script>

5. 分页导航 Pagination

docsify 的分页导航插件，由@imyelo 提供。

<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>

6. 忽略副标题

在标题旁添加{docsify-ignore} 或在页面的第一个标题上使用 {docsify-ignore-all}

该标题不会出现在侧边栏的目录中。

## 第一个标题 {docsify-ignore-all}

### 副标题 {docsify-ignore}

?> 更多关于 docsify 的配置项，请查看docsify 文档open in new window

Markdown 语法

1. 段落和换行

一个 Markdown 段落是由一个或多个连续的文本行组成，它的前后要有一个以上的空行。普通段落不该用空格或制表符来缩进。

2. 标题

类 Atx 形式则是在行首插入 1 到 6 个 #，对应到标题 1 到 6 阶，例如：

    # 这是 H1

    ## 这是 H2

    ###### 这是 H6

类 Setext 形式是用底线的形式，利用 =（最高阶标题）和 -（第二阶标题），例如：

    This is an H1
    =============

    This is an H2
    -------------

3. 分隔线

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线：

    * * *

    ***

    *****

    - - -

    ---------------------------------------

4. 引用

在每行的最前面加上>就可以了：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 也允许你偷懒只在整个段落的第一行最前面加上>：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

5. 代码块

和程序相关的写作或是标签语言原始码通常会有已经排版好的代码区块，通常这些区块我们并不希望它以一般段落文件的方式去排版，而是照原来的样子显示。

要在 Markdown 中建立代码区块很简单，只要简单地缩进 4 个空格或是 1 个制表符就可以，也可以用三个反引号(```这是代码块```)例如，下面的输入：

    这是一个普通段落：
        这是一个代码区块。

6. 列表

Markdown 支持有序列表和无序列表。

无序列表：

    -   Red
    -   Green
    -   Blue

有序列表则使用数字接着一个英文句点：

    1.  Bird
    2.  McHale
    3.  Parish

列表项目可以包含多个段落，段落开头都必须缩进 4 个空格或是 1 个制表符：

    1.  This is a list item with two paragraphs. Lorem ipsum dolor
    sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    mi posuere lectus.

    Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    sit amet velit.

    2.  Suspendisse id sem consectetuer libero luctus adipiscing.

7. 链接

中括号里是链接字符，小括号里是链接地址，链接地址后面可以跟一个链接提示，就像这样：

    [an example](http://example.com/ "Title")

你也使用相对路径：

    [About](/about)

8. 图片

图片的语法和链接的基本一样，只需要在前面加一个英文叹号

    ![Alt text](/path/to/img.jpg)

9. 强调

用两个 * 或两个_包起来表示粗体，例如：

    **double asterisks**

    __double underscores__

10. 代码

如果要标记一小段行内代码，你可以用反引号把它包起来（`），例如：

    Use the `printf()` function.

11. 自动链接

就像这样：

    <http://example.com/>

会转为：

    <a href="http://example.com/">http://example.com/</a>

12. 反斜杠

反斜杠用来转义，比如：

    \*literal asterisks\*

转义的方法是反斜杠后跟下面这些字符：

    \   反斜线
    `   反引号
    *   星号
    _   底线
    {}  花括号
    []  方括号
    ()  括弧
    #   井字号
    +   加号
    -   减号
    .   英文句点
    !   惊叹号

13. 表格

键名	描述	代码
title	设置书本的标题	"title" : "学习笔记"
author	作者的相关信息	"author" : "Bluej"
description	本书的简单描述	"description" : markdown 语法"

?> 以上列举常用的 markdown 语法，具体请查看MarkDown 官方教程open in new window

# 文档工具 docsify

# docsify 介绍

# 快速开始

# 1. 安装

# 2. 初始化项目

# 3. 开始写文档

# 4.本地预览网站

# docsify 常用插件

# 1. 封面

# 2. 侧边栏

# 3. 代码高亮

# 4. 复制到剪贴板

# 5. 分页导航 Pagination

# 6. 忽略副标题

# Markdown 语法

# 1. 段落和换行

# 2. 标题

# 3. 分隔线

# 4. 引用

# 5. 代码块

# 6. 列表

# 7. 链接

# 8. 图片

# 9. 强调

# 10. 代码

# 11. 自动链接

# 12. 反斜杠

# 13. 表格