# Readable Markup =Readable Markup= is a small markup language for writing prose in plain text. The idea is that the source should already be pleasant to read before it is rendered. ## Principles - keep the source easy to read - keep the syntax easy to remember - prefer a small number of features - use blank lines to separate thoughts ## Paragraphs Paragraphs are separated by a blank line. ``` Like this. And this is a new paragraph. ``` ## Headings Headings use leading `#` markers. ``` # Heading 1 ## Heading 2 ### Heading 3 ``` ## Lists Unordered lists use leading `-` markers. ``` - list item, continuing the line continuing with a paragraph - another list item - nested bullet ``` Ordered lists use slightly different markers: - decimal: `1.` - alphabetic: `a)` - Roman: `(i)` ``` 1. list item 1 a) nested ordered list (i) ultra-nested ordered list. new paragraph. 2. list item 2 ``` ## Description lists Description lists use `- Term:`. - The term is a single line ending with `:` - The description starts on the next indented line and must not be empty - All items must follow this form, or the list is an ordinary unordered list ``` - Term: The description goes here. - Another term: The first paragraph. The second paragraph. ``` ## Quotes Quotes use a leading `>` marker ``` > Quotes use `>` at the start of a line. > This is the same paragraph. > > This is a new paragraph. ``` > quotes are useful ## Horizontal rules Use at least three hyphens on a line by themselves: `---`. --- ## Links Bare links work naturally in prose, for example http://example.com. The link must be on one line. Trailing punctuation is excluded. ## Media Images, audio, and video must be on their own line: ``` image://mycat.png audio://birds.ogg video://clip.webm ``` Media syntax is not recognised inside ordinary prose. There is currently no caption syntax. ## Inline markup These are the basic inline forms: ``` *bold* /italics/ ~strike~ _underline_ =highlight= `literal span` ``` > *bold* /italics/ ~strike~ _underline_ =highlight= `literal span` Inline markup uses matching opening and closing markers on the same line. A marker must have whitespace/punctuation on the outside, and must not have whitespace on the inside. This means: ``` *Maths:* 3 * 4 + 2 * 4 ``` Here, `*Maths:*` is bold, but the multiplication signs remain plain text. ## Literal blocks Literal blocks use blocks fenced with ```: ``` code goes here still code ``` ## Tables Tables use a `table` fenced block with visually aligned columns. ``` col1 col2 row1 cell row2 cell ``` ```table col1 col2 row1 cell row2 cell ``` The first row is rendered as the header row. ## Things Not Implemented There were a few things that I wanted to implement but I could not find a good way to do so: - labelled links (they are not intuitive) - asides (they break up the prose) - footnotes (they break up the prose as well) ## As HTML A few notes when converting to HTML: - Headings should get `id` attributes and the heading text should link to itself. - List items should not wrap their first paragraph in ``, but later paragraphs should. - Literal blocks render as ``. - The first row of a table renders as header cells.
`, but later paragraphs should. - Literal blocks render as `
`. - The first row of a table renders as header cells.