From 20ed6195324c84e2001a775c84abb59a5d207267 Mon Sep 17 00:00:00 2001 From: tomas-hartman <44980733+tomas-hartman@users.noreply.github.com> Date: Sat, 27 Nov 2021 21:19:54 +0100 Subject: [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 --- markdown.html.markdown | 65 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 60 insertions(+), 5 deletions(-) (limited to 'markdown.html.markdown') 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
###### This is an
``` + 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 (`
`) are easily added with three or more asterisks or +Horizontal rules (`
`) 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

](#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. 
![This is the alt-attribute.][myimage]
 
 [myimage]: relative/urls/cool/image.jpg "if you need a title, it's here"
+ ## 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 `` tag to represent keyboard +In GitHub Flavored Markdown, you can use a `` tag to represent keyboard keys. ```md Your computer crashed? Try sending a Ctrl+Alt+Del ``` + ### 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) -- cgit v1.2.3 From 22861c5c74292180f9f9fdadaafa7afb4455d2f6 Mon Sep 17 00:00:00 2001 From: taivlam <47955724+taivlam@users.noreply.github.com> Date: Sun, 16 Jan 2022 03:43:14 +0000 Subject: [markdown/en] Fixed minor typos & backticks * Added some periods at end of sentences for consistent style * Line 238 previously rendered as "` - even though GitHub preview correctly displayed 3 consecutive backticks, i.e.: ``` (hopefully this fix will work) * Line 281 missed the capitalization of "This" --- markdown.html.markdown | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'markdown.html.markdown') diff --git a/markdown.html.markdown b/markdown.html.markdown index 60ca1323..a6000910 100644 --- a/markdown.html.markdown +++ b/markdown.html.markdown @@ -169,9 +169,9 @@ render the numbers in order, but this may not be a good idea. 1. Item three ``` -(This renders the same as the above example) +(This renders the same as the example above.) -You can also use sublists +You can also use sublists. ```md 1. Item one @@ -203,7 +203,7 @@ a line with four spaces or a tab. ``` You can also re-tab (or add an additional four spaces) for indentation -inside your code +inside your code. ```md my_array.each do |item| @@ -211,13 +211,13 @@ inside your code end ``` -Inline code can be created using the backtick character `` ` `` +Inline code can be created using the backtick character `` ` ``. ```md John didn't even know what the `go_to()` function did! ``` -In GitHub Flavored Markdown, you can use a special syntax for code +In GitHub Flavored Markdown, you can use a special syntax for code. 
 ```ruby
@@ -227,7 +227,7 @@ end
 ```
The above text doesn't require indenting, plus GitHub will use syntax -highlighting of the language you specify after the \`\`\` +highlighting of the language you specify after the opening ```. ## Horizontal rule @@ -278,7 +278,7 @@ There is also "implicit naming" which lets you use the link text as the id. 
[This][] is a link.
 
-[this]: http://thisisalink.com/
+[This]: http://thisisalink.com/ But it's not that commonly used. -- cgit v1.2.3 From 873314f253a37932f836354b482fcda03f0bf505 Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Fri, 11 Nov 2022 10:38:32 +0100 Subject: add link to markdownlint It already was mentioned, the additional link eases installation and thus promotes its subsequent use. --- markdown.html.markdown | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'markdown.html.markdown') diff --git a/markdown.html.markdown b/markdown.html.markdown index a6000910..cfc0ddf3 100644 --- a/markdown.html.markdown +++ b/markdown.html.markdown @@ -40,9 +40,9 @@ specific to a certain parser. Markdown is a superset of HTML, so any HTML file is valid Markdown. ```md - ``` @@ -370,9 +370,10 @@ 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. +`Markdownlint` has been created. Available as a +[separate tool](https://github.com/markdownlint/markdownlint) +as well as a plugin for some IDEs, it can be used to ensure validity and +readability of Markdown. --- -- cgit v1.2.3 From bba9f7df211d63293e2a957872d156a0a6dfcd48 Mon Sep 17 00:00:00 2001 From: Marcel Ribeiro-Dantas Date: Sat, 10 Dec 2022 12:05:34 -0300 Subject: Fixes typos in many different English articles Signed-off-by: Marcel Ribeiro-Dantas --- markdown.html.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'markdown.html.markdown') diff --git a/markdown.html.markdown b/markdown.html.markdown index cfc0ddf3..fefb60f6 100644 --- a/markdown.html.markdown +++ b/markdown.html.markdown @@ -298,7 +298,7 @@ omitted though.) - [Subchapter

](#subchapter-h3-) ``` -Nontheless, this is a feature that might not be working in all Markdown +Nonetheless, this is a feature that might not be working in all Markdown implementations the same way. ## Images -- cgit v1.2.3 From 365200ce0aa1ee13fe48ef939b9bfc1da136044d Mon Sep 17 00:00:00 2001 From: Boris Verkhovskiy Date: Wed, 3 Apr 2024 03:53:28 -0700 Subject: Fix syntax highlighting for Markdown --- markdown.html.markdown | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) (limited to 'markdown.html.markdown') diff --git a/markdown.html.markdown b/markdown.html.markdown index fefb60f6..ee213083 100644 --- a/markdown.html.markdown +++ b/markdown.html.markdown @@ -207,7 +207,7 @@ inside your code. ```md my_array.each do |item| - puts item + puts item end ``` @@ -219,12 +219,13 @@ John didn't even know what the `go_to()` function did! In GitHub Flavored Markdown, you can use a special syntax for code. -
-```ruby
+````md
+```ruby
 def foobar
-    puts "Hello world!"
+  puts "Hello world!"
 end
-```
+``` +```` The above text doesn't require indenting, plus GitHub will use syntax highlighting of the language you specify after the opening ```. @@ -264,11 +265,13 @@ Relative paths work too. Markdown also supports reference style links. -
[Click this link][link1] for more info about it!
-[Also check out this link][foobar] if you want to.
+```md
+[Click this link][link1] for more info about it!
+[Also check out this link][foobar] if you want to.
 
-[link1]: http://test.com/ "Cool!"
-[foobar]: http://foobar.biz/ "Alright!"
+[link1]: http://test.com/ "Cool!" +[foobar]: http://foobar.biz/ "Alright!" +``` The title can also be in single quotes or in parentheses, or omitted entirely. The references can be anywhere in your document and the reference IDs @@ -276,9 +279,11 @@ can be anything so long as they are unique. There is also "implicit naming" which lets you use the link text as the id. -
[This][] is a link.
+```md
+[This][] is a link.
 
-[This]: http://thisisalink.com/
+[This]: http://thisisalink.com/ +``` But it's not that commonly used. @@ -311,9 +316,11 @@ Images are done the same way as links but with an exclamation point in front! And reference style works as expected. -
![This is the alt-attribute.][myimage]
+```md
+![This is the alt-attribute.][myimage]
 
-[myimage]: relative/urls/cool/image.jpg "if you need a title, it's here"
+[myimage]: relative/urls/cool/image.jpg "if you need a title, it's here" +``` ## Miscellany -- cgit v1.2.3