Markdown: Difference between revisions

From miki
Jump to navigation Jump to search
 
(One intermediate revision by the same user not shown)
Line 8: Line 8:
* [https://github.com/joeyespo/grip GRIP — an offline MarkDown viewer] (see tip further down also)
* [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
;Review
Line 22: Line 23:
=== Syntax ===
=== Syntax ===
;Links
;Links
<source lang=markdown>
<source lang=text>
This is a [link to Markdown](https://daringfireball.net/projects/markdown/).
This is a [link to Markdown](https://daringfireball.net/projects/markdown/).
</source>
</source>


;Bullets
;Bullets
<source lang=markdown>
<source lang=text>
* First bullet.
* First bullet.
- Sub-bullet one.
- Sub-bullet one.
Line 35: Line 36:


Bullets must be separated from normal paragraph with a BLANK line:
Bullets must be separated from normal paragraph with a BLANK line:
<source lang=markdown>
<source lang=text>
A normal paragraph.
A normal paragraph.


Line 43: Line 44:


Continuation line require BLANK line as well:
Continuation line require BLANK line as well:
<source lang=markdown>
<source lang=text>
* First bullet.
* First bullet.


Line 52: Line 53:


A better way is to use <code><br/></code>:
A better way is to use <code><br/></code>:
<source lang=markdown>
<source lang=text>
* First bullet.
* First bullet.
<br/>Continuation line, better.
<br/>Continuation line, better.

Latest revision as of 04:56, 30 June 2023

Links

References
Tools
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">