Markdown: Difference between revisions
Jump to navigation
Jump to search
(→Links) |
(→Links) |
||
| (10 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
;References |
;References |
||
* [https://guides.github.com/features/mastering-markdown/ Mastering MarkDown (GitHub flavor)] |
* [https://guides.github.com/features/mastering-markdown/ Mastering MarkDown (GitHub flavor)] |
||
* [http://hyperpolyglot.org/lightweight-markup Hyperpolyglot - Markdown, reStructuredText, AsciiDoc, Mediawiki, Org-mode] |
|||
;Tools |
;Tools |
||
* [https://github.com/joeyespo/grip GRIP — an offline MarkDown viewer] (see tip further down also) |
|||
* [https://jbt.github.io/markdown-editor/ Markdown viewer and editor (GitHub flavor)] |
* [https://jbt.github.io/markdown-editor/ Markdown viewer and editor (GitHub flavor)] |
||
* [https://rust-lang.github.io/mdBook/ mdBook] Make MarkDown books |
|||
;Review |
|||
* [http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/ Why You Shouldn’t Use “Markdown” for Documentation] |
|||
:This author advocates instead AsciiDoc (using [https://asciidoctor.org/ Asciidoctor]), or reStructuredText (using [http://www.sphinx-doc.org/en/stable/usage/quickstart.html Sphinx]). |
|||
== Reference== |
|||
=== Flavors === |
|||
There are at least 3 main Markdown flavors: |
|||
* Original flavor from John Gruber. |
|||
* GitHub flavor (with eg. syntax highlighting extension). |
|||
* Pandoc flavor. |
|||
=== Syntax === |
|||
;Links |
|||
<source lang=text> |
|||
This is a [link to Markdown](https://daringfireball.net/projects/markdown/). |
|||
</source> |
|||
;Bullets |
|||
<source lang=text> |
|||
* First bullet. |
|||
- Sub-bullet one. |
|||
- Another sub-bullet. |
|||
* Second bullet. |
|||
</source> |
|||
Bullets must be separated from normal paragraph with a BLANK line: |
|||
<source lang=text> |
|||
A normal paragraph. |
|||
* First bullet. |
|||
* Second bullet. No need for blank line. |
|||
</source> |
|||
Continuation line require BLANK line as well: |
|||
<source lang=text> |
|||
* First bullet. |
|||
Continuation line, but will render badly. |
|||
* Second bullet. No need for blank line. |
|||
</source> |
|||
A better way is to use <code><br/></code>: |
|||
<source lang=text> |
|||
* First bullet. |
|||
<br/>Continuation line, better. |
|||
* Second bullet. No need for blank line. |
|||
</source> |
|||
== Tips == |
== Tips == |
||
=== Preview standard MarkDown === |
|||
Use {{deb|markdown}} package. |
|||
<source lang="c"> |
|||
sudo apt install markdown |
|||
</source> |
|||
Then, for instance, using {{deb|entr}}: |
|||
<source lang="c"> |
|||
echo README.md | entr sh -c 'markdown README.md > README.html' |
|||
</source> |
|||
This will generate a new {{file|README.html}} every time {{file|README.md}} is modified. |
|||
=== Preview Markdown before pushing to GitHub === |
|||
Use the wonderful tool [https://github.com/joeyespo/grip GRIP — GitHub README Instant Preview]. |
|||
<source lang=bash> |
|||
sudo apt install grip |
|||
cd /my/repo |
|||
grip # Now, open up browser to http://localhost:6419/ |
|||
</source> |
|||
=== Comments in Markdown === |
=== Comments in Markdown === |
||
We abuse link tags [https://stackoverflow.com/questions/4823468/comments-in-markdown]: |
We abuse link tags [https://stackoverflow.com/questions/4823468/comments-in-markdown]: |
||
[//]: # (This may be the most platform independent comment) |
[//]: # (This may be the most platform independent comment) |
||
=== Align images === |
|||
To center image on GitHub [https://gist.github.com/DavidWells/7d2e0e1bc78f4ac59a123ddf8b74932d]: |
|||
<source lang=text> |
|||
<p align="center"> |
|||
<img width="460" height="300" src="http://www.fillmurray.com/460/300"> |
|||
</p> |
|||
</source> |
|||
To left/right align: |
|||
<source lang=text> |
|||
<img align="left" width="100" height="100" src="http://www.fillmurray.com/100/100"> |
|||
<img align="right" width="100" height="100" src="http://www.fillmurray.com/100/100"> |
|||
</source> |
|||
Latest revision as of 04:56, 30 June 2023
Links
- References
- Mastering MarkDown (GitHub flavor)
- Hyperpolyglot - Markdown, reStructuredText, AsciiDoc, Mediawiki, Org-mode
- Tools
- GRIP — an offline MarkDown viewer (see tip further down also)
- Markdown viewer and editor (GitHub flavor)
- mdBook Make MarkDown books
- Review
- This author advocates instead AsciiDoc (using Asciidoctor), or reStructuredText (using Sphinx).
Reference
Flavors
There are at least 3 main Markdown flavors:
- Original flavor from John Gruber.
- GitHub flavor (with eg. syntax highlighting extension).
- Pandoc flavor.
Syntax
- Links
This is a [link to Markdown](https://daringfireball.net/projects/markdown/).
- Bullets
* First bullet.
- Sub-bullet one.
- Another sub-bullet.
* Second bullet.
Bullets must be separated from normal paragraph with a BLANK line:
A normal paragraph.
* First bullet.
* Second bullet. No need for blank line.
Continuation line require BLANK line as well:
* First bullet.
Continuation line, but will render badly.
* Second bullet. No need for blank line.
A better way is to use
* First bullet.
<br/>Continuation line, better.
* Second bullet. No need for blank line.
Tips
Preview standard MarkDown
Use markdown package.
sudo apt install markdown
Then, for instance, using entr:
echo README.md | entr sh -c 'markdown README.md > README.html'
This will generate a new README.html every time README.md is modified.
Preview Markdown before pushing to GitHub
Use the wonderful tool GRIP — GitHub README Instant Preview.
sudo apt install grip
cd /my/repo
grip # Now, open up browser to http://localhost:6419/
Comments in Markdown
We abuse link tags [1]:
[//]: # (This may be the most platform independent comment)
Align images
To center image on GitHub [2]:
<p align="center">
<img width="460" height="300" src="http://www.fillmurray.com/460/300">
</p>
To left/right align:
<img align="left" width="100" height="100" src="http://www.fillmurray.com/100/100">
<img align="right" width="100" height="100" src="http://www.fillmurray.com/100/100">