gitbook-plugin-diff

Welcome to gitbook-plugin-diff 👋

A gitbook plugin for showing the differences between the codes within markdown

English | 中文

🏠 Homepage

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

Screenshot

• usage

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

• preview

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

Usage

Step #1 - Update book.json file

In you gitbook's book.json file, add diff to plugins list.

Here is simplest example :

{
    "plugins": ["diff"]
}

In addition, the supported configuration options are as follows :

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

Step #2 - Use in markdown file

diff support method and options for generating diff block code.

Here is basic grammar in your markdown file :

{% diff %}
```
old code
```
```
new code
```
{% enddiff %}

And there are some examples :

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

diffs two blocks of text, comparing character by character.

Return

Returns a list of change objects (See below).

Option

• ignoreCase: true to ignore casing difference. Defaults to false.

Examples

• usage

set method="diffChars" to call Diff.diffChars(oldStr, newStr[, options]) method

{% diff method="diffChars" %}
```js
cat
```
```js
cap
```
{% enddiff %}

• preview

  ca
- t
+ p

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

diffs two blocks of text, comparing word by word, ignoring whitespace.

Return

Returns a list of change objects (See below).

Option

• ignoreCase: Same as in diffChars.

Examples

• usage

set method="diffWords" to call Diff.diffWords(oldStr, newStr[, options]) method

{% diff method="diffWords" %}
```bash
beep boop  
```
```bash
beep boob blah
```
{% enddiff %}

• preview

  beep 
- boop
+ boob

+ blah

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

diffs two blocks of text, comparing word by word, treating whitespace as significant.

Return

Returns a list of change objects (See below).

Option

• ignoreCase: Same as in diffWords.

Examples

• usage

set method="diffWordsWithSpace" to call Diff.diffWordsWithSpace(oldStr, newStr[, options]) method

{% diff method="diffWordsWithSpace" %}
```bash
beep boop  
```
```bash
beep boob blah
```
{% enddiff %}

• preview

  beep 
- boop
+ boob blah

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

diffs two blocks of text, comparing line by line.

Return

Returns a list of change objects (See below).

Option

• ignoreWhitespace: true to ignore leading and trailing whitespace. This is the same as diffTrimmedLines
• newlineIsToken: true to treat newline characters as separate tokens. This allows for changes to the newline structure to occur independently of the line content and to be treated as such. In general this is the more human friendly form of diffLines and diffLines is better suited for patches and other computer friendly output.

Examples

• usage

set method="diffLines" to call Diff.diffLines(oldStr, newStr[, options]) method

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

• preview

- beep boop

+ beep boob blah

  the cat is palying with cap

- what

+ who

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

diffs two blocks of text, comparing line by line, ignoring leading and trailing whitespace.

Return

Returns a list of change objects (See below).

Option

• ignoreWhitespace: Same as in diffLines.
• newlineIsToken: Same as in diffLines.

Examples

• usage

set method="diffTrimmedLines" to call Diff.diffTrimmedLines(oldStr, newStr[, options]) method

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

• preview

- beep boop
  the cat is palying with cap
  what

+ beep boob blah
  the cat is palying with cat
  who

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

diffs two blocks of text, comparing sentence by sentence.

Return

Returns a list of change objects (See below).

Examples

• usage

set method="diffSentences" to call Diff.diffSentences(oldStr, newStr[, options]) method

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

• preview

- beep boop
  the cat is palying with cap
  what

+ beep boob blah
  the cat is palying with cat
  who

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

diffs two JSON objects, comparing the fields defined on each. The order of fields, etc does not matter in this comparison.

Return

Returns a list of change objects (See below).

Examples

• usage

set method="diffJson" to call Diff.diffJson(oldObj, newObj[, options]) method

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

• preview

{
-   "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])

diffs two arrays, comparing each item for strict equality (===).

Return

Returns a list of change objects (See below).

Options

• comparator: function(left, right) for custom equality checks

Examples

• usage

set method="diffArrays" to call Diff.diffArrays(oldArr, newArr[, options]) method

{% diff method="diffArrays" %}
```json
[
    "Vue",
    "Python",
    "Java",
    "flutter",
    "springboot",
    "docker",
    "React",
    "小程序"
]
```
```json
[
    "Vuejs",
    "Nodejs",
    "Java",
    "flutter",
    "springboot",
    "docker",
    "React"
]
```
{% enddiff %}

• preview

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

Step #3 - Run gitbook commands

1. Run gitbook install. It will automatically install diff gitbook plugin for your book. This is needed only once.

gitbook install

or you can run npm install gitbook-plugin-diff to install locally.

npm install gitbook-plugin-diff

1. Build your book (gitbook build) or serve (gitbook serve) as usual.

gitbook serve

Examples

• Official documentation configuration file

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

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

• Official example configuration file

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

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

• Sample book.json file

{
    "plugins": ["diff"]
}

or you can set method as your default method to compare between codes:

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

or you can set options as your default settings according to method:

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

Note: Above snippet can be used as complete book.json file, if your book doesn't have one yet.

Thanks

• 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

Author

👤 snowdreams1006

• Website: snowdreams1006.tech
• Github: @snowdreams1006
• Email: [e-mail]

Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

Show your support

Give a Star if this project helped you!

Copyright

Copyright © 2019 snowdreams1006.

This project is MIT licensed.