Writeup

Writeup is a text markup format that translates to HTML5. It is similar to Markdown in spirit, but not equivalent. Some differences:

• Writeup documents can embed the contents of other files, with sensible default styling.
• Writeup has unambiguous character escape syntaxes.
• The output HTML document is organized into hierarchical sections.
• An optional lightweight presentation mode (implemented with embedded JavaScript) makes Writeup useful for simple technical slide decks.
• A required syntax version at the top of every Writeup document allows the format to evolve while preserving the ability to render older documents exactly as originally intended.
• Special handling of copyright/license header lines.
• Integration with Muck, a build tool for data projects.

The project is hosted at https://github.com/gwk/writeup, with documentation at https://gwk.github.io/writeup.

Usage

Writeup can take 0, 1 or 2 arguments, defaulting to stdout and stdin as follows:

Here is the builtin help documentation:

Format

Writeup documents consist of:

• An initial required version line: writeup v0.

• Optional consecutive copyright/license lines at the beginning of the document, followed by a blank line. Recognized prefixes are:

  • ©
  • Copyright
  • Dedicated to the public domain
• Blank lines, containing only whitespace characters.
• Header lines, beginning with one or more # (hash) characters.
• List lines, beginning with zero or more pairs of spaces, followed by a * (dash) character.
• Code lines, prefixed with a | (pipe / vertical-bar) character.
• Quote lines, prefixed with a > (greater-than) character.
• Text lines, which are any lines that don't match any of the above criteria.

These are translated as follows:

• Line breaks are inserted between text lines.
• Groups of consecutive lines are grouped into paragraphs.
• A blank separates text lines into paragraphs.

• A header line denotes a section with a header whose numerical level is indicated by the number of hash symbols.

  • Sections are translated into nested <section> elements, containing the appropriate <h1> through <h6> header elements.
  • Sections can be nested arbitrarily deeply, but beyond 6 levels will all produce h6 tags, the maximum supported by HTML5.

There is also support for inline markup:

• Inline code is quoted with backticks like so: `…`

  • Literal backticks and backslashes within an inline code span are written by escaping with a backslash: \` and \\.

• A generic span syntax also exists: <tag: …>, where the tag can be one of the following:

  • b: bold text: <b: bold text> → bold text.
  • embed: embed content from an external file.

  • link, http, https, mailto all specify a link:

    • If the link is followed by a space and additional words of text, then the text becomes the visible link text.
    • Example: <https://github.com/gwk/writeup> → https://github.com/gwk/writeup
    • Example: <https://github.com/gwk/writeup writeup> → writeup
    • if the tag is link, then the link is a relative link and is treated by Muck as a project dependency.
  • span: a generic HTML span with arbitrary options (syntax is a work in progress).

• More inline markup features need to be added!

  • italics, strikethrough, edit additions and deletions, etc.

Versioning

All Writeup documents require a version line at the beginning of the document, like this:

Writeup is currently experimental, and the only version number supported is 0. Once the format is reasonably stable, then it will be promoted to v1. From then on, if the format changes, implementations should either recognize and respect or else reject older documents.

Text snippets submitted to a program using Writeup as a library can omit the version number; it is then the responsibility of the program to track the format version as necessary.

Implementation

Writeup is currently implemented as a Python 3.6 script, depending only on the standard library.

Examples

Sections and text:

Becomes:

Header 1

line 1

• A

• B

  • B1
  • B2
• C

Header 2

line 2
Line 3

Credits

By George King.