πŸ¦‰ Docuowl generates a static single-page documentation from Markdown files

Overview

πŸ¦‰ Docuowl

Docuowl generates a static single-page documentation from Markdown files

Rationale

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

Demo

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

Docuowl Screenshot

Installing

Refer to the releases page to get the latest version.

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.

Building

In order to locally build, use the provided Makefile. Steps consist of running cmd/static-generator/main.go, responsible for compiling static files required by static/static.go, and running go build on cmd/docuowl/main.go.

TODO

  • Full-text Search
  • Add tests

License

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

MIT License

Copyright Β© 2021 Victor Gama
Copyright Β© 2021 Real Artists

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, 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 THE
SOFTWARE.
Comments
  • Request to improve installation instructions

    Request to improve installation instructions

    Hi! Nice-looking project. I'd love to create more readable documentation with docuowl for some of my projects.

    However, I might be daft, but I am not sure on the actual installation process, since this is not covered in any detail.

    I am on macOS 11.2.3 (Macbook Pro M1) and using the Darwin ARM64 variant of docuowl. It can be directly executed (i.e. double-clicking the file) after allowing it in Security (being third party software). Adding it to the path variable in .zshrc (as I am assuming the intended installation would be) does not allow me to use it. Executing it with sh docuowl gives an error about being unable to execute a binary file.

    This is all probably very easy to get working, but I'd be happy for advice and maybe having this updated in the docs for anyone having these "dumb" problems :)

    documentation enhancement 
    opened by mikaelvesavuori 4
  • Suggestion for full-text search (stork)

    Suggestion for full-text search (stork)

    I just recently discovered stork, and I think it could be a good "3rd party" (self-hosted, not cloud!) solution for full-text search without having to reinvent the wheel inside Docuowl.

    As far as I know, stork currently doesn't recursively add files from a directory to its database, but once your Docuowl tree is well established, you could configure stork (or write a script to autogen the config if you have tons of files) and it should work well (although I haven't tested it with Docuowl yet...).

    On the Docuowl side, perhaps there could be an integration with stork so that the search bar uses either the built-in search feature or stork's search.

    Just a thought!

    opened by netstx 4
  • Dark mode switch

    Dark mode switch

    Hi @heyvito, nice project! Is there an easy way to use a light color mode instead of the dark mode? On the Stripe API documentation page there is a dark mode switch, would it be possible to have it on the docuowl generated documentation too?

    opened by filipecalegario 4
  • Images do not resize in a responsive way

    Images do not resize in a responsive way

    Currently, images do not resize in a responsive way on smaller resolutions/mobile. It's a matter of a few lines of CSS, so I thought it wouldn't be too much of a problem to fix it :^)

    Example of what I'm talking about: image

    opened by invakid404 3
  • Make the design responsive

    Make the design responsive

    I often scroll documentation on my phone (as to have a third screen) and currently, the mobile view is… somewhat lacking. I attached a screenshot to highlight what I mean. The main text is all squashed up while the examples take way too much space.

    My suggestion would be to move the example column under their corresponding text to make it easier to read. photo5431762281198366932

    opened by mpldr 2
  • fix(img): add responsiveness with restriction to content size

    fix(img): add responsiveness with restriction to content size

    Description: Add responsiveness to images inside <section> elements, enclosing the <img> into its section size. Possibly fix for #17

    Screenshots: | Mobile | PC | | ------- | -- | | | |

    Videos: https://user-images.githubusercontent.com/28108272/119242138-fe597800-bb31-11eb-9b76-5f785cd9f47e.mp4 https://user-images.githubusercontent.com/28108272/119242142-05808600-bb32-11eb-8147-29fa7a26159d.mp4

    opened by coelhucas 0
  • Add a visible anchor link

    Add a visible anchor link

    Currently it is not possible to get an anchor link from a title. It would be nice to have something like GitHub's, which shows an anchor button when one hovers a title.

    x

    enhancement 
    opened by heyvito 0
  • Fix/search regression

    Fix/search regression

    This updates how anchoring is done, which fixes fts_exec, bringing search back. This also reverts a change in fts_exec introduced by #8, which broke the search feature.

    opened by heyvito 0
  • howto build binary

    howto build binary

    [email protected]:/mnt/e/code/docuowl$ go mod vendor
    github.com/heyvito/docuowl/parts imports
            embed: package embed is not in GOROOT (/usr/local/go/src/embed)
    
    opened by xiaods 0
  • feat: Light theme

    feat: Light theme

    Bumps to v0.2

    Closes #4

    Features

    • [x] Add new light color scheme
    • [x] Improve TOC open/close indicator
    • [x] Add light scheme chooser
    • [x] Upgrade CSSs to compiled SCSS
    enhancement 
    opened by heyvito 0
  • Looking for examples

    Looking for examples

    Hi, For me I think this project is amazing! But its a little vague for me how I should make all the folders and how the md files should be written.

    Can anyone send me an example? or all folders that make up the demo provided by the author?

    Thank you

    opened by SonNNguyen 1
  • Brew installation broken

    Brew installation broken

    Hi, it seems that the brew formula is outdated:

    Error: Invalid formula: /usr/local/Homebrew/Library/Taps/docuowl/homebrew-tap/Formula/docuowl.rb
    docuowl: Calling bottle :unneeded is disabled! There is no replacement.
    Please report this issue to the docuowl/tap tap (not Homebrew/brew or Homebrew/core):
      /usr/local/Homebrew/Library/Taps/docuowl/homebrew-tap/Formula/docuowl.rb:10
    
    Error: Cannot tap docuowl/tap: invalid syntax in tap!
    
    opened by eloo 1
  • Code formatting doesn't work for yaml

    Code formatting doesn't work for yaml

    When using codeblocks for yaml somehow all lines get squished into one, making it unusable. It works if you don't specify a language but that removes the nice syntax highlighting. I haven't encountered this with other languages.

    Example:

    image

    Sidenotes content:

      #! Usage
    
      ```yml
      actions:
        - id: something
          uses: something/[email protected]
          something: else
    ```
    

    This is not just the case with sidenotes, also if you place it in the content.md file.

    Any idea why this is just happening with yaml?

    opened by TimoGlastra 0
  • could not be installed on mac with m1 chip

    could not be installed on mac with m1 chip

    Warning: Calling bottle :unneeded is deprecated! There is no replacement.
    **Please report this issue to the docuowl/tap tap (not Homebrew/brew or Homebrew/core):
      /opt/homebrew/Library/Taps/docuowl/homebrew-tap/Formula/docuowl.rb:10**
    
    Error: Invalid formula: /opt/homebrew/Library/Taps/docuowl/homebrew-tap/Formula/docuowl.rb
    formulae require at least a URL
    
    Error: Cannot tap docuowl/tap: invalid syntax in tap!
    

    I can not install it, I think it may be an issue with compatibility with the mac m1 apple chip or Monetery OS

    And thanks.

    opened by mohammad-n-11178 1
  • How to add my custom CSS?

    How to add my custom CSS?

    Hi, I found this project today and already becoming a big fan, with its simplicity and Stripe-ish looking UI!

    So my question, how could I override the existing CSS to tweak some styles?

    opened by tomodian 0
