QuickDoc Example

This is a sample QuickDoc markup test. The source for this can be found on GitHub. It is a dead-simple and easily parsed wiki-style markup for Common Lisp. In addition to markup, it also supports meta tag information to be embedded in any generated HTML and custom stylesheeting.

Document Header

At the very beginning of the document, if a line begins with a @ then it is considered a meta comment. These are both options indicating how the document should be rendered, and also meta information for the generated HTML.

@Title  : Example QuickDoc
@Author : Me
@Date   : Today

The above will set the <TITLE> of the QuickDoc to "Example QuickDoc" and add <META> tags for "author" and "date" (note how "author" and "date" are downcased, all meta comment keys are case-insensitive and forced lowercase).

The syntax for a meta comment is <name> : <content>. If no : is present separating the name and content, then the entire comment is considered to be the name and the content attribute is left as empty.

The first line in the document that does not begin with an @ begins the actual document body and any other lines beginning with @ from then will be treated as plain text.

If no @title tag is present the document is named "Untitled".

Body Formatting Rules

QuickDoc is like most markdown formats. However, it subscribes to the notion that less is more and allows for much prettier output. It allows for ATX-style headings, paragraphs, blockquotes, links, images, bullet lists, tables, and pre-formatted blocks. And many of these can be embedded recursively.

Headings

Headings are begun with the = characters (followed by a space) at the start of a line and up to three levels are permitted. Any trailing = after the header are optional and will be ignored.

= h1 =
== h2 ==
=== h3 ===
==== h4 ====
===== h5 =====
====== h6 ======

QuickDoc limits the heading depth to six.

Paragraphs

Any line that isn't formatted with a pre-defined style at the start is considered to be a paragraph of formatted text. Empty newlines break paragraphs, but otherwise paragraphs are merged together. Within a paragraph, the following formatting rules apply:

Use **bold** to begin and end bold text.
Use __italic__ to begin and end italic text.
Use ~~strike-through~~ to begin and end ~~strike-through~~ text.
Use ^^ to begin and end ^superscript text.
Use ,, to begin and end _subscript text.
Use [[links]] to create links.
Use [[href | captioned links]] to create captioned links.
Use `pre-formatted text` to start and stop pre-formatted text.

Emphasis can ~~be nested~~, but you can't nest recursively.

Any character can be escaped (to prevent formatting) with the \ character. If the last line of a paragraph is \ then a hard <BR> is inserted.

The White House\
1600 Pennsylvania Avenue NW\
Washington, DC 20500

The White House
1600 Pennsylvania Avenue NW
Washington, DC 20500

Unicode characters (like ✓) can be inserted using \uhhhh, where 'hhhh' is a 4-digit hexadecimal value. The following unicode characters are also specially supported:

(tm) for ™
(R) for ®
(C) for ©
(1/4) for ¼
(1/2) for ½
(3/4) for ¾
(o) for °
(+/-) for ±

Lists

Lists can either be unordered or enumerated. Any line beginning with * followed by a space will create a list item for an unordered list. Any line beginning with # followed by a space will create an ordered list item. Any non-list item or empty line will terminate the list.

* Item A
* Item B

Item A
Item B

# Item 1
# Item 2

Item 1
Item 2

List items can be formatted, with all the rules for paragraphs, and they can be nested by simply adding more sub-items to the same list. Unordered and enumerated lists can also be embedded within each other.

* Item A
* * Item A.a
* * Item A.b
* Item B
* # Item B.1
* # * Item B.1.a
* # * Item B.2.b
* # Item B.2

Item A

Item A.a
Item A.b

Item B

Item B.1

Item B.1.a
Item B.2.b

Item B.2

Blockquotes

Any line beginning with > followed by a space will begin a blockquote. Like list items, blockquotes can make use of all the same formatting rules as paragraphs, and can recursively include themselves and lists.

> Lorem ipsum...

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed doeiusmod tempor incididunt ut labore et dolore magna aliqua. Utenim ad minim veniam, quis nostrud exercitation ullamco laborisnisi ut aliquip ex ea commodo consequat. Duis aute irure dolorin reprehenderit in voluptate velit esse cillum dolore eu fugiatnulla pariatur. Excepteur sint occaecat cupidatat non proident,sunt in culpa qui officia deserunt mollit anim id est laborum.

Notes

You can create an aside note with ? followed by a space and all the text inside will be formatted like a paragraph (it isn't recursive like a blockquote).

? **Notice** Watch this space!
? You never know when something new will appear.

Tables

If a line begins with a single | followed by a space, it is considered to be a CSV table record. The record is parsed according to RFC 4180 and displayed. The very first record in a table is assumed to be the header row.

| Name, Age, Gender, Relation
| "Massung, Jeffrey", 37, M, Father
| "Massung, Isabel", 5, F, Daughter

Name	Age	Gender	Relation
Massung, Jeffrey	37	M	Father
Massung, Isabel	5	F	Daughter

Table data cells are not parsed for markup. Header cells are left as plain text.

Pre-formatted Text

If you want to display entire lines of pre-formatted text, begin the line with : followed by a space. As with all other groups, they will coalesce until reaching an empty line or non pre-formatted line.

CL-USER > (flet ((initial (m)
                   (with-re-match (v m)
                     (format nil "~@(~a~)." (char $1 0)))))
            (replace-re #r/(%a+)%s*/ #'initial "lisp in small pieces" :all t))
"L.I.S.P."

Images

Images are not ever embedded into paragraphs. They are on a line of their own, and centered. Any line that begins with a ! followed by a space will be an image where the rest of the line is the address of the image to display. Using !< or !> will align the image to the left and right of any text following it. You can insert a caption for the image by using a | after the URL for the image. Any text after the | will be used as the caption.

!> http://imgs.xkcd.com/comics/lisp_cycles.png | A funny Lisp comic

While there is no method of specifying the size of the image to display, the CSS for the HTML rendering is allowed to set the max-height of centered images to something reasonable (240px is recommended) and a maximum width for left- and right-justified images.

Videos

Videos can be embedded with ! as well. The URL must be a link to an embedded YouTube or Vimeo video. Captioning and aligning all work the same as images. The QuickDoc parser will simply recognize that the URL is to one of those sites and embed it as such.

! http://player.vimeo.com/video/106786265 | Envoy

Envoy

Horizontal Rules

A horizontal rule can be placed anywhere by beginning a line with ---. Text can optionally be centered immediately above the horizontal rule by putting it after the ---.

--- That's all folks! ---

That's all folks!

If you find QuickDoc useful, please let me know!