We've all been there, just finishing up our awesome project, whether it be a design framework or front-end library, and finding ourselves wondering how to create documentation for the project. We find ourselves envying the beautiful documentation of companies like Stripe, but instead opting out of creating custom documentation due to the amount of work it would require. Cutedoc is a simple command line tool that can be used to solve this problem.

Using technologies that you already know and love, like github flavored markdown, you can create beautiful documentation sites by simply creating markdown files and then stitching them together using a simple manifest file. Cutedoc leverages a high level of customization through the manifest file and allows you to specify the template theme and color scheme, the logo and icon of used, project metadata, and more.

If you already have Go installed, you can easily grab the latest version of Cutedoc by using the go get command in the console. If your GOPATH/bin env variable is set, the cutedoc command will be accessible without having to specify the executable path.

$ go get github.com/NickTheDev/cutedoc/cmd/cutedoc

If you do not have or wish to install Go, you can grab a pre-built binary from Github. However, with this method you will have to optionally add the executable to your env variables yourself.

To create your project, start by creating a .cutedoc.yml file in a directory of your choice, usually the in the root of your project. This is the general structure of a manifest file:

meta:
  title: Cutedoc
  author: NickTheDev
  description: Cutedoc's documentation.
  branding:
    icon: docs/static/img/icon.png
    logo: docs/static/img/logo.png
articles:
  Introduction:
    Intro: docs/sources/about.md

Meta

To describe basic characteristics of the project, you can define a meta section in the manifest file. In this section you may define meta such as the title, author, and description and the project branding.

# Project metadata.
meta:
  # Html header metadata title. Default is blank.
  title: Cutedoc

  # Html header metadata author. Default is blank.
  author: NickTheDev

  # Html header metadata description. Default is blank.
  description: Cool documentation.

  # Project branding.
  branding:
    # Html header favicon, preferably 16 x 16. Default is null.
    icon: path/to/icon.png

    # Logo of the project, preferably 200 x 100. Default is null.
    logo: path/to/logo.png

Build

To configure the build of your project, you can define a build section in the manifest file. In this section you may specify the output directory of the build and whether to minify the production assets or not.

# Build config.
build:
  # Output directory of the documentation. Default is 'docs'.
  dir: docs

  # Whether or not to minify the build assets (css, js). Default is true.
  minify: true

Articles

To link markdown files in your project, you can define an articles section in the manifest file. In this section you may define article groups, and then place the links in them.

# Project articles.
articles:
  # Article group name.
  Introduction:
    # Path to article markdown file, may use github flavored markdown.
    Intro: docs/sources/about.md

Theme

To configure the theme of your project, you can define a theme section in the manifest file. You may specify the template name, the only one currently being the minimal theme (The documentation you are reading right now uses the minimal theme). You can also define the color scheme of the template, namely the primary, secondary, text, nav, and background colors.

# Project theme.
theme:
  # Theme template, currently the only supported template is 'minimal'. Default is 'minimal'.
  template: minimal

  # Template color scheme.
  colors:
    # Primary color used for headers and navigation group text colors. Default is 3e4669.
    primary: 3e4669

    # Secondary color used an accent in the navigation and the body headers. Default is c3c6de.
    secondary: c3c6de

    # Body text color used in the documentation. Default is 3e4669.
    text: 3e4669

    # Navigation background color. Default is fff.
    nav: fff

    # Background color. Default is f6f7fb.
    background: f6f7fb

To build a project, simply execute the cutedoc command in a directory containing a .cutedoc.yml manifest file.

$ cutedoc

Cutedoc will create documentation in the manifest's specified output directory the contents will look like this:

/static
  /img
    icon.png
    logo.png
  /css
    main.css
  /js
    main.js
index.html