Nim
Nim copied to clipboard
Implement Markdown automatic links extension
Summary
Adopt the implicit_header_references extension for both normal section references and Nim smart doc links. This is a part of work for converting from RST to Markdown markup.
Description
Example:
Type relations
==============
Convertible relation
--------------------
Markdown's CommonMark spec allows only links with the explicit target:
Ref [Convertible relation](#type-relations-convertible-relation)
While in RST we can have just:
Ref `Convertible relation`_
Fortunately there is the implicit_header_references extension from Pandoc Markdown, which allows to skip target section:
**Ref [Convertible relation]()**
To summarize:
* Old RST ways of referencing:
- manual `Convertible relation <#type-relations-convertible-relation>`_
- automatic `Convertible relation`_
* New Markdown ways:
- manual [Convertible relation](#type-relations-convertible-relation)
- **automatic, suggested here: [Convertible relation]()**
Also the whole point of Nim extension (which implement https://github.com/nim-lang/RFCs/issues/125) — smart doc links is to avoid inputting a complex target anchor format when referencing Nim's symbol. Applying the current suggestion here:
* old RST links:
- manual `iterator walkdir (dir: string) <#walkDir.i,string>`_
- auto `iterator walkdir (dir: string)`_
* Markdown links:
- manual [iterator walkDir (dir: string)](#walkDir.i,string)
- **suggested [iterator walkdir (dir: string)]()**
Alternatives
Input only standard Markdown links.