Configure docsify to use markdown-it

[infinitecompute]

Feature request

Enable the use of markdown-it renderer instead of marked.

What problem does this feature solve?

Docsify is an incredibly well designed documentation generator and its ease of use with Github pages makes it well suited to that purpose. Docsify uses the marked renderer.

Unfortunately, the markdown tool ecosystem is very fragmented and it is difficult to choose feature rich markdown editing tools that will render with high fidelity across static website generation frameworks. On the editing side, HackMD (& CodiMD) is a pack leader for collaboration on Github based markdown. The HackMD VSCode extension also provides a great developer experience. It uses the modern and extensible markdown-it renderer. Its plugin model is allowing it to evolve fast and create the kind of modern content that is expected in blogs, docs, and websites.

What does the proposed API look like?

Not an API change, but presumably it involves swapping out the underlying node packages

These are the markdown-it dependencies in HackMD:

  "dependencies": {
    "markdown-it": "^10.0.0",
    "markdown-it-abbr": "^1.0.4",
    "markdown-it-container": "^2.0.0",
    "markdown-it-deflist": "^2.0.3",
    "markdown-it-footnote": "^3.0.2",
    "markdown-it-imsize": "^2.0.1",
    "markdown-it-ins": "^2.0.0",
    "markdown-it-mark": "^2.0.0",
    "markdown-it-mathjax": "^2.0.0",
    "markdown-it-regexp": "^0.4.0",
    "markdown-it-sub": "^1.0.0",
    "markdown-it-sup": "^1.0.0",
    "markdown-it-task-checkbox": "^1.0.6",
    "markdown-it-emoji": "^1.4.0"
  }

How should this be implemented in your opinion?

I believe that markdown-it's extensibility makes it a great default choice for docsify and having more future-proof. Alternatively, I would be happy to have instructions for swapping out the renderer.

Are you willing to work on this yourself?

Yes. Assuming I am not missing some reason why this isn't pluggable. I would need assistance from docsify core contributors.

[infinitecompute]

I created a markdown-it branch in my fork to see what would break if I cut it over. Looks like entities parsing in acorn is breaking.

[anikethsaha]

I thought for this a while back. We can have this if its not breaking change. feel free to submit a PoC.

[anikethsaha]

let us know if you need any help 👍

[jack9603301]

I'm thinking about whether it's better to use tui.editor, a powerful markdown editor / parser, which has the parsing and rendering module to handle markdown. At the same time, tui.editor's powerful extension function can better expand the users of the publisher, although we don't need its editor module!

[jack9603301]

My WP markdown plug-in will decide to use Tui. Editor to provide users with a better editing and rendering experience! If it can be supported, then the documents I write in the future may have a way to provide the same rendering effect as Tui. Editor!

[jack9603301]

The repo of tui.editor is at https://github.com/nhn/tui.editor

[anikethsaha]

actually we need a parser instead of an editor and I think they dont expose any parser. let me know if they do that

[jack9603301]

It does separate the two modules. Take the official CDN as an example. The markdown viewer is located at the following address:
https://uicdn.toast.com/editor/latest/toastui-editor-viewer.js

[jack9603301]

You can check the official documentation for such an editor / parser. See if it can be used and more suitable for application, but tui.editor needs to input a DOM element and the raw content of markdown for parsing, such as:

js:

const viewer = new Viewer({
  el: document.querySelector('#viewer'),
  height: '600px',
  initialValue: '# hello'
});

viewer.getHtml();

[anikethsaha]

we cant use cdn in core and also, i dont think that is the parser code which you shared.

[jack9603301]

The official document of tui.editor is as follows:
https://nhn.github.io/tui.editor/latest/

[jack9603301]

In fact, it can be introduced by NPM or yarn's nodejs package management tool,
the address is:

node_modules/@toast-ui/editor/dist/toastui-editor-viewer

[anikethsaha]

can you share their parser link ?

[jack9603301]

const viewer = new Viewer({
  el: document.querySelector('#viewer'),
  height: '600px',
  initialValue: '# hello'
});

viewer.getHtml();

It's just an example from the official website that parses the markdown syntax of # hello and outputs HTML!

[jack9603301]

  "dependencies": {
    "@toast-ui/editor": "^2.0.1",
    "@toast-ui/editor-plugin-chart": "^1.0.0",
    "@toast-ui/editor-plugin-code-syntax-highlight": "^1.0.0",
    "@toast-ui/editor-plugin-color-syntax": "^1.0.0",
    "@toast-ui/editor-plugin-table-merged-cell": "^1.0.0",
    "@toast-ui/editor-plugin-uml": "^1.0.0",
    "codemirror": "^5.52.2",
    "eve": "^0.5.4",
    "highlight.js": "^9.18.1",
    "jquery": "^3.4.1",
    "katex": "^0.11.1",
    "markdown-it": "^10.0.0",
    "squire-rte": "^1.9.0",
    "to-mark": "^1.1.9"
  }

This is the configuration of package. json from WP reliablemd.You can use NPM or yarn to install it, and the relative path of the disk isnode_modules/@toast-ui/editor/dist/toastui-editor-viewer.js

[jack9603301]

Of course, I'm just suggesting.

[jack9603301]

In general, I use the following code to install:

npm install @toast-ui/editor

or

yarn add @toast-ui/editor

The relevant links are as follows:

https://nhn.github.io/tui.editor/latest/#-install

[jack9603301]

The official website is as follows:
https://ui.toast.com/tui-editor/
The official website documents are as follows:
https://nhn.github.io/tui.editor/latest/

[anikethsaha]

thanks for the links. I will take a look.
I would still prefer markdown-it though if there is not much difference.

[jack9603301]

Thanks, because I chose WP RMD when I developed it, I know it is an excellent markdown renderer!

[infinitecompute]

Thanks @jack9603301, I haven't used Toast and I'm happy to see that it uses markdown-it in your package list! As @anikethsaha notes the fragmentation is on the renderer/parser side. It looks like we get the most bang for the buck by having Docsify rendering be configurable for markdown-it + choice of renderer plugins.

@anikethsaha, what is the best way for me to enlist your help debugging the entity parser
issue I'm seeing in my branch? Shall I post the error log?

[anikethsaha]

Shall I post the error log?

yea sure

[infinitecompute]

app.log

Looks like I'm missing punycode.

[anikethsaha]

Looks like I'm missing punycode.

I think yea, can you. also, I think markdown-it has a dep acorn cause we are not using it. May be you need to re-install the dependencies.

[yzhang-gh]

My +1 for the markdown-it parser. I really like the extensibility of markdown-it as a VSCode Markdown plugin maintainer.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[zappala]

markdown-it has some great plugins that extend basic markdown functionality. Does the current markdown parser have any equivalent?

[gpetrov]

It is a shame that this issue got closed by the stale bot - can it be reopened?

[infinitecompute]

Sorry, I don't have the ability to reopen it.

[fyuniv]

Any progress on supporting markdown-it?

[sosiristseng]

It's probably on Docsify v5 #1061

[jhildenbiddle]

Arise, zombie issue! Arise!

We are currently pushing towards releasing v5 which will be backwards compatible with v4. For this reason, changing markdown parsers for v5 is not an option. I have set the milestone for this issue to v6 to ensure it is considered when that works begins.