Docui

An opiniated frontend documentation builder cli tool.

Install

npm install -g docui

You'll probably need sudo

Usage - How to...

... start a new project

To start a new project, create an empty folder and run the scaffolder command

mkdir my-project
cd my-project
docui --init

It will copy an empty skeleton and make it easy to start. See below to understand what is created.

If you want to git you project, run git init, add and commit everything before starting coding.

... work and developp

In your project folder, run docui --watch. It will build the documentation, watch your source folders and update on any change. Start editing the less, html, markdown files located in the src folder.

A small web server will start on port 8182. You can provide a different port with docui --watch 8888 for example.

Once the server is started, you can reach:

• localhost:8182/documentation/debug/: the current working doc version
• localhost:8182/release/debug/main.css: the current working compiled css version

Any other previous published version are available on localhost:8182/documentation/1.0.0/ and localhost:8182/release/1.0.0/ (1.0.0 is the version number).

... release a version

Once you're happy with your documentation version, run docui --release major|minor\patch. It will build the new version, commit it if your are in a git repo, and increase the package version.

You're now free to push on your shared repository.

... publish on Github pages

You can easily publish the latest versions on Github Pages. Run docui --publish: your dist folder (previous version) will be push on your gh-pages branch. So, you'll get your documentation alive on https://YOURNAME.github.io/YOUR-REPO/documentation/1.0.0/ (1.0.0 and every other versions you have previously publish).

The older documentation are not modify, so it brings you a good history versioning.

Opiniated code

In you project, you'll get the folders:

• dist
  • documentation build documentation versions
    • debug for development
    • v1.0.0
    • v1.1.0
    • ...
  • releases build releases of your css
    • debug
    • v1.0.0
    • v1.1.0
    • ...
• src
  • statics any markdown file will be a section of the doc
    • content-section.md
    • another-content-section.md
  • style
    • main.less main less file where you include your code and import the components
    • components one component per folder
      • one-component
        • one-component.md optionnal documentation
        • one-component.less the less file of the component
        • one-component.html the html preview of your component
      • another-component
        • another-component.md
        • another-component.less
        • another-component.html
      • ...
• docui.json your configuration file

Documentation build:

Template

The documentation is a one-page template. You can edit design options and content in the docui.json file (color, cover, main texts).

The main menu is built over html dom (h1/h2/h3) and not customizable.

Statics

Statics markdown pages are converted into html sections. The section title are build from the markdown filename, after stripping non alnum chars and any prefix matching ^\d*- . Thus, you can order your section by naming them with prefix:

• 01-introduction.md => Introduction
• 02-core-features.md -> Core features
• ...

Components

One component = one folder.

• my-component-1
  • my-component-1.md
  • my-component-1.html
  • my-component-1.less

Each component has it own folder, and at least a html file with its preview.

You can add a markdown file to provide more information or other usecase sample.

Other files are not manged by the documentation but you can add what you want.

Markdown content

Markdown-to-html converter follows standard rule. A little improvement for the documentation is done regarding blockcode.

Any blockcode will be converted and render:

• an exact html render (insert html code inline to render the look and feel of the component)
• the code with any inline style removed

Thus, you can put inline style for the documentation that will be rendered as demo, but not shared to the user in the documentation.

Thanks

The current design is powered by

• fastclick by FTLabs
• Parallaxify by MoOx