Repository files navigation

Docuowl generates a static single-page documentation from Markdown files

As a long-time fan of documentation style made byStripe,and Markdown, I decided to use the former as a base to create a pretty documentationgenerator that outputs something like Stripe's. Stripe also generously allowed meto use their layout, so here's a big thank you to them!♥️

Looking for a demo? A simple demo is available athttps://docuowl.github.io/demo/!

To install Docuowl usingHomebrew, execute the following command:

brew install docuowl/tap/docuowl

Refer to thereleases page to getthe latest version.

Docuowl takes a directory as input. The directory is expected to have onedirectory for each section or group. Each group may have subsections, which bytheir turn must also be placed into directories.EachSection is required to have ancontent.md file, containing theFrontmatter for that section, and an optionalsidenotes.md file, that will berendered to the right of the section. The Frontmatter must contain at least aTitle property, and an optionalID property containing a unique slug for thatsection.EachGroup must contain a singlemeta.md file, containing a Frontmatter likea 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

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

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

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

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

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

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

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

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

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

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

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

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

$ docuowl --input docs --output docs-html --watchDocuowl v0.1Listening on 127.0.0.1:8000

Then open your browser and point to 127.0.0.1:8000. The page will be reloadedeach time a file changes in theinput directory.

In order to locally build, use the providedMakefile. Steps consist of runningcmd/static-generator/main.go, responsible for compiling static files requiredbystatic/static.go, and runninggo build oncmd/docuowl/main.go.

• Full-text Search
• Add tests

This software uses other open-source components. For a full list, see theLICENSE file.

MIT LicenseCopyright © 2021 Victor GamaCopyright © 2021 Real ArtistsPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.