gitbook 入门教程之比较代码块差别 diff 插件

在 markdown 文档中显示代码之间的差别的 Gitbook 插件

English | 中文

🏠 主页

• Github : https://snowdreams1006.github.io/gitbook-plugin-diff/
• GitLab: https://snowdreams1006.gitlab.io/gitbook-plugin-diff/
• Gitee : https://snowdreams1006.gitee.io/gitbook-plugin-diff/

屏幕截图

• 用法

{% diff method="diffJson" %}

{
"name": "gitbook-plugin-simple-mind-map",
"version": "0.2.1",
"description": "A gitBook plugin for generating and exporting mind map within markdown"
}

{
"name": "gitbook-plugin-diff",
"version": "0.2.1",
"description": "A gitbook plugin for showing the differences between the codes within markdown"
}

{% enddiff %}

• 预览

{
-   "description": "A gitBook plugin for generating and exporting mind map within markdown",
-   "name": "gitbook-plugin-simple-mind-map",
+   "description": "A gitbook plugin for showing the differences between the codes within markdown",
+   "name": "gitbook-plugin-diff",
    "version": "0.2.1"
}

用法

步骤＃1-更新 book.json 文件

在您的 gitbook 的 book.json 文件中,将 diff 添加到 plugins 列表中.

这是最简单的示例:

{
    "plugins": ["diff"]
}

此外,受支持的配置选项以下:

"gitbook": {
    "properties": {
        "method": {
            "type": "string",
            "title": "jsdiff api method",
            "required": false,
            "default": "diffLines",
            "description": "some supported methods such as diffChars or diffWords or diffWordsWithSpace or diffLines or diffTrimmedLines or diffSentences or diffCss or diffJson or diffArrays"
        },
        "options": {
            "type": "object",
            "title": "jsdiff api options",
            "required": false,
            "description": "some methods may not support options"
        }
    }
}

步骤＃2- 使用 markdown 语法

diff 插件支持 method 和 options 等选项生成差别代码块.

这是在 markdown 文件中基本使用语法:

{% diff %}

old code

new code

{% enddiff %}

下面有一些基本示例:

Diff.diffChars(oldStr, newStr[, options])

区分两个文本块，逐个字符比较。

返回

返回更改对象列表（请参见下文）。

选项

• ignoreCase ： true忽略大小写差别。默认为false 。

示例

• 用法

设置 method="diffChars"以调用 Diff.diffChars(oldStr, newStr[, options])方法

{% diff method="diffChars" %}

cat

cap

{% enddiff %}

• 预览

ca
- t
+ p

Diff.diffWords(oldStr, newStr[, options])

区分两个文本块，逐字比较，忽略空格。

返回

返回更改对象列表（请参见下文）。

选项

• ignoreCase ：与diffChars相同。

示例

• 用法

设置 method="diffWords"来调用 Diff.diffWords(oldStr, newStr[, options])方法

{% diff method="diffWords" %}

beep boop

beep boob blah

{% enddiff %}

• 预览

beep
- boop
+ boob

+ blah

Diff.diffWordsWithSpace(oldStr, newStr[, options])

区分两个文本块，逐字比较，将空白视为有效。

返回

返回更改对象列表（请参见下文）。

选项

• ignoreCase ：与diffWords相同。

示例

• 用法

设置 method="diffWordsWithSpace"以调用 Diff.diffWordsWithSpace(oldStr, newStr[, options])方法

{% diff method="diffWordsWithSpace" %}

beep boop

beep boob blah

{% enddiff %}

• 预览

beep
- boop
+ boob blah

Diff.diffLines(oldStr, newStr[, options])

比较两个文本块，逐行比较。

返回

返回更改对象列表（请参见下文）。

选项

• ignoreWhitespace ： true忽略前导和尾随空白。这与diffTrimmedLines相同
• newlineIsToken ： true newlineIsToken换行符视为单独的标记。这容许换行结构的更改独立于行内容而发生，并照此处理。一般，这是diffLines更加人性化的形式，而且diffLines更适合于补丁和其余计算机友好的输出。

示例

• 用法

设置 method="diffLines"以调用 Diff.diffLines(oldStr, newStr[, options])方法

{% diff method="diffLines",options={"newlineIsToken":true} %}

beep boop
the cat is palying with cap
what

beep boob blah
the cat is palying with cap
who

{% enddiff %}

• 预览

- beep boop

+ beep boob blah

  the cat is palying with cap

- what

+ who

Diff.diffTrimmedLines(oldStr, newStr[, options])

区分两个文本块，逐行比较，忽略前导和尾随空格。

返回

返回更改对象列表（请参见下文）。

选项

• ignoreWhitespace ：与diffLines相同。
• newlineIsToken ：同diffLines 。

示例

• 用法

设置 method="diffTrimmedLines"来调用 Diff.diffTrimmedLines(oldStr, newStr[, options])方法

{% diff method="diffTrimmedLines",options={"newlineIsToken":true} %}

beep boop
the cat is palying with cap
what

beep boob blah
the cat is palying with cat
who

{% enddiff %}

• 预览

- beep boop
  the cat is palying with cap
  what

+ beep boob blah
  the cat is palying with cat
  who

Diff.diffSentences(oldStr, newStr[, options])

区分两个文本块，逐句比较。

返回

返回更改对象列表（请参见下文）。

示例

• 用法

设置 method="diffSentences"来调用 Diff.diffSentences(oldStr, newStr[, options])方法