Releases(v0.2.4)
Owner
Docuowl
Quick & Pretty documentations
Docuowl
Default godoc generator - make your first steps towards better code documentation

godoc-generate Overview godoc-generate is a simple command line tool that generates default godoc comments on all exported types, functions, consts an

Dimitar Petrov 19 Sep 14, 2022
A vitamin C rich, book, pdf & documentation brewing library for e-readers/e-ink readers

go-Cbook A vitamin C rich, book, pdf & documentation brewing library for e-readers/e-ink readers. Now take priviliges of (eye-safe) e-readers to read

VOrishirne 6 Dec 28, 2021
Manage internal technical documentation that is enriched with live data accreted from your environment.

Manage internal technical documentation that is enriched with live data accreted from your environment.

Daniel Tedman 0 Dec 11, 2021
TLDR Page Creator is a program designed to help users make TLDR pages

TLDR Page Creator is a program designed to help users make TLDR pages, while avoiding syntax errors from TLDR-style markdown.

null 8 Apr 8, 2022
Script to generate a web page for your Aliucord plugins repo.

Aliucord-Store Script used to generate a website front-end for your plugins. Usage: go run cmds/store/main.go -dir string Your repository's

Zoey 3 Jan 31, 2022
RTS: request to struct. Generates Go structs from JSON server responses.

