[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>

1 files changed, 60 insertions, 5 deletions

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)