{% diff method="diffSentences" %}

beep boop
the cat is palying with cap
what

beep boob blah
the cat is palying with cat
who

{% enddiff %}

• 预览

- beep boop
  the cat is palying with cap
  what

+ beep boob blah
  the cat is palying with cat
  who

Diff.diffCss(oldStr, newStr[, options])

比较两个文本块，比较 CSS 标记。

返回

返回更改对象列表（请参见下文）。

示例

• 用法

设置 method="diffCss"来调用 Diff.diffCss(oldStr, newStr[, options])方法

{% diff method="diffCss" %}

.markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4, .markdown-section h5, .markdown-section h6 {

margin-top: 1.275em;
margin-bottom: .85em;
font-weight: 700;

}

.markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4, .markdown-section h5, .markdown-section h6 {

margin-top: 1.5em;
margin-bottom: 1em;

}

{% enddiff %}

• 预览

.markdown-section h1, .markdown-section h2, .markdown-section h3, .markdown-section h4, .markdown-section h5, .markdown-section h6 {
    margin-top:
- 1.275em
+ 1.5em
  ;
    margin-bottom:
- .85em
+ 1em
  ;
-
    font-weight: 700;

}

Diff.diffJson(oldObj, newObj[, options])

比较两个 JSON 对象，比较每一个对象上定义的字段。在此比较中，字段的顺序等并不重要。

返回

返回更改对象列表（请参见下文）。

示例

• 用法

设置 method="diffJson"来调用 Diff.diffJson(oldObj, newObj[, options])方法

{% diff method="diffJson" %}

{
"name": "gitbook-plugin-simple-mind-map",
"version": "0.2.1",
"description": "A gitBook plugin for generating and exporting mind map within markdown"
}

{
"name": "gitbook-plugin-diff",
"version": "0.2.1",
"description": "A gitbook plugin for showing the differences between the codes within markdown"
}

{% enddiff %}

• 预览

{
-   "description": "A gitBook plugin for generating and exporting mind map within markdown",
-   "name": "gitbook-plugin-simple-mind-map",
+   "description": "A gitbook plugin for showing the differences between the codes within markdown",
+   "name": "gitbook-plugin-diff",
    "version": "0.2.1"
}

Diff.diffArrays(oldArr, newArr[, options])

比较两个数组，比较每一个项目是否严格相等（===）。

返回

返回更改对象列表（请参见下文）。

选件

• comparator ：用于自定义相等性检查的function(left, right)

示例

• 用法

设置 method="diffArrays"以调用 Diff.diffArrays(oldArr, newArr[, options])方法

{% diff method="diffArrays" %}

[

"Vue",
"Python",
"Java",
"flutter",
"springboot",
"docker",
"React",
"小程序"

]

[

"Vuejs",
"Nodejs",
"Java",
"flutter",
"springboot",
"docker",
"React"

]

{% enddiff %}

• 预览

[
-   Vue
-   Python
+   Vuejs
+   Nodejs
    Java
    flutter
    springboot
    docker
    React
-   小程序
]

步骤＃3- 运行 gitbook 命令

1. 运行 gitbook install .它将自动为您的 gitbook 安装 diff 插件.

该步骤仅须要容许一次便可.

gitbook install

或者您能够运行 npm install gitbook-plugin-diff 命令本地安装 gitbook-plugin-diff 插件.

npm install gitbook-plugin-diff

1. 像往常同样构建您的书（ gitbook build ）或服务（ gitbook serve ）.

gitbook serve

示例

• 官方文档配置文件

https://github.com/snowdreams1006/gitbook-plugin-diff/blob/master/docs/book.json

{
    "plugins": ["diff"],
    "pluginsConfig": {
        "diff": {
            "method": "diffJson"
        }
    }
}

• 官方示例配置文件

https://github.com/snowdreams1006/gitbook-plugin-diff/blob/master/example/book.json

{
    "plugins": ["diff"],
    "pluginsConfig": {
        "diff": {
            "method": "diffJson"
        }
    }
}

• 示例book.json文件

{
    "plugins": ["diff"]
}

或者您能够将 method 设置为默认方法用于代码之间进行比较方式：

{
    "plugins": ["diff"],
    "pluginsConfig": {
        "diff": {
            "method": "diffChars"
        }
    }
}

或者您能够根据方法将 options 设置为默认选项.

{
    "plugins": ["diff"],
    "pluginsConfig": {
        "diff": {
            "method": "diffChars",
            "options": {
              "ignoreCase": true
            }
        }
    }
}

注意 ：若是您的书尚未建立,以上代码段能够用做完整的 book.json 文件.

致谢

• A javascript text differencing implementation. : https://github.com/kpdecker/jsdiff
• get colors in your node.js console : https://github.com/Marak/colors.js
• GitBook CodeGroup Plugin : https://github.com/lwhiteley/gitbook-plugin-codegroup

做者

👤 snowdreams1006

• 网站 : snowdreams1006.tech
• GitHub : @snowdreams1006
• 电子邮件 : snowdreams1006@163.com

贡献

欢迎贡献，问题和功能要求！随时检查问题页面 。

支持

若是这个项目对您有帮助，请给个星星 ！

版权

版权全部 ©2019 snowdreams1006 。

该项目是MIT许可的。

若是本文对你有所帮助,不用赞扬,也没必要转发,直接点赞留言告诉鼓励一下就能够啦!