Implement Pandoc Markdown concise link extension (#20304)

* Implement Pandoc Markdown concise link extension

This implements https://github.com/nim-lang/Nim/issues/20127.
Besides reference to headings we also support doing references
to Nim symbols inside Nim modules.

Markdown:
```
Some heading
------------

Ref. [Some heading].
```

Nim:
```
proc someFunction*() ...

... ## Ref. [someFunction]
```

This is substitution for RST syntax like `` `target`_ ``.
All 3 syntax variants of extension from Pandoc Markdown are supported:
`[target]`, `[target][]`, `[description][target]`.

This PR also fixes clashes in existing files, particularly
conflicts with RST footnote feature, which does not work with
this PR (but there is a plan to adopt a popular [Markdown footnote
extension](https://pandoc.org/MANUAL.html#footnotes) to make footnotes work).

Also the PR fixes a bug that Markdown links did not work when `[...]`
section had a line break.

The implementation is straightforward since link resolution did not
change w.r.t. RST implementation, it's almost only about new syntax
addition. The only essential difference is a possibility to add a custom
link description: form `[description][target]` which does not have an
RST equivalent.

* fix nim 1.0 gotcha

doc/idetools.md

@@ -239,7 +239,7 @@ symbol for which idetools returns valid output.
 skConst
 -------
 
-| **Third column**: module + [n scope nesting] + const name.
+| **Third column**: module + \[n scope nesting] + const name.
 | **Fourth column**: the type of the const value.
 | **Docstring**: always the empty string.
 
@@ -254,7 +254,7 @@ skConst
 skEnumField
 -----------
 
-| **Third column**: module + [n scope nesting] + enum type + enum field name.
+| **Third column**: module + \[n scope nesting] + enum type + enum field name.
 | **Fourth column**: enum type grouping other enum fields.
 | **Docstring**: always the empty string.
 
@@ -269,7 +269,7 @@ skEnumField
 skForVar
 --------
 
-| **Third column**: module + [n scope nesting] + var name.
+| **Third column**: module + \[n scope nesting] + var name.
 | **Fourth column**: type of the var.
 | **Docstring**: always the empty string.
 
@@ -291,7 +291,7 @@ defined, since at that point in the file the parser hasn't processed
 the full line yet. The signature will be returned complete in
 posterior instances of the iterator.
 
-| **Third column**: module + [n scope nesting] + iterator name.
+| **Third column**: module + \[n scope nesting] + iterator name.
 | **Fourth column**: signature of the iterator including return type.
 | **Docstring**: docstring if available.
 
@@ -308,7 +308,7 @@ posterior instances of the iterator.
 skLabel
 -------
 
-| **Third column**: module + [n scope nesting] + name.
+| **Third column**: module + \[n scope nesting] + name.
 | **Fourth column**: always the empty string.
 | **Docstring**: always the empty string.
 
@@ -325,7 +325,7 @@ skLabel
 skLet
 -----
 
-| **Third column**: module + [n scope nesting] + let name.
+| **Third column**: module + \[n scope nesting] + let name.
 | **Fourth column**: the type of the let variable.
 | **Docstring**: always the empty string.
 
@@ -346,7 +346,7 @@ defined, since at that point in the file the parser hasn't processed
 the full line yet. The signature will be returned complete in
 posterior instances of the macro.
 
-| **Third column**: module + [n scope nesting] + macro name.
+| **Third column**: module + \[n scope nesting] + macro name.
 | **Fourth column**: signature of the macro including return type.
 | **Docstring**: docstring if available.
 
@@ -384,7 +384,7 @@ Note that at the moment the word `proc` is returned for the
 signature of the found method instead of the expected `method`.
 This may change in the future.
 
-| **Third column**: module + [n scope nesting] + method name.
+| **Third column**: module + \[n scope nesting] + method name.
 | **Fourth column**: signature of the method including return type.
 | **Docstring**: docstring if available.
 
@@ -402,7 +402,7 @@ This may change in the future.
 skParam
 -------
 
-| **Third column**: module + [n scope nesting] + param name.
+| **Third column**: module + \[n scope nesting] + param name.
 | **Fourth column**: the type of the parameter.
 | **Docstring**: always the empty string.
 
@@ -427,7 +427,7 @@ While at the language level a proc is differentiated from others
 by the parameters and return value, the signature of the proc
 returned by idetools returns also the pragmas for the proc.
 
-| **Third column**: module + [n scope nesting] + proc name.
+| **Third column**: module + \[n scope nesting] + proc name.
 | **Fourth column**: signature of the proc including return type.
 | **Docstring**: docstring if available.
 
@@ -446,7 +446,7 @@ returned by idetools returns also the pragmas for the proc.
 skResult
 --------
 
-| **Third column**: module + [n scope nesting] + result.
+| **Third column**: module + \[n scope nesting] + result.
 | **Fourth column**: the type of the result.
 | **Docstring**: always the empty string.
 
@@ -467,7 +467,7 @@ defined, since at that point in the file the parser hasn't processed
 the full line yet. The signature will be returned complete in
 posterior instances of the template.
 
-| **Third column**: module + [n scope nesting] + template name.
+| **Third column**: module + \[n scope nesting] + template name.
 | **Fourth column**: signature of the template including return type.
 | **Docstring**: docstring if available.
 
@@ -496,7 +496,7 @@ posterior instances of the template.
 skType
 ------
 
-| **Third column**: module + [n scope nesting] + type name.
+| **Third column**: module + \[n scope nesting] + type name.
 | **Fourth column**: the type.
 | **Docstring**: always the empty string.
 
@@ -512,7 +512,7 @@ skType
 skVar
 -----
 
-| **Third column**: module + [n scope nesting] + var name.
+| **Third column**: module + \[n scope nesting] + var name.
 | **Fourth column**: the type of the var.
 | **Docstring**: always the empty string.