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

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

主页

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" %}

```json

{

  "name": "gitbook-plugin-simple-mind-map",

  "version": "0.2.1",

  "description": "A gitBook plugin for generating and exporting mind map within markdown"

}

```

```json

{

  "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" %}

```js

cat

```

```js

cap

```

{% enddiff %}

预览

  ca

- t

+ p

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

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

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

选项

ignoreCase ：与diffChars相同。

示例

用法

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

{% diff method="diffWords" %}

```bash

beep boop

```

```bash

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" %}

```bash

beep boop

```

```bash

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} %}

```bash

beep boop

the cat is palying with cap

what

```

```bash

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} %}

```bash

beep boop

the cat is palying with cap

what

```

```bash

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" %}

```bash

beep boop

the cat is palying with cap

what

```

```bash

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" %}

```css

.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;

}

```

```css

.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" %}

```json

{

  "name": "gitbook-plugin-simple-mind-map",

  "version": "0.2.1",

  "description": "A gitBook plugin for generating and exporting mind map within markdown"

}

```

```json

{

  "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" %}

```json

[

    "Vue",

    "Python",

    "Java",

    "flutter",

    "springboot",

    "docker",

    "React",

    "小程序"

]

```

```json

[

    "Vuejs",

    "Nodejs",

    "Java",

    "flutter",

    "springboot",

    "docker",

    "React"

]

```

{% enddiff %}

预览

[

-   Vue

-   Python

+   Vuejs

+   Nodejs

    Java

    flutter

    springboot

    docker

    React

-   小程序

]

步骤＃3- 运行 `gitbook` 命令

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

该步骤仅需要允许一次即可.

gitbook install

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

npm install gitbook-plugin-diff

像往常一样构建您的书（ 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

贡献

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

支持

如果这个项目对您有帮助，请给个星星！

版权

该项目是MIT许可的。

如果本文对你有所帮助,请动动小手点一下推荐,否则还请留言指正,如有需要,请关注个人公众号「 雪之梦技术驿站 」