Add markdown widget to docs

[erquhart]

The markdown widget parses markdown documents to an AST, so non-abstract particulars are lost, such as whether a code block used four spaces or fences. We need to document these transformations so that users can anticipate them. This issue should first serve to collect the transformations, and can be closed with a documentation update PR.

Transformations:

• Images, links, and footnotes that separate the reference from the definition will be combined
• All code blocks become fenced
• Bold markers become asterisks
• Emphasis markers become underscores

Update: the markdown widget itself needs to be added to the new widgets docs.

[verythorough]

For the markdown widget config documentation, @hcavalieri has done an awesome job adding it to PR #866. For documenting the transformations, I'm wondering about the best location for this, debating between one of these options:

• in the markdown section of the widgets doc (might make for an overly long section)
• in the soon-to-be-added user guide, as a part of a full page about using the rich text editor (might feel off-puttingly technical for some content editors)
• in its own doc specifically about the rich text editor/markdown widget (might not be enough content to justify a whole page)

I'd love to hear others' thoughts on this.

[erquhart]

I'd expect a split between user docs and implementor docs. Not all widgets will require user docs, but this one will.

[verythorough]

Yeah, I think we need a guide to the rich text editor in the user docs for sure. What I'm not sure about is whether the markdown transformation details in the OP should belong there, or in one of the other two locations I listed.

[erquhart]

I think both, but catered to each. For user docs, I'd just note that using the visual editor will result in formatting optimizations to the underlying markdown document, and also note that references and footnotes aren't supported. The more fine-grained details could go in the implementation docs, but maybe we could cross link to that for users that want more advanced info.

[erquhart]

@verythorough if you're good with that, add the status: accepted label to signal that it's ready to work.

[hdoro]

I agree with Shawn that we could have two different approaches for each and believe that displaying both is the way to go, but if you allow me to shoot some ideas:

• In the user docs when we talk about Markdown we could give them some references for Markdown courses so then they can be fully aware of how it works - for example there's Wes Bos's Mastering Markdown
• For the implementation docs, personally I think a whole page for it would be overkill, unless we pack it with sections such as extending the editor - with more examples other than the current YouTube video one - and give readers a full, holistic view about the editing process.
• However, I do understand that extending widgets should be separate, so what we could do is add a new subsection to the current widgets page (under the widgets cloud) with all this information about the markdown widget compile process for whoever wants to read about. This way, the widget's tab isn't so long and keeps straight to the point, and heavier users of the editor could refer to the subsection in the header links on the sidebar.
• We should go the extra mile and add a visual representation of the changes: on one side, the content in the editor, and on the other (or under it) a code block with the parsed .md file.

(Sorry for writing so much 😅 )

[erquhart]

Honestly, I think a long entry for the markdown widget is fine - it's a very complicated widget, night and day from the others in that regard, and there may be more like it in the future. Perhaps it will eventually be split out of the core and get a dedicated repo in the future, but a long entry is okay for now.

+1 for visuals and a helpful markdown learning link in the user docs.

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

[martinjagodic]

Closing because the markdown widget is documented here: https://decapcms.org/docs/widgets/#markdown