Links general policy for the docs?

[Blind4Basics]

I'm going through @Kask's message on zulip, and I'm wondering if we shouldn't try to only use the [text][refLink] syntax: this way, the actual links are stored once and for all at the bottom of the file, so if ever an update is needed, it's way easier to maintain.

Opinions?

Example (the index page for the markdowns):

Codewars supports [Markdown][wiki-markdown].

More specifically, [GitHub Flavored Markdown][gfm] (strict superset of [CommonMark][common-mark]) and few [Codewars extensions][extensions].

<!-- the following lines are defining the links and aren't visible in the rendered page -->
[wiki-markdown]: https://en.wikipedia.org/wiki/Markdown
[common-mark]: https://commonmark.org/
[gfm]: https://github.github.com/gfm/
[extensions]: /references/markdown/extensions/

I'll update #74 accordingly.

[hobovsky]

I wonder if it will be really helpful since every page would contain references anyway. You won't be able to update one definition in some kind of template and have all references across all docs updated, am I right?

[Blind4Basics]

mmmh, nope, but at least, you'd have to do the change one single time per link and per page to update (the main reason, imo, is to know that if you have to check something, you just have to go to see at the very end of the page, without any risk to miss a link somewhere inside the text).

[Blind4Basics]

or maybe limit that to external links?

(but, I mean, could be useful for internal links to, if one day we need to change the names of some files... Well, I guess that the best way in the case would actually be to use so s.replace(//g,m=>...) on all the files, in that case)

[kazk]

I tend to use the referencing when the URLs gets in the way.

Codewars supports [Markdown](https://en.wikipedia.org/wiki/Markdown).

More specifically, [GitHub Flavored Markdown](https://github.github.com/gfm/) (strict superset of [CommonMark](https://commonmark.org/)) and few [Codewars extensions](/references/markdown/extensions/).

Too many URLs in between words are annoying to me.

For these, I tend to first write without the reference

Codewars supports [Markdown][].

More specifically, [GitHub Flavored Markdown][] (strict superset of [CommonMark][]) and few [Codewars extensions][].

Those acts as placeholders as I write. Then I'll add the references or just inline the URLs.

[Blind4Basics]

so, no special preferences to adopt for the docs, ok. 👍