Markdown Syntax Reference

Rishi Goutam

April 15, 2022—11 min read

I use markdown for writingIncluding this article. During my time at the NYC Data Science Academy, students were to write blog posts for their python, R, and machine learning projects and publish via WordpressYou can read my posts there as well.

Due to an aversion to using WordpressI need vim-bindings in my editors. It's a disability, just like my deuteranopia . and a desire to have control over my work, I decided to look into writing in plain text files. My first approach was to write in regular markdown and convert that into HTML. Quickly, I realized that Pandoc was the way to go and wrote in Pandoc-flavored markdown. I wrote a python tool using pypandoc to have it automatically convert a directory of *.md files to *.html. Pandoc’s really powerful, and has some benefits over MDX, but I needed a publishing flow that was seamless—no more copying over generated HTML files into the /public directory of a React app.

MDX is better than markdown. Shows image of MDX and markdown logos with a > symbol in between

That’s when I turned to Gatsby.js, which supports markdownx^⊕MDX = MD + TSX, which is essentially markdown plus React components. It took a while to set up my site and to create custom components to mimic Tufte–CSS, but the result has been great.

The rest of this “article” is a syntax reference—I use it often. I hope it is helpful to you as well.

Font styles
Lists
Blockquotes
Epigraphs
Notes
Horizontal Rule
Links
Tables
Code
- Code Gists
Media
Admonitions

Font styles

Standard markdown

Emphasis ¹

Text can be emphasized like _word_
Text can be strongly emphasized like **word**
Text can be very strongly emphasized like **_word_**
A part of a word can be emphasized as well

~~Strikethrough~~ text like ~~word~~

Styling with Tufte-CSS, and HTML/CSS

The first letter in a paragraph can have drop caps. Here we add some extra text to see how it wraps. Some more text so that we have at least three lines. Maybe we can keep going on and on and on and on.

<p class="dropcaps">The first letter...</p>

Text can be underlined stylishly with Tufte-CSS

<span class="tufte-underline">underlined</span>

We can begin a paragraph with small caps with Tufte-CSS

<p>
  <span class="newthought">We can begin</span> a paragraph with small caps with
  Tufte-CSS
</p>

We can create highlighted text using <mark>

<mark>highlighted text</mark>

We can create subscripts (H₂O) as well as superscripts (X²).

`H~2~0` and `X^2^`

Abbreviations

The HTML specification is maintained by the W3C.

The HTML specification
is maintained by the W3C.

_[HTML]: Hyper Text Markup Language
_[W3C]: World Wide Web Consortium

Lists

Checklists Project milestones:

Create project
Write project blog posts
Share online

Unordered list Some big technology firms:

Amazon
Microsoft
Apple
Google

Ordered list Steps to create a data science project:

Clean and merge datasets
Conduct exploratory data analysis
Manipulate data to suit models and visualizations
Create predictive models
Visualize data
Present insights

Definition list

Façade: A façade (/fəˈsɑːd/) is generally the front part or exterior of a building. It is a loan word from the French façade (pronounced [fasad]), which means 'frontage' or 'face'.

<dl>
  <dt>Façade</dt>
  <dd>
    A façade (/fəˈsɑːd/) is generally the front part or exterior of a building.
    It is a loan word from the French façade (pronounced [fasad]), which means
    'frontage' or 'face'.
  </dd>
</dl>

Blockquotes

Blockquotes can be useful if you‘re quoting someone, as in an email, or a famous saying by a famous person from a famous book.

> Blockquotes can be useful if **you**'re _quoting_ someone, as in an email, or a famous saying by a famous person from a famous book.

Epigraphs

The English language…becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easier for us to have foolish thoughts.
George Orwell, “Politics and the English Language”

<div class="epigraph">
  <blockquote>
    <p>
      The English language…becomes ugly and inaccurate because our thoughts are
      foolish, but the slovenliness of our language makes it easier for us to
      have foolish thoughts.
    </p>
    <footer>George Orwell, “Politics and the English Language”</footer>
  </blockquote>
</div>

Notes

Footnotes

Let’s say we are writing about a technique I found on stackoverflow, medium, or web² article. We can link to it via a footnote. The footnote will show up at the bottom of the page.