RTS: Request to Struct Generate Go structs definitions from JSON server responses. RTS defines type names using the specified lines in the route file

Paolo Galeone 235 Sep 27, 2022
Generates Golang code with enums from TOML specification

enum-generator This enum-generator is intended to generate golang source code for string-based enum types and enum types with associated data from des

WiMark Systems 0 Dec 29, 2021
Mongo-backed Static Site Generator for fun

MDBSSG MongoBacked SSG next: set up casbin middleware after: factor out common or large patterns in existing handlers after: refactor UserModel.CheckS

Tyler Darnell 1 Feb 27, 2022
Giraffe - An opinionated static site generator written in Go

Giraffe: An opinionated static site generator I want to start 2022 by writing a

Thien Nguyen 4 Sep 29, 2022
A static blog generator for telling tall tales

Gleeman Gleeman is a toy static blog generator that aims to be a simple way to tell tales. The term "gleeman" is taken from Robert Jordan's epic fanta

Brian Seitel 0 Jan 14, 2022
The noblest static site generator πŸ₯¬

I love Darkness ?? Also posted here This is no life It doesn't feel right anymore. I feel that every time I write something for my website, I have to

Sandy 18 Sep 30, 2022
Merge FiveM cars into a single resource

FiveM Cars Merger Merge FiveM cars into a single resource Usage Download the binary from here or build it Save it in a directory Create a new folder i

iLLenium Studios 1 May 3, 2022
An experimental distribution of Temporal that runs as a single process

Temporalite ⚠️ This project is experimental and not suitable for production use. ⚠️ Temporalite is a distribution of Temporal that runs as a single pr

Datadog, Inc. 331 Sep 20, 2022
An easy-to-use Map Reduce Go parallel-computing framework inspired by 2021 6.824 lab1. It supports multiple workers on a single machine right now.

MapReduce This is an easy-to-use Map Reduce Go framework inspired by 2021 6.824 lab1. Feature Multiple workers on single machine right now. Easy to pa

Bo-Wei Chen 193 Sep 17, 2022
Converts grouped transactions in a ZKB transaction CSV (incl. details) to single transactions

ZKB Converter Converts grouped transactions in a ZKB transaction CSV (incl. deta

Tobias Nehrlich 0 Dec 26, 2021
Easily create & extract archives, and compress & decompress files of various formats

archiver Introducing Archiver 3.1 - a cross-platform, multi-format archive utility and Go library. A powerful and flexible library meets an elegant CL

Matt Holt 3.7k Sep 21, 2022
The forgotten go tool that executes and caches binaries included in go.mod files.

The forgotten go tool that executes and caches binaries included in go.mod files. This makes it easy to version cli tools in your projects such as gol

Dustin Blackman 24 Sep 27, 2022
elPrep: a high-performance tool for analyzing sequence alignment/map files in sequencing pipelines.

Overview elPrep is a high-performance tool for analyzing .sam/.bam files (up to and including variant calling) in sequencing pipelines. The key advant

null 260 Sep 8, 2022
View the script files in the original Resident Evil 2 / Biohazard 2 as pseudocode

Resident Evil 2 Script Viewer About You can view the script files in the original Resident Evil 2 / Biohazard 2 as pseudocode next to the original byt

Samuel Yuan 14 Jan 20, 2022