markdown

markdown is a lightweight markup language ideal for static site generators. this page contains information on how to write markdown files. pub.pl uses a slightly modified version.

filetype

a markdown file is a plain-text file ending with the extension .md. you can create a file like this at the command line with a command like touch file.md or in a text editor like TextEdit or pluma. note that rich text editors like TextEdit must to explicitly told to switch to plain-text mode; the necessary command may be found in the “Format” menu, the save dialog, or elsewhere. consult your editor’s documentation for more information.

syntax

every logical line (that is, sequence of characters terminated by an enter or return) constitutes a separate paragraph.

headers are added to markdown files with the # and ## cues. any line starting with # is a top-level header (like the header above that says “markdown”). a line that starts with ## is a second-level header

formatting

text can be formatted with the \* characters. placing a pair of stars around a sequence of text makes the text italic (\*italic\*). placing a double pair of stars (\*\*) around a phrase makes it bold (\*\*bold\*\*). finally, a triple pair of stars (\*\*\*) makes it bold and italic (\*\*\*bold and italic\*\*\*).

you can also use the \_ character to underline text (\_underline\_), although this should be used sparingly. conventionally, underlines on the internet denote links, and while the default stylesheet makes links and underlined text very distinct, they are probably still best avoided.

code and other literals can be written by surrounding them with the character `, for instance, `src/index.md` (`\`src/index.md\).

lists

markdown can create two types of lists, ordered lists and unordered lists.

ordered lists are created by prefixing lines with a number followed by a .; e.g., 1. line one; 2. line two:

1. line one
2. line two

unordered lists are created by placing an asterisk \* at the start of the line; e.g. \* line one; \* line two:

• line one
• line two

note that the asterisk must be followed by a space to distinguish a list entry from line-initial italics.

links

to add a link to another file or website, surround the linked text with square brackets and place a URL directly next to it in parentheses. for example, the link index is written \[index](/index.html). there cannot be a space between the ] and (.

you can link to other documents in the same site, external sites, sections of the same page, or sections of other pages. sections are denoted with the # character, so a link to convenience replacements can be written as \[convenience replacements](#convenience-replacements). a link from another page to this section could be written \[links](markdown.html#links).

addressing files is fairly complex, and has its own section.

escapes

there's a small problem here - what if you need to include a literal \* or \_ in a file, such as in an equation (12*2) or a function signature (void do\_things\_with\_stuff(struct stuff\* s))? in this case, we use the standard escape character, the backslash \.

by placing a backslash in front of a formatting character (including another backslash), the character loses its special meaning, and becomes just another symbol (as in void do\\\_things\\\_with\\\_stuff(struct stuff\\* s)) above.

horizontal rule

to separate two paragraphs with a line, you can use the sequence -\-\- to generate a horizontal rule:

this is often used to indicate perspective breaks in stories or to separate unnamed sections in essays. note that the -\-\- sequence must occur on its own line with no other content, including spaces.

convenience replacements

the sequence -\- is automatically transformed into an em-dash (--). this may be prevented by writing it as -\\-.

the character x is printed as a multiplication sign (×) when it occurs directly between two digits, as in 12x4 (12\x4); this may be prevented by prefacing the x with a backslash, as in 12\\x4.

the sequence -\:- is printed as a division sign (-:-), as in 100-:-10 (100-\:-10); this may be prevented by prefacing the : with a backslash, as in 100-\\:-10.