Feature: Commonmark compliant markdown renderer

[tmpfs]

This issue represents the existing discussions on updating the AST to support a Commonmark compliant renderer.

Related forum discussions:

http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287
http://talk.commonmark.org/t/customizable-renderer-output-in-commonmark-js/1146/12

Originally discussed in #6.

[tmpfs]

Issue #82 should be resolved first in my opinion.

[nicojs]

I've created a commonmark complaint renderer here:
https://github.com/nicojs/html2commonmark

Example:

var renderer = new require('html2commonmark').Renderer();
var reader = new require('commonmark').Parser();
var aPieceOfCake = renderer.render(reader.parse('a `piece` of _cake_'));

[tmpfs]

Thanks for the input Nico but this discussion is about this library and it's ability to support converting back to Commonmark from the AST generated.

Your implementation here:

https://github.com/nicojs/html2commonmark/blob/master/src/MarkdownRenderer.ts

Is not in Javascript. We would like a Javascript version built on top of this Javascript reference implementation.

Maybe you have some ideas about how the AST needs to be modified to support the currently missing data? Please see:

http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287/25

[nicojs]

My version is indeed written in TypeScript, which is transpiled to JavaScript before use. As you can see:

git clone https://github.com/nicojs/html2commonmark
cd html2commonmark
npm install
npm install -g grunt-cli
grunt build
vim dist/server/MarkdownRenderer.js

I did my work based on the cmark reference implementation (as was suggested to me in this comment by @jgm). I didn't know a markdown renderer was wanted, otherwise i would have created a pull request.

EDIT: I don't checkin the dist folder as it is build output, however the dist folder is published in the npm package

[tmpfs]

My bad Nico, maybe you can let us know if there is anything missing from the AST that would help to get the job done, I am personally keen to get all the relevant info in the AST so that implementing a Markdown renderer that reproduces a document as close to the original as possible is an easy task.

[nicojs]

@tmpfs ok, let's say i can find the time to do this.

You want the list as a comment on this issue? Or somewhere else?

[tmpfs]

Thanks @nicojs, I have added a little to this thread:

http://talk.commonmark.org/t/issues-to-resolve-before-1-0-release/1287/26?u=tmpfs

What I think we need to work out is all the things missing from the AST that at the moment prevent a clean round trip to commonmark, if you were able to add your experiences there I think it would be invaluable.

[mattyclarkson]

I really would like a commonmark renderer so that I can create a commonmark formatter CLI. Is there still interest in a markdown renderer? Seems like #82 is moving forward well.

[jgm]

If you're interested in it, there's interest!

[mattyclarkson]

Excellent. Would it make sense to wait for #82 splits the renders out into separate projects or shall I get a PR together to submit a render/commonmark.js? I can always rebase/refactor into another project later if needed.

[jgm]

I don't think there's been any progress on #82 for over a year (though I do think it's a good idea). Perhaps you could contact @tmpfs and see if they want help on it? One might have reservations about adding a commonmark renderer as part of commonmark.js, since that adds to the package size and it's a feature not everyone needs.

[mattyclarkson]

I would agree. I feel like all the renders should be an opt in from a package. I'll have a look at #82 to get up to speed.

[tmpfs]

Hello folks,

I have had it done and working (in production) for quite a while now, I was awaiting guidance from @jgm on how to proceed creating separate renderer npm packages.

I have just merged upstream into my fork here (all tests continue to pass): https://github.com/tmpfs/commonmark.js and use these renderers in my markdown tools here: https://github.com//mkdoc/mkdoc.

My feeling is that we should bundle the abstract renderer and then separate out into:

• commonmark-html
• commonmark-xml

I also have more renderers here which we should also move to separate packages:

• https://github.com/mkdoc/mkout/blob/master/lib/text.js
• https://github.com/mkdoc/mkout/blob/master/lib/yaml.js (useful for debugging the AST)
• https://github.com/mkdoc/mkout/blob/master/lib/man.js (maybe rename to commonmark-troff)

Happy to work on this some more as I think it is a useful and logical separation of concerns.