# 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/](http://localhost:8182/documentation/debug/): the current working doc version
- [localhost:8182/release/debug/main.css](http://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](https://pages.github.com/). 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](https://github.com/ftlabs/fastclick) by FTLabs
- [Parallaxify](https://moox.io/parallaxify/) by MoOx