Some markdown syntax difference with GitBook

GitBook(Legacy) support code syntax with following syntax

`` ` ``

HonKit does not support it.

Workaround:

<code>`</code>

Probably, this changes is caused by kramed to @honkit/markup-it https://github.com/GitbookIO/gitbook-markdown/commit/0981578985933b9e3acd24adcb7cabb7e2c7849b#diff-e8acc63b1e238f3255c900eed37254b8

Related

https://github.com/asciidwango/js-primer/pull/1200

[azu]

Proposal: Downgrade markdown parser to kramed

Current HonKit has some issues on Markdown parser that is based on markup-it@2.

We can get more compatibility with GitBook Legacy by downgrading markdown parser. This is temporary action in v3.

Probably, next major version will change it.

Background

• GitBook v3(stable) use https://github.com/GitbookIO/kramed
• GitBook v4(beta) use markup-it@2
• HonKit use HonKit Markdown Parser based on markup-it@ 2

Incompatible with GitBook Legacy plugin

Some plugin depended on kramed parser #82

• gitbook-plugin-uml
• (Please tell us if you found)

Incompatible with CommonMark

GitBook v4(beta) and HonKit Markdown Parser can not parse CommonMark syntax correctly

For example,

`` ` ``

and

~~~md
 ```mermaid
 graph TD;
   A-->B;
   A-->C;
   B-->D;
   C-->D;
 ```
~~~

kramed can parse these. Maybe, It is marked based parser and it close to CommonMark behavior

Action

• Use gitbook-markdown@1.3.2 or Create fork of gitbook-markdown@1.3.2 as @honkit/markdown-legacy

- const markdownParser = require("@honkit/markdown");
+ const markdownParser = require("@honkit/markdown-legacy");

It will improve GitBook(legacy) compatible and It help you to smooth migrate from GitBook.

Future of Markdown parser

In V4 #15 ?

I have two proposals.

• Parser plugin https://github.com/honkit/honkit/issues/84
• Rewrite markdown parser with existing markdown parser library

Parser plugin https://github.com/honkit/honkit/issues/84

Currently, user can not select parser as plugin. Probably, we can do it.

So, HonKit user will select @honkit/markdown or @honkit/markdown-legacy, or own custom parser. It includes asciidoc parser.

If a user want to use gitbook-plugin-uml, the user @honkit/markdown-legacy.

Rewrite markdown parser with existing markdown parser library

We want to get more CommonMark compatible in the future. I think, It is good that we use remark or Marked. These Markdown parser is compatible with CommonMark and we can add custom sytntax like # Title {#title-id}

We can not get incentive from original Markdown parser like kramed or markup-it.

📝 Actually, kramed is a fork of old marked

kramed did want to support custom syntax like mathjax. It was the reason for creating kramed.

Why fork marked ?

marked hasn’t been evolving as much as it could be lately and due to our needs with GitBook, we need features such as robust mathjax support and want to strive closer to the rising kramdown standard. https://github.com/GitbookIO/kramed

But GitBook/HonKit has supported mathjax by mathjax plugin. In other words, We not need to extend the parser.

So, We want to get rid of full scratched markdown parser. It make maintaince cost.

📝 Custom parser that is used remark or Marked is needed for basic backward compatible.

[azu]

https://github.com/honkit/honkit/releases/tag/v3.5.1 releaed. https://github.com/honkit/honkit/releases/tag/v3.5.1 use @honkit/markdown-legacy that is based on GitBook v3 parser.