# Documentation

In general each package should have information for installment and general
usage in a README.md file.

Also process documentation and user documentation, should also be commited in
packages in markdown files.

## Working with documentation

Markdown Resource: https://www.markdownguide.org/

### Documentation generation

One can generate documentation by running the `npm run docs` command. It will
aggregate documentation from all packages and spin up a web interface to the
docs at [http://localhost:3000/#/](http://localhost:3000/#/)

We are using [docsify](https://github.com/docsifyjs/docsify/) to generate a web
interface, and custom tooling to compile the markdown files.

### How to document

If there is documentation that is specific to a package, then it should be
include in the package as part of the readme for that package, or as seperate
markdown files. Each package can have a `{namespace}.docs.json` file, that
describes the structure and location of files. (The `{namespace}` is a unique
key which identifies the domain of your documentation. All BodilessJS packages
have a `bodiless.docs.json` file. We'll talk about namespaces in greater detail
below). For example if your package added a component it might have a
`bodiless.docs.json`:

``` json
{
  "Component": {
    "FlashyComponent.md": "./README.md",
    "FlashyComponentScreenShot.png": "./FlashyComponentScreenShot.png"
  }
}
```

If your Package has lots of different files one can put them in a directory with
the desired structure and then just reference the directory as such

``` json
{
  "_dir": "./doc",
}
```

#### If you are using files in the package.json

If you are using the key files in the package.json you need to make sure you add
your docs.json file and any dir you are using to the package.json, such as:

``` json
{
...
  "files" {
    ...
    "/doc",
    "/{namespace}.docs.json"
  }
...
}
```

This ensure that they are part of the package on release.

### Navbar and Sidebar

The Navbar and Sidebar will be autogenerated based on the structure presented.
The titles foe each item will be the keys in `{namespace}.docs.json` (or the
directory/file names if using the `_dir` key). These titles will be made a
little more friendly by
- stripping the `.md` suffix.
- convering PascalCase or snake_case to multiple words, eg:
  - "AboutUs.md" -> "About Us"
  - "npm_commands.md" -> "npm commands"

### Controlling the structure

Because documentation is assembled from different packages, the final order of
items can be hard to predict. In order to control structure more precisely, you
can create a `bodiless.docs.toc.js` file (this should reside at the to level of
your project). This module should contain a single default export: a function
which returns a javascript object defining the ordering of your documentation.

The top level keys of this object should be *namespaces*, and will define the
top level sections of your documentation. For example, if your site level
documentation was namespaced as 'mysite' (via `mysite.docs.json` files in your
site-level packages), you could create two sections in your
`bodiless.docs.toc.js` by returning:

```js
{
  mysite: {},
  bodiless: {}
}
```

Note that the first section will be "hoisted" to the top of your documentation
tree, so this would result in having a "Bodiless" section at the same level as
any sub-sections of your site-level documentation.  Note also that if you don't
care about dividing your docs by namespace, you can include a single top-level
blank key, and all documentation will be included at the top level.

The values of the top level keys are themselves objects whose structure is
similar to that of the `{namespace}.docs.json` file described above, except that
the values of each key should be blank. For example:

```js
{
  bodiless: {
	  About: {
	  	'GettingStarted.md': '',
	  },
	  Components: {
	  Design: {},
	  Development: {},
	  Tools: {}
  }
}
```

This will ensure that the order of the top-level categories is fixed, and that
the first item in the "About" category is "GettingStarted.md". The contents of
each category, as well as the actual documentation to insert at
"GettingStarted.md", will be determined by the individual packages supplying
documentation. Thus, you can specify an order for the things you care about, and
let the documentation builder fill in the remaining documentation.

Note that the default ordering is supplied by a `defaultToc` function exported
by the `@bodiless/documentation` package. You can import this into your
site-level `bodiless.docs.toc.js` and modify the object at will--making it easy
to extend existing structure.

### Theme & Markdown

BodilessJS utilizes https://github.com/jhildenbiddle/docsify-themeable for its
theming and markdown typography.

The sidebar uses https://github.com/iPeng6/docsify-sidebar-collapse to expand
funtionality of the sidebar to meet requirements. 

It also adds Tabs from https://jhildenbiddle.github.io/docsify-tabs/#/ to allow
more content formatting.

<!-- tabs:start -->

#### ** English **

Hello!

#### ** French **

Bonjour!

#### ** Italian **

Ciao!

<!-- tabs:end -->