Markdown code blocks part 2; migrate Nim Manual

[a-mr]

Besides migrating the Manual to Markdown-style code blocks (follow-up #19954 ), this PR also:

• changes headings like

  heading
  ~~~~~~~
  

  to

   ### heading
  

  since Markdown supports only === and --- while using ~~~ as an alternative syntax for code blocks
• fixes loading of files by file= in Markdown code blocks (I forgot to add the corresponding logic in prev. PR)

[AmjadHD]

What are you going to do for links: destructors <destructors.html>_ and other rst features unsupported by markdown ?

[github-actions]

Thanks for your hard work on this PR!
The lines below are statistics of the Nim compiler built from 62b81d7

Hint: mm: orc; threads: on; opt: speed; options: -d:release
163447 lines; 12.441s; 841.203MiB peakmem

[a-mr]

@AmjadHD
good question.
They need to be disabled in Markdown mode, particularly in .md files, because they interfere with Markdown _ syntax which is emphasis — (almost) the same as *.

For the case you presented one will have to use: [destructors](destructors.html).

Whether keep support to RST or not: it's not decided — lately @Araq have been pushing towards dropping RST support altogether. Though these arguments "RST is dead, Markdown has won" remind me something like "Nim is dead, C++ has won".

If RST is to be kept as an option: for documentation comments in .nim files there is a proposal to introduce module-level pragma discussed in #17987. So {.doclang: rst.} would turn RST as the documentation language for module.

There are other cases that need to be decided, most importantly RST links to local document's sections that are as simple as `Section name`_ (though they are buggy in current Nim's implementation) — it still does not have an equivalent in Markdown though one can use something like [Section name](#section-name) but that's ugly.

[AmjadHD]

@a-mr
I'm in favor of this push towards markdown, nimlsp's docstring popups are ugly because LSP doesn't support rst.

[Section name](#section-name) but that's ugly

That's subjective :)
Any Ideas of how to replace roles in markdown ?

[a-mr]

@AmjadHD

That's subjective :)

I'm thinking of borrowing of some (limited) form of the implicit_header_references extension from Pandoc Markdown.

# Heading identifiers in HTML

To link:

[Heading identifiers in HTML]()

Any Ideas of how to replace roles in markdown ?

Pandoc's extension inline_code_attributes

`<$>`{.haskell}

I found it nice that it's close to Nim's pragma syntax (may be we can even allow to put the second dot, a {.haskell.}