πŸ¦‰ A documentation generator

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/!

image

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

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
Go TΓΌrkiye Event Template Generator

Go Türkiye Cover Generator Etkinliklerde değişen tek şey konuşmacıların konusu, ismi, nerede çalıştıklarıyla beraber etkinliğin zamanı. Her etkinlikte

Go TΓΌrkiye 25 Dec 5, 2022
πŸ¦‰ A documentation generator

?? Docuowl Docuowl generates a static single-page documentation from Markdown files Rationale As a long-time fan of documentation style made by Stripe

Docuowl 1.2k Dec 28, 2022
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
Automatically generate RESTful API documentation with Swagger 2.0 for Go.

Automatically generate RESTful API documentation with Swagger 2.0 for Go.

Swaggo 7.5k Jan 9, 2023
πŸ¦‰ Docuowl generates a static single-page documentation from Markdown files

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

Docuowl 1.2k Jan 2, 2023
Automated configuration documentation library for Go Projects.

Cato Cato is an automated documentation generation library for Go Projects. Through the use of custom tags for struct fields, Cato can extract informa

CS3 Organization 6 Aug 28, 2020
Utilities to generate (reference) documentation for the docker CLI

About This is a library containing utilities to generate (reference) documentation for the docker CLI on docs.docker.com. Disclaimer This library is i

Docker 16 Dec 28, 2022
Flugel Test Documentation for steps to run and test the automatio

Flugel Test Documentation Documentation for steps to run and test the automation #Test-01 1 - Local Test Using Terratest (End To End) 1- By runing " t

Suc0_Unix 0 Nov 13, 2022
CLI client for docat, Manage your docat documentation with ease.

docatl, the docat cli Manage your docat documentation with ease. Getting Started Download the latest Release binary for your platform and start pushin

null 12 Nov 10, 2022
Vela plugin designed for generating a static documentation website with Hugo.

Vela plugin designed for generating a static documentation website with Hugo.

Vela 0 Jul 22, 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 Jan 3, 2023
Documentation side of the spaghetti cutter.

spaghetti-analyzer - Win The Fight Against Spaghetti Code Overview spaghetti-analyzer is a command line tool for CI/CD pipelines (and dev machines) th

FlowDev 3 Dec 7, 2022
atwhy is a tool to describe your decisions inside the code where they are actually made and still get a readable documentation.

atwhy What is atwhy atwhy can be used to generate a documentation out of comments in the code. That way you can for example describe all available opt

Tiffinger & Thiel GmbH 4 Oct 30, 2022
Golang library for converting Markdown to HTML. Good documentation is included.

md2html is a golang library for converting Markdown to HTML. Install go get github.com/wallblog/md2html Example package main import( "github.com/wa

null 0 Jan 11, 2022
Op - A small tool that will allow you to open language or framework documentation in your browser from your terminal

op "op" is a small tool that will allow you to open language or framework docume

Damien Sedgwick 3 Aug 25, 2022
Rendering godocs for Backstage TechDocs documentation

greenroom What is this all about now? Rendering godocs for Backstage TechDocs documentation. greenroom renders Godoc comments into documentation that

Casey Marshall 2 Oct 31, 2022
🧬 fiber middleware to automatically generate RESTful API documentation with Swagger

Swagger fiber middleware to automatically generate RESTful API documentation with Swagger Usage Add comments to your API source code, See Declarative

Fiber 126 Jan 1, 2023
DND-magic-item-Generator - D&D magic item generator like in Diablo

DND-magic-item-Generator D&D magic item generator like in Diablo Legendary items

Hex Kot 0 Mar 28, 2022
A fast data generator that's multi-table aware and supports multi-row DML.

If you need to generate a lot of random data for your database tables but don't want to spend hours configuring a custom tool for the job, then datage

Coding Concepts 53 Dec 26, 2022