|
|
- .\"
- .Dd Dec 22, 2007
- .Dt MKD-EXTENSIONS 7
- .Os MASTODON
- .Sh NAME
- .Nm mkd-extensions
- .Nd Extensions to the Markdown text formatting syntax
- .Sh DESCRIPTION
- This version of markdown has been extended in a few ways by
- extending existing markup, creating new markup from scratch,
- and borrowing markup from other markup languages.
- .Ss Image dimensions
- Markdown embedded images have been extended to allow specifying
- the dimensions of the image by adding a new argument
- .Em =/height/x/width/
- to the link description.
- .Pp
- The new image syntax is
- .nf
- ![alt text](image =/height/x/width/ "title")
- .fi
- .Ss pseudo-protocols
- Five pseudo-protocols have been added to links
- .Bl -tag -width XXXXX
- .It Ar id:
- The
- .Ar "alt text"
- is marked up and written to the output, wrapped with
- .Em "<a id=id>"
- and
- .Em "</a>" .
- .It Ar class:
- The
- .Ar "alt text"
- is marked up and written to the output, wrapped with
- .Em "<span class=class>"
- and
- .Em "</span>" .
- .It Ar raw:
- The
- .Ar title
- is written
- .Em -- with no further processing --
- to the output. The
- .Ar "alt text"
- is discarded.
- .It Ar abbr:
- The
- .Ar "alt text"
- is marked up and written to the output, wrapped with
- .Em "<abbr title=abbr>"
- and
- .Em "</abbr>" .
- .It Ar lang:
- The
- .Ar "alt text"
- s marked up and written to the output, wrapped with
- .Em "<span lang=lang>"
- and
- .Em "</span>" .
- .El
- .Ss Pandoc headers
- The markdown source document can have a 3-line
- .Xr Pandoc
- header in the format of
- .nf
- % title
- % author(s)
- % date
- .fi
- which will be made available to the
- .Fn mkd_doc_title ,
- .Fn mkd_doc_author ,
- and
- .Fn mkd_doc_date
- functions.
- .Ss Definition lists
- A definition list item
- is defined as
- .nf
- =tag=
- description
- .fi
- (that is a
- .Ar = ,
- followed by text, another
- .Ar = ,
- a newline, 4 spaces of intent, and then more text.)
- .Pp
- Alternatively, definition list items are defined as
- .nf
- tag
- : description
- .fi
- (This is the format that
- .Ar "PHP Markdown Extra"
- uses.)
- .Pp
- .Ss embedded stylesheets
- Stylesheets may be defined and modified in a
- .Em <style>
- block. A style block is parsed like any other
- block level html;
- .Em <style>
- starting on column 1, raw html (or, in this case, css) following
- it, and either ending with a
- .Em </style>
- at the end of the line or a
- .Em </style>
- at the beginning of a subsequent line.
- .Pp
- Be warned that style blocks work like footnote links -- no matter
- where you define them they are valid for the entire document.
- .Ss relaxed emphasis
- The rules for emphasis are changed so that a single
- .Ar _
- will
- .Em not
- count as a emphasis character if it's in the middle of a word.
- This is primarily for documenting code, if you don't wish to
- have to backquote all code references.
- .Ss alpha lists
- Alphabetic lists (like regular numeric lists, but with alphabetic
- items) are supported. So:
- .nf
- a. this
- b. is
- c. an alphabetic
- d. list
- .fi
- will produce:
- .nf
- <ol type=a>
- <li>this</li>
- <li>is</li>
- <li>an alphabetic</li>
- <li>list</li>
- </ol>
- .fi
- .Ss tables
- .Ar "PHP Markdown Extra"
- tables are supported; input of the form
- .nf
- header|header
- ------|------
- text | text
- .fi
- will produce:
- .nf
- <table>
- <thead>
- <tr>
- <th>header</th>
- <th>header</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td>text</td>
- <td>text</td>
- </tr>
- </tbody>
- </table>
- .fi
- The dashed line can also contain
- .Em :
- characters for formatting; if a
- .Em :
- is at the start of a column, it tells
- .Nm discount
- to align the cell contents to the left; if it's at the end, it
- aligns right, and if there's one at the start and at the
- end, it centers.
- .Ss strikethrough
- A strikethrough syntax is supported in much the same way that
- .Ar `
- is used to define a section of code. If you enclose text with
- two or more tildes, such as
- .Em ~~erased text~~
- it will be written as
- .Em "<del>erased text</del>" .
- Like code sections, you may use as many
- .Ar ~
- as you want, but there must be as many starting tildes as closing
- tildes.
- .Ss markdown extra-style footnotes
- .Ar "PHP Markdown Extra"
- footnotes are supported. If a footnote link begins with a
- .Ar ^ ,
- the first use of that footnote will generate a link down to the
- bottom of the rendered document, which will contain a numbered footnote
- with a link back to where the footnote was called.
- .Sh AUTHOR
- David Parsons
- .%T http://www.pell.portland.or.us/~orc/
- .Sh SEE ALSO
- .Xr markdown 1 ,
- .Xr markdown 3 ,
- .Xr mkd-callbacks 3 ,
- .Xr mkd-functions 3 ,
- .Xr mkd-line 3 .
- .Pp
- .%T http://daringfireball.net/projects/markdown
- .Pp
- .%T http://michelf.com/projects/php-markdown
|