diff options
Diffstat (limited to 'markdown.html.markdown')
| -rw-r--r-- | markdown.html.markdown | 117 |
1 files changed, 90 insertions, 27 deletions
diff --git a/markdown.html.markdown b/markdown.html.markdown index cf4286e2..ee213083 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,22 +18,31 @@ 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 -<!--This means we can use HTML elements in Markdown, such as the comment -element, and they won't be affected by a markdown parser. However, if you -create an HTML element in your markdown file, you cannot use markdown syntax +<!--This means we can use HTML elements in Markdown, such as the comment +element, and they won't be affected by a markdown parser. However, if you +create an HTML element in your markdown file, you cannot use markdown syntax within that element's contents.--> ``` @@ -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,9 +168,10 @@ 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 +(This renders the same as the example above.) + +You can also use sublists. ```md 1. Item one @@ -189,35 +203,36 @@ 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| - puts item + puts item 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. -<pre> -<code class="highlight">```ruby +````md +```ruby def foobar - puts "Hello world!" + puts "Hello world!" end -```</code></pre> +``` +```` 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 <code>```</code>. ## 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 +250,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 @@ -248,11 +265,13 @@ Relative paths work too. Markdown also supports reference style links. -<pre><code class="highlight">[<span class="nv">Click this link</span>][<span class="ss">link1</span>] for more info about it! -[<span class="nv">Also check out this link</span>][<span class="ss">foobar</span>] if you want to. +```md +[Click this link][link1] for more info about it! +[Also check out this link][foobar] if you want to. -[<span class="nv">link1</span>]: <span class="sx">http://test.com/</span> <span class="nn">"Cool!"</span> -[<span class="nv">foobar</span>]: <span class="sx">http://foobar.biz/</span> <span class="nn">"Alright!"</span></code></pre> +[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 @@ -260,13 +279,35 @@ can be anything so long as they are unique. There is also "implicit naming" which lets you use the link text as the id. -<pre><code class="highlight">[<span class="nv">This</span>][] is a link. +```md +[This][] is a link. -[<span class="nv">this</span>]: <span class="sx">http://thisisalink.com/</span></code></pre> +[This]: http://thisisalink.com/ +``` 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-) +``` + +Nonetheless, 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 @@ -275,10 +316,14 @@ Images are done the same way as links but with an exclamation point in front! And reference style works as expected. -<pre><code class="highlight">![<span class="nv">This is the alt-attribute.</span>][<span class="ss">myimage</span>] +```md +![This is the alt-attribute.][myimage] + +[myimage]: relative/urls/cool/image.jpg "if you need a title, it's here" +``` -[<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 +346,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 +365,7 @@ cumbersome, but if you really want it: | Left-aligned | Centered | Right-aligned | | blah | blah | blah | ``` + or, for the same results ```md @@ -327,5 +374,21 @@ 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. 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. + --- + +## 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) |