| title | description | published | date | tags | editor | dateCreated |
|---|---|---|---|---|---|---|
Drafting in Markdown |
true |
2022-03-01 03:38:59 UTC |
markdown |
2021-08-18 10:57:57 UTC |
Markdown is a lightweight markup language that is widely supported. While Markdown is significantly easier to use than XML it is also less powerful and is less standardised. Consequently the Markdown toolchains are very popular but the tools are not interchangeable as they use different syntaxes.
- Choose a Markdown toolchain from the list below
- The chosen toolchain will normally include its own template, which you then edit with your choice of text editor.
- If you require automated builds then consider the Github workflow.
- Process your edited I-D using the IETF Author Tools web service.
The following Markdown toolchains have been reported in common use by I-D authors.
kramdown-rfc is an open source text processor that converts files written in its proprietary markdown syntax into RFCXML. This is by far the most commonly used Markdown toolchain for I-Ds.
The Author Tools web service supports kramdown-rfc as one of its backend processors.
mmark is an open source text processor that converts files written in its proprietary markdown syntax into RFCXML.
The Author Tools web service supports mmark as one of its backend processors.
internet-draft-template and i-d-template are a pair of tools that work together together to provide an automated Markdown I-D build system in GitHub. Behind the scenes, they use kramdown-rfc as the Markdown processor but can be configured to use mmark or even an RFCXML processor.
To use these tools you start by creating a new repository using internet-draft-template. The new created repository includes a template Markdown file and the automation features of i-d-template.
Authors writing in Markdown may find the following tools helpful:
bibxml2md converts BibXML references into Markdown. See References in RFCXML for more details.
draftr provides a live on-screen rendering using kramdown-rfc. This tool is no longer maintained, see kdwatch below instead.
kdwatch is a locally installable live-update rendering display.
vscode-livepreview is a VS Code extension from Microsoft that can preview the HTML document rendering. It does this by hosting a local HTTP server that can be accessed via the internal VS Code browser or an external browser. Can be combined with any "build on save" approach for a more live-update type workflow.