[markdown/en] add chapters on table of contents and markdownlint (#4273)

* feat (Markdown-en): add info on markdownlint and table of contents

* fix (Markdown-cs-cz): fix typos

* fix (Markdown-en): keep lines short

* fix (Markdown-en): add further reading

* fix (Markdown-cs-cz): add further reading

Co-authored-by: Tomas Hartman <tomash@xcroco.com>

2 files changed, 81 insertions, 22 deletions

diff --git a/cs-cz/markdown.html.markdown b/cs-cz/markdown.html.markdown
index c01d25a6..50a69107 100644
--- a/cs-cz/markdown.html.markdown
+++ b/cs-cz/markdown.html.markdown
@@ -40,6 +40,7 @@ specifickou vlastnost daného parseru.
   - [Klávesové zkratky](#klávesové-zkratky)
   - [Tabulky](#tabulky)
 - [Markdownlint](#markdownlint)
+- [Reference](#reference)
 
 ## HTML Elementy
 
@@ -99,7 +100,7 @@ __Stejně jako tento.__
 Ve verzi Markdownu od GitHubu máme k dispozici také přeškrtnutí:
 
 ```md
-~~Tento text je přeškrtlý.~~
+~~Tento text je přeškrtnutý.~~
 ```
 
 ## Odstavce
@@ -133,7 +134,7 @@ Blokové citace se dělají jednoduše uvozením řádku znakem >.
 > Toto je bloková citace. Můžete dokonce
 > manuálně rozdělit řádky, a před každý vložit >, nebo nechat vaše řádky 
 > jakkoli dlouhé, ať se zarovnají samy.
-> Je to jedno, pokud vždy začinají symbolem `>`.
+> Je to jedno, pokud vždy začínají symbolem `>`.
 
 > Použít můžu i více než jednu úroveň
 >> odsazení.
@@ -176,7 +177,7 @@ je třeba vždy překontrolovat, že číslování funguje správně. -->
 1. Položka dvě
 1. Položka tři
 
-<!-- (Toto zobrazí to samě, jako příklad nad tím.) -->
+<!-- (Toto zobrazí to samé, jako příklad nad tím.) -->
 ```
 
 Můžete také tvořit podseznamy:
@@ -191,12 +192,12 @@ Můžete také tvořit podseznamy:
 ```
 
 Vytvořit lze i zaškrtávací seznamy. Takto lze vytvořit seznam s HTML checkboxy.
-(Boxy níže bez 'x' jsou nezašktrnuté checkboxy.)
+(Boxy níže bez 'x' jsou nezaškrtnuté checkboxy.)
 
 ```md
 - [ ] První úkol, který je třeba dokončit
 - [ ] Druhý úkol na dodělání
-Tento box bude zašktrnutý
+Tento box bude zaškrtnutý
 - [x] Tento úkol byl dokončen
 ```
 
@@ -351,7 +352,7 @@ kurzívou, tak hvězdičky vyescapuji `\`: \*tento text bude obklopený hvězdi�
 ### Klávesové zkratky
 
 ```md
-<!-- V Markdownu od GitHubu můžete použít tag <kbd> k označení klaves na 
+<!-- V Markdownu od GitHubu můžete použít tag <kbd> k označení kláves na 
 počítači -->
 
 Váš počítač přestal pracovat? Zkuste
@@ -385,18 +386,21 @@ validity a čitelnosti Markdownu kódu.
 
 ---
 
-> _Pozn. překladatele:_ Tento text vznikl jako překlad původního článku, který
-> vznikl v roce 2013, který byl po obsahové stránce naposledy editován v roce
-> 2015 a kombinace původního českého překladu z roku 2015. Některé informace v
-> tomto článku, zejména ty, týkající se specifických vlastnostní parserů
-> markdownu tak již dnes mohou být zasrtaralé.
->
-> Za účelem aktualizace tohoto článku jsem přidal kapitoly o
-> [generování obsahů](#obsahy), které mj. využívá i tento článek a o
-> [Markdownlintu](#markdownlint).
-
----
+## Reference
 
 Pro více informací doporučujeme oficiální článek o syntaxi od Johna Grubera
  [zde](http://daringfireball.net/projects/markdown/syntax) a skvělý tahák od
  Adama Pritcharda [zde](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
+
+---
+
+> _Pozn. překladatele:_ Tento text vznikl jako překlad původního článku, který
+> pochází z roku 2013 a kombinace původního českého překladu z roku 2015.
+> Některé informace v tomto článku, zejména ty, týkající se specifických
+> vlastností parserů markdownu tak již dnes mohou být zastaralé.
+
+Aktuální informace o specifických vlastnostech různých implementací Markdownu
+můžete nalézt zde (v angličtině):
+
+- [Markdown pro GitHub](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+- [Markdown pro GitLab](https://docs.gitlab.com/ee/user/markdown.html)
diff --git a/markdown.html.markdown b/markdown.html.markdown
index cf4286e2..60ca1323 100644
--- a/markdown.html.markdown
+++ b/markdown.html.markdown
@@ -3,12 +3,13 @@ language: markdown
 contributors:
     - ["Dan Turkel", "http://danturkel.com/"]
     - ["Jacob Ward", "http://github.com/JacobCWard/"]
+    - ["Tomáš Hartman", "https://github.com/tomas-hartman"]
 filename: markdown.md
 ---
 
 
-Markdown was created by John Gruber in 2004. It's meant to be an easy to read 
-and write syntax which converts easily to HTML (and now many other formats as 
+Markdown was created by John Gruber in 2004. It's meant to be an easy to read
+and write syntax which converts easily to HTML (and now many other formats as
 well).
 
 Markdown also varies in implementation from one parser to a next. This
@@ -17,16 +18,25 @@ specific to a certain parser.
 
 - [HTML Elements](#html-elements)
 - [Headings](#headings)
-- [Simple Text Styles](#simple-text-styles)
+- [Simple text styles](#simple-text-styles)
 - [Paragraphs](#paragraphs)
 - [Lists](#lists)
 - [Code blocks](#code-blocks)
 - [Horizontal rule](#horizontal-rule)
 - [Links](#links)
+  - [Table of contents](#table-of-contents)
 - [Images](#images)
 - [Miscellany](#miscellany)
+  - [Auto-links](#auto-links)
+  - [Auto-links for emails](#auto-links-for-emails)
+  - [Escaping characters](#escaping-characters)
+  - [Keyboard keys](#keyboard-keys)
+  - [Tables](#tables)
+- [Markdownlint](#markdownlint)
+- [Further reading](#further-reading)
 
 ## HTML Elements
+
 Markdown is a superset of HTML, so any HTML file is valid Markdown.
 
 ```md
@@ -49,6 +59,7 @@ text you want to be in that element by a number of hashes (#).
 ##### This is an <h5>
 ###### This is an <h6>
 ```
+
 Markdown also provides us with two alternative ways of indicating h1 and h2.
 
 ```md
@@ -81,6 +92,7 @@ GitHub, we also have strikethrough:
 ```md
 ~~This text is rendered with strikethrough.~~
 ```
+
 ## Paragraphs
 
 Paragraphs are a one or multiple adjacent lines of text separated by one or
@@ -119,6 +131,7 @@ Block quotes are easy and done with the > character.
 ```
 
 ## Lists
+
 Unordered lists can be made using asterisks, pluses, or hyphens.
 
 ```md
@@ -155,6 +168,7 @@ render the numbers in order, but this may not be a good idea.
 1. Item two
 1. Item three
 ```
+
 (This renders the same as the above example)
 
 You can also use sublists
@@ -217,7 +231,7 @@ highlighting of the language you specify after the \`\`\`
 
 ## Horizontal rule
 
-Horizontal rules (`<hr/>`) are easily added with three or more asterisks or 
+Horizontal rules (`<hr/>`) are easily added with three or more asterisks or
 hyphens, with or without spaces.
 
 ```md
@@ -235,11 +249,13 @@ the text to display in hard brackets [] followed by the url in parentheses ()
 ```md
 [Click me!](http://test.com/)
 ```
+
 You can also add a link title using quotes inside the parentheses.
 
 ```md
 [Click me!](http://test.com/ "Link to Test.com")
 ```
+
 Relative paths work too.
 
 ```md
@@ -266,7 +282,27 @@ There is also "implicit naming" which lets you use the link text as the id.
 
 But it's not that commonly used.
 
+### Table of contents
+
+Some Markdown flavors even make use of the combination of lists, links and
+headings in order to create tables of contents. In this case, heading titles in
+lowercase are prepended with hash (`#`) and are used as link ids. Should the
+heading have multiple words, they will be connected with a hyphen (`-`), that
+also replaces some special characters. (Some other special characters are
+omitted though.)
+
+```md
+- [Heading](#heading)
+- [Another heading](#another-heading)
+- [Chapter](#chapter)
+  - [Subchapter <h3 />](#subchapter-h3-)
+```
+
+Nontheless, this is a feature that might not be working in all Markdown
+implementations the same way.
+
 ## Images
+
 Images are done the same way as links but with an exclamation point in front!
 
 ```md
@@ -278,7 +314,9 @@ And reference style works as expected.
 <pre><code class="highlight">!&#x5b;<span class="nv">This is the alt-attribute.</span>][<span class="ss">myimage</span>]
 
 &#x5b;<span class="nv">myimage</span>]: <span class="sx">relative/urls/cool/image.jpg</span> <span class="nn">"if you need a title, it's here"</span></code></pre>
+
 ## Miscellany
+
 ### Auto-links
 
 ```md
@@ -301,13 +339,14 @@ in italics, so I do this: \*this text surrounded by asterisks\*.
 
 ### Keyboard keys
 
-In GitHub Flavored Markdown, you can use a `<kbd>` tag to represent keyboard 
+In GitHub Flavored Markdown, you can use a `<kbd>` tag to represent keyboard
 keys.
 
 ```md
 Your computer crashed? Try sending a
 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd>
 ```
+
 ### Tables
 
 Tables are only available in GitHub Flavored Markdown and are slightly
@@ -319,6 +358,7 @@ cumbersome, but if you really want it:
 | Left-aligned | Centered | Right-aligned |
 | blah         | blah     | blah          |
 ```
+
 or, for the same results
 
 ```md
@@ -327,5 +367,20 @@ Col 1 | Col2 | Col3
 Ugh this is so ugly | make it | stop
 ```
 
+## Markdownlint
+
+In order to simplify work with Markdown and to unify its coding style,
+`Markdownlint` has been created. This tool is available also as a plugin for
+some IDEs and can be used as an utility to ensure validity and readability of
+Markdown.
+
 ---
+
+## Further reading
+
 For more info, check out John Gruber's official post of syntax [here](http://daringfireball.net/projects/markdown/syntax) and Adam Pritchard's great cheatsheet [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
+
+If you want to learn more on some major Markdown flavors' features, see:
+
+- [GitHub flavored Markdown](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+- [GitLab flavored Markdown](https://docs.gitlab.com/ee/user/markdown.html)