[^singlelinefootnote]: Footnote syntax can be found [here](https://www.markdownguide.org/extended-syntax/#footnotes)

We can also have a longer footnote³ with multiple paragraphs and even code formatting. Scroll to the bottom or click the footnote superscript number to read the footnote. The footnote includes a link back to the original text

[^longfootnote]:
    Here's one with multiple paragraphs and code.
    Indent paragraphs to include them in the footnote.

    Add as many paragraphs as you like. Note that we have a line break when we want to break up a paragraph

Sidenotes

We can have footnotes in the marginUsing footnotes along with sidenotes causes numbering-consistency issues. This allows the reader to quickly read your commentary about the topic. Although footnotes are linked back, there is some context switching involved. Sidenotes side-step this issue.

We do this by including a custom <Sidenote> component into the mdx fileSee tutorial. You might have noticed we can also pass in html to our sidenote The link to the MDX component tutorial is an <a> tag.

Some text<Sidenote note="Commentary on text" />.

Marginal notes

If you want a sidenote without footnote-style numberings, then you want a margin note^⊕This is a margin note. Notice there isn't a number preceding the note. See original Tufte–CSS write-up for more details.. It is simply a sidenote that omits the reference number. Unnumbered footnotes in the margin can also be created with the <Marginnote> component.

You might notice that on a small-width screen, such as on phones, margin notes are hidden by default—replaced by the ^⊕ symbol (⊕). Clicking on this will show the note. Similarly, for a sidenote, clicking on the number will open the sidenote.

Some text<Marginnote note="Non-numbered commentary in the margin" />.

Adding images to sidenotes and marginal notes

TODO

This is work in progress. I need to figure out how to pass images or HTML to a component from within MDX.

The current implementation gets the job done…poorly

An image with an optional caption can be added to a sidenoteWe use Gatsby.js for this site
Gatsby.js logo
Gatsby has great remark plugins with out-of-the-box MDX support! Usually… (or marginal note). We accomplish this by simply adding more html within a <Sidenote> or <Marginnote>.

These two components are essentially the same. We dangerouslySetInnerHTML on these components and tweak some classes to differentiate them.

<Sidenote note="Some note<br/><img src='/<slug>/<image>.png'<br/>Some caption" />

This is quite hacky, but it works. Unfortunately, as far as I am aware, the gatsby-remark-tufte plugin does not work with MDX, so we have to write our own custom TSX components (<Sidenote> and <Marginnote>)

Horizontal Rule

Use three or more…

hyphens,

or asterisks,

or underscores.

Hyphens

---

Asterisks

---

Underscores

---

Links

[goutam.io](https://www.goutam.io/)
<https://www.gatsbyjs.org/>

Tables

This is a pipe table

Syntax	Description
Header	Title
Paragraph	Text

| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

Use : in the second row under the headers to tell markdown align columns

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

| Right | Left | Default | Center |
| ----: | :--- | ------- | :----: |
|    12 | 12   | 12      |   12   |
|   123 | 123  | 123     |  123   |
|     1 | 1    | 1       |   1    |

This is a table with where we can be lazy by not manually specifying widths. We also omit pipes around the edges

fruit	price
apple	2.05
pear	1.37
orange	3.09

| fruit  | price |
| ------ | ----: |
| apple  |  2.05 |
| pear   |  1.37 |
| orange |  3.09 |

Code

We can inline code return "hello, world!" in a paragraph

`return "hello, world!"`

We can specify the language for syntax highlighting and can add a title (bar.py) for a code snippet if we wish.

Python

bar.py

def foo(someint: int) -> int:
    """
    returns 1 plus the input

    :param some_int: an integer
    """
    print(f"We were given {some_int} as input")
    return 1 + some_int

```python:title=bar.py
def foo(someint: int) -> int:
    """
    returns 1 plus the input

    :param some_int: an integer
    """
    print(f"We were given {some_int} as input")
    return 1 + some_int
```

JavaScript

filename.js

console.log('This is filename.js');

```js:title=filename.js
console.log('This is filename.js');
```

Shell

rm -rf ~/test

```zsh
rm -rf ~/test
```

Code diff

const App = () => {
-	return <div>This line was removed</div>;
+	return <div>This line was added</div>;
}

```diff
const App = () => {
-	return <div>This line was removed</div>;
+	return <div>This line was added</div>;
}
```

Code Gists

  
          ; bombs a city that the user inputs. must be logged in as the president
        
          (define (process-bomb-city)
        
            (if logged-in
        
                (begin
        
                  (display "Enter a city to bomb from CITIES.\n")
        
                  (let ((city (read)))
        
                    (if (assoc city cities)
        
                        (if (assoc city american-cities)
        
                            (display "War Operation Plan Response will not bomb American cities.\n")
        
                            (let* ((pair (assoc city cities))
        
                                   (population (cdr pair)))
        
                              (cond ((= 0 population)
        
                                     (display "This city has no inhabitants. No bomb has been dropped.\n"))
        
                                    ((= 0 bombs)
        
                                     (display "You do not possess any bombs. No bomb has been dropped.\n"))
        
                                    (else
        
                                     (begin
        
                                       (set! bombs (- bombs 1))
        
                                       (if (< population 3)
        
                                           (set! cities (cons (cons city 0) cities))
        
                                           (set! cities (cons (cons city (- population 3)) cities)))
        
                                       (display "You have bombed the city and killed 3 million inhabitants."))))))
        
                        (display "This city exists only in your imagination.\n"))))
        
                (display "You are not logged in. Please do so.\n")))

view raw wargames.scm hosted with ❤ by GitHub

<div class="fullwidth">

`gist:rishigoutam/42ddba9c16796a570b84#wargames.scm?highlights=86,103&lines=82-105`

</div>

Media

Images

Gatsby logo

You can also add a title, in addition to the alt. Hover over the image to read the title.

A Rishi-moji

![A Rishi-moji](./memoji.png 'Rishi Goutam's memoji')

GIFs

<figure class="fullwidth">

![Pandoc is great!](./pandoc-opt.gif)

</figure>

Iframe

<iframe
  src="https://chart-studio.plotly.com/~plotlygoutamorg/7.embed?link=false&modebar=false"
  width="1077"
  height="700"
></iframe>

Mermaid

TODO

This plugin requires puppeteer and does not work on Gatsby Cloud without configuration. Works on localhost. Need to investigate

graph LR
install[Install Plugin]
install --> configure[Configure Plugin]
configure --> draw[Draw Fancy Diagrams]

Renders as:

graph LR
install[Install Plugin]
install --> configure[Configure Plugin]
configure --> draw[Draw Fancy Diagrams]

Admonitions

We use remark-admonitions to render admonitions in markdown.

Pro tip

🪥 Brush your teeth to prevent tooth decay 🦷

Note

Note to self–add more code examples!

ls -l
total 2528
-rw-r--r--     1 rishi  staff    1966 Apr 17 09:14 README.md
drwxr-xr-x     3 rishi  staff      96 Apr 17 09:14 blog
-rw-r--r--     1 rishi  staff     415 Apr 17 15:44 gatsby-browser.js
-rw-r--r--     1 rishi  staff    5810 Apr 17 15:34 gatsby-config.js
-rw-r--r--     1 rishi  staff    2561 Apr 17 15:36 package.json
drwxr-xr-x     7 rishi  staff     224 Apr 17 09:14 projects
drwxr-xr-x     9 rishi  staff     288 Apr 17 09:14 src
-rw-r--r--     1 rishi  staff  661841 Apr 17 15:36 yarn.lock

Warning

🐕 Beware of dog (and dangerouslySetInnerHTML)

Caution

They are watching you 👀

Important!

Brush your ṫeeth ţwice a day!

Here’s the syntax

admonition.md

:::<tip|note|warning|caution|important> <Title>
<Some admonition to the reader goes here>
:::

You can use any combination of * or _ for emphasis↩
Footnote syntax can be found here ↩
Here’s one with multiple paragraphs and code. Indent paragraphs to include them in the footnote.
Add as many paragraphs as you like. Note that we have a line break when we want to break up a paragraph↩

	; bombs a city that the user inputs. must be logged in as the president
	(define (process-bomb-city)
	(if logged-in
	(begin
	(display "Enter a city to bomb from CITIES.\n")
	(let ((city (read)))
	(if (assoc city cities)
	(if (assoc city american-cities)
	(display "War Operation Plan Response will not bomb American cities.\n")
	(let* ((pair (assoc city cities))
	(population (cdr pair)))
	(cond ((= 0 population)
	(display "This city has no inhabitants. No bomb has been dropped.\n"))
	((= 0 bombs)
	(display "You do not possess any bombs. No bomb has been dropped.\n"))
	(else
	(begin
	(set! bombs (- bombs 1))
	(if (< population 3)
	(set! cities (cons (cons city 0) cities))
	(set! cities (cons (cons city (- population 3)) cities)))
	(display "You have bombed the city and killed 3 million inhabitants."))))))
	(display "This city exists only in your imagination.\n"))))
	(display "You are not logged in. Please do so.\n")))

Table of Contents

Font styles

Standard markdown

Styling with Tufte-CSS, and HTML/CSS

Abbreviations

Lists

Blockquotes

Epigraphs

Notes

Footnotes

Sidenotes

Marginal notes

Adding images to sidenotes and marginal notes

TODO

Horizontal Rule

Links

Tables

Code

Code Gists

Media

Images

GIFs

Iframe

Mermaid

TODO

Admonitions

Pro tip

Note

Warning

Caution

Important!