Nim icon indicating copy to clipboard operation
Nim copied to clipboard

Implement Markdown automatic links extension

Open a-mr opened this issue 2 years ago • 0 comments

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.

Additional Information

a-mr avatar Aug 01 '22 10:08 a-mr