Docuowl

Docuowl generates a static single-page documentation from Markdown files.

Documentation Organization

Docuowl takes a directory as input. The directory is expected to have one
directory for each section or group. Each group may have subsections, which by
their turn must also be placed into directories.
Each Section is required to have an content.md file, containing the
Frontmatter for that section, and an optional sidenotes.md file, that will be
rendered to the right of the section. The Frontmatter must contain at least a
Title property, and an optional ID property containing a unique slug for that
section.
Each Group must contain a single meta.md file, containing a Frontmatter like
a Section, and an optional content following the frontmatter.

For instance, take the following directory tree as example:

.
├── 1-introduction
│   └── content.md
├── 2-errors
│   ├── content.md
│   └── sidenotes.md
├── 3-authentication
│   ├── content.md
│   └── sidenotes.md
├── 4-authorization
│   ├── 1-login
│   │   ├── content.md
│   │   └── sidenotes.md
│   ├── 2-logout
│   │   ├── content.md
│   │   └── sidenotes.md
│   ├── 4-me
│   │   ├── content.md
│   │   └── sidenotes.md
│   └── meta.md
├── 5-foo
│   ├── 1-listing-foos
│   │   ├── content.md
│   │   └── sidenotes.md
│   ├── 2-merged-foos
│   │   ├── content.md
│   │   └── sidenotes.md
│   └── meta.md
├── 6-bars
│   ├── content.md
│   └── sidenotes.md
├── 7-list-foobars
│   ├── content.md
│   └── sidenotes.md
├── 8-get-foobar
│   ├── content.md
│   └── sidenotes.md
└── 9-foobar-data
    ├── content.md
    └── sidenotes.md

Example of meta.md:

---
Title: Authorization
---

> :warning: **Warning**: All authorization endpoints are currently in maintenance

Markdown Extensions

Docuowl introduces two new blocks to Markdown: Boxes and Attributes List.

Boxes

Boxes can only be used in sidenotes. To create a new box, use the following
format:

#! This is a box
And this is the box's content

After one #!, the box will take any content that follows until one of the
following conditions are met:

  1. A horizontal ruler is found (----)
  2. Another Box begins.

Attributes List

Attributes Lists can only be used in contents. To create a new Attribute List,
use the following format:

#- Attribute List
- Key1 `type`
- Key1 Description

Usage

Docuowl can be invoked in two modes: Compile, and Watch.

Compile

Compilation will output a single index.html file to an specified directory,
taking another directory as input. For instance:

$ docuowl --input docs --output docs-html

Watch

Watch allows one to continuously write documentation and see the preview with
auto-reload. For that, use:

$ docuowl --input docs --output docs-html --watch

Docuowl v0.1
Listening on 127.0.0.1:8000

Then open your browser and point to 127.0.0.1:8000. The page will be reloaded
each time a file changes in the input directory.

TODO

  • [ ] Full-text Search
  • [ ] Improve CSS