Markdown Guidelines

conversion

Use pandoc with the option set to markdown—this is the only one that preserves emacs style tables.

Metadata

Use at the start of the document

---
title: Data Science
lang: english
author: Zach Hadgraft
date: 2023-04-24
---

Or, beneath a header:

 # my-header

 ---
 tags: I/O, concurrency
 ---

escape characters

Escape these characters with a backslash (as shown here in original):

inline display

• Use **strong** for strong
• Use *emphasis* for emphasis
• Use `code` for code (inline code)
• Use $x + y = 1$ for $x + y = 1$ (inline math)

Newlines

Add 2 spaces to the end of a line to create a <br/>.

HTML entities

Use them as you would normally.

kbd

C-x C-k K

Use CTRL+y for keystrokes.

Use <kbd>CTRL</kbd>+<kbd>y</kbd> for keystrokes.

abbr

C-x C-k B

For abbreviations use:

Estimated time of arrival is used in travel contexts.

ETA stands for estimated time of arrival.

Example: I’ll call you when my flight lands and give you an ETA.

Estimated time of arrival is used in travel contexts.

**<abbr title="estimated time of arrival">ETA</abbr>** stands for estimated time of arrival.

Example: *I'll call you when my flight lands and give you an ETA.*

• use the title or abbreviation in the paragraphs that precede and follow the tag

dfn

C-x C-k d

For definitions use:

An abacus is an oblong frame with rows of wires or grooves along which beads are slid, used for calculating.

The abacus was used from ancient times in the ancient Near East, Europe, China, and Russia, until the adoption of the Arabic numeral system.

An **<dfn>abacus</dfn>** an oblong frame with rows of wires or grooves along which beads are slid, used for calculating.

• use the word in the paragraphs that precede and follow the tag

links

this is a link

results in

<a href="www.somesite.com" title="Somesite!">this is a link</a>

a variation is this is a link

http://example.com

results in

<a href="http://example.com/">http://example.com</a>

a description is a reference to:

Heading anchors:

If you have the heading ‘My Special Heading’, create a link to it with:

[My Special Heading](#my-special-heading)

bookmarks

(local-set-key (kbd “C-x C-k J”) ‘markdown-insert-bookmark) (defun markdown-insert-bookmark () “Prompt user with input for a bookmark element.” (interactive) ;; search for uris (let* ((id-regex “id="\(figure-[0-9]+\)"”) (ids (save-excursion (goto-char (point-min)) (let (id-list) (while (re-search-forward id-regex nil t) (add-to-list ‘id-list (match-string 1))) id-list))) (id (completing-read “Choose ID: " ids))

     ;; new regex from string and regex
     (let ((my-var "bar"))

(setq my-regex (format “foo\(%s\)baz” my-var)) my-regex)

     ;; search for regex and retain only the group
     (let ((my-regex "foo\\(bar\\)baz")
  (my-match))

(save-excursion (goto-char (point-min)) ;; Start at the beginning of the buffer (when (re-search-forward my-regex nil t) (setq my-match (match-string 1)))) my-match)

;; Insert the figure element
(insert (format "<figure id=\"%s\" class=\"markdown-figure\">\n\n\n\n</figure>\n\n" id))
;; Move the cursor to the second line between the opening and closing tags
(forward-line -2)
;; Insert the description with the pretty-printed ID
(insert (format "<figcaption>%s%s</figcaption>\n" pretty-id description))
;; Move the cursor to the second of the three lines
(forward-line -3)
(insert (format "![%s%s](%s)" pretty-id description uri)))

;; After exiting the recursive edit, unrecognize the table (forward-line 5))

With header “## Simple Noninferential Passages ##” a simple bookmark is

[Simple noninferential passages]

With header “## 12345 10.03 This is a CooL HEADER/title 1234” the appropriate way to bookmark is

12345 10.03 This is a CooL-HEADER/title 1234

Notice that leading numerals are removed, spaces are converted to ‘-’, most special characters (’.’, ‘/’, ‘(’, ‘)’, etc.) are removed, and letters are converted to lower case.

Using headers that match the pattern [A-Za-z ] may be the best policy for future portability.

A bookmark on another page in the same folder

images

C-c TAB

Pandoc converts these to figures:

![This link is to a nonexistent image](/path/to/img.jpg)

![This link is to a nonexistent image](/path/to/img.jpg "Optional Title")

But, pandoc will leave these alone:

![This link is to a nonexistent image]
(/path/to/img.jpg)\

Creative Works

C-x C-k C

Awesome Book Title

<cite>Awesome Book Title</cite>

Block Display

hr

Use dashes (-) to create a horizontal rule

---

Tables

limit table size to 80 characters

Use C-x C-k T.

<figure id="table-001" class="markdown-table">

+----------+----------+
|Socks     |Hats      |
+----------+----------+
|1         |2         |
+----------+----------+

Table: Table-001. This is a table!

</figure>

Simple Table

a  b  c
----
1  2  3

Variation 1

Table: My Table

|x|y|
|-|-|
|1|0|

Table: My Table

Github-flavored markdown

colons determine alignment of columns underscore determines header outer pipes are optional pipes don’t need to be vertically; “cells” can be of unequal width

Table: Table caption

| Left-aligned | Centered | Right-aligned |
|--------------|:--------:|--------------:|
| 1            |2         |3              |

Table: Table caption

Emacs style tables

+———-+———-+————-+ | Heading1 | Heading2 | Heading3 | +———-+———-+————-+ | … |some text | some really | | | | long text | | | | | | | | | +———-+———-+————-+ |something | 12321 | 0 | +———-+———-+————-+

+----------+----------+-------------+
| Heading1 | Heading2 |  Heading3   |
+----------+----------+-------------+
|   ...    |some text | some really |
|          |          |  long text  |
|          |          |             |
|          |          |             |
+----------+----------+-------------+
|something |  12321   |      0      |
+----------+----------+-------------+

*These tables are only converted to HTML tables by pandoc with the ‘markdown’ option, and parsing is strict so no split or spanned cells

Lists

Sentence 1. And sentence 2 will both be on the same line (newline is removed)

This is a paragraph that will stand alone.

1. Numbered lists
2. cannot have
3. Non-numbered lines between

Indented lists are supported, but indent by 4 spaces or single tab

Figure

Usually images…

C-x C-k F

<figure id="figure-001" class="markdown-figure">

![Figure-001. My figure](./img/figure.png)

<figcaption>Figure-001. My figure</figcaption>
</figure>

codeblock

C-x C-k c

1 + 1

<figure id="code-001" class="markdown-code-figure">

``` python
1 + 1
```

<figcaption>Code-001. My python code</figcaption>
</figure>

Example Block

C-x C-k h

<div class="markdown-div-example" id="example-001">
<div class="html-div-example-title">Example-001. My Example</div>
</div>
<!-end example -->

Algorithm Block

C-x C-k a

<figure id="algorithm-001" class="markdown-algorithm-figure">

Algorithm

<figcaption>Algorithm-001. Algorithm does things</figcaption>
</figure>

Equation Block

C-x C-k E

<figure id="equation-001" class="markdown-equation-figure">

$$
\begin{gather}
1 + 1 = 2
\end{gather}
$$

<figcaption>Equation-001. Easy equation</figcaption>
</figure>

Theorem Block

C-x C-k u

<figure id="theorem-001" class="markdown-theorem-figure">

A theorem

<figcaption>Theorem-001. My Theorem</figcaption>
</figure>

Proof

C-x C-k w

<figure id="proof-001" class="markdown-proof-figure">

My proof

<figcaption>Proof-001. My proof</figcaption>
</figure>

asides

articles

Block Quoting

This start of block quote more blockquote

LaTeX

infotable

deprecated

<article class="infotable">
<header>This is a table</header>

+----------+----------+-------------+
| Heading1 | Heading2 |  Heading3   |
+----------+----------+-------------+
|   ...    |some text | some really |
|          |          |  long text  |
|          |          |             |
|          |          |             |
+----------+----------+-------------+
|something |  12321   |      0      |
+----------+----------+-------------+

</article>