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

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


All of the source code and documentation is dedicated to the public domain under CC0: https://creativecommons.org/.publicdomain/zero/1.0/.


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

$ writeup <in >out $ writeup file.wu > out $ writeup file.wu file.html

Here is the builtin help documentation:

usage: writeup [-h] [-deps] [-css CSS [CSS ...]] [-no-css] [-no-js] [-bare] [-section SECTION] [-dbg] [src_path] [dst_path] Converts .wu files to html. positional arguments: src_path Input .wu source path; defaults to <stdin>. dst_path Output path: defaults to <stdout>. optional arguments: -h, --help show this help message and exit -deps Print external file dependencies of the input, one per line. Does not output HTML. -css CSS [CSS ...] paths to CSS. -no-css Omit default CSS. -no-js Omit default Javascript. -bare Omit the top-level HTML document structure. -section SECTION Emit only the specified section. -dbg print debug info.


Writeup documents consist of:

These are translated as follows:

There is also support for inline markup:

Comparison to Markdown

Writeup differs from Github Flavored Markdown (GFD) substantially. Here are some of the more obvious points:

A note about GitHub Readme files

GitHub supports several markup formats for project readmes, via https://github.com/github/markup; Writeup is not yet one of them. However


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

writeup v0

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.


If you start using Writeup seriously please let me know and I will bump the version number to 1.


Writeup HTML contains Javascript that facilitates paging across primary and secondary sections using the left and right arrow keys.

Presentation Mode

Writeup HTML files contain CSS and Javascript for both normal and presentation modes. Press p in the browser to toggle between modes. Presentation mode simply adds styling to the primary and secondary sections to render them at the full window height; in conjunction with the paging mechanism this lets you use Writeup documents as simple slide decks.


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


Sections and text:

# Header 1 line 1 * A * B * B1 * B2 * C ## Header 2 line 2 Line 3


Header 1

line 1

  • A
  • B

    • B1
    • B2
  • C

Header 2

line 2
Line 3


By George King.