Documentation
¶
Overview ¶
Command md2html converts Markdown to HTML.
It is tailored for converting the Markdown sources of the Elvish website (https://elv.sh) to HTML.
It first applies a pre-processing step that expands the following macros:
@module declares the file to be the reference doc for a module.
This has two effects: it declares a docset anchor immediately, and causes the inserts elvdocs for the module at the end of the current to be inserted at the end of the file. It should appear at the beginning of the reference doc for a module.
@dl expands to a binary download link.
The processed Markdown source is then converted to HTML using a codec based on md.HTMLCodec, with the following additional features:
Autogenerated ID for each heading
Self link for each heading
Table of content (optional, turn on with <!-- toc -->)
Implicit links to elvdoc targets when link destination is empty and link text is a single code span - for example, [`put`]() has destination builtin.html#put (or just #put within doc for the builtin module itself)
Section numbers for headings (optional, turn on with <-- number-sections -->)
Syntax highlighting of code blocks with language elvish or elvish-transcript
Headers for code blocks when a code fence has additional text after the language tag (like foo.elv in "```elvish foo.elv")
The "ttyshot" language tag in a fence code block causes the content to be treated as a reference to a ttyshot and expanded.
The comment block for optional features should appear before the main text, and can contain multiple features (like <!-- toc number-sections -->).
A note on the implicit elvdoc target feature: ideally, we would like to use Markdown's shortcut link feature and let a simple [`put`] have an implicit target of builtin.html#put. Doing this has two prerequisites:
The src.elv.sh/pkg/md package must be modified to support shortcut links.
The src.elv.sh/pkg/elvdoc package must be modified to add declarations of these shortcut targets. This is because shortcut links in Markdown must be declared, otherwise [`put`] is just literal [<code>put</code>].
This is feasible for targets in the same file, but much more tricky for targets in a different module. For example, if the elvdoc of a:foo references b:bar, we need to insert a declaration for b:bar to the elvdoc of a:foo.
Hence we've settled on using an empty target for now. It is a bit ugly but hopefully not too ugly.
Source Files