new.html.md.erb

---
parent: contribute
title: add documentation
---

# Add Documentation <%= edit_link %>

Follow this guide to add a new documentation.

<%= partial 'partials/toc' %>

## Introduction

We'll use the *Analytics* project as an example to guide you how to add a new
documentation section.

## Documentation Directory

The first step you have to do is create the directory that the documentation will
live in and be served from.

The documentation directory name should be comprehensive, representative and
future proof. Keep in mind that it will be part of the URL path to access the
documentation.

##### Guidelines
{:.collapsible .collapsed data-toggle="collapse" data-target="#documentation-directory-guidelines" /}

<div id="documentation-directory-guidelines" class="collapse" markdown="1">
Avoid flavored names
: Do not use flavored names (i.e. *alve*, *scrooge*, *skroutz*, etc.) for the
  documentation directory, even if your project is only available for a single
  flavor. It will make things a lot easier to maintain if something changes in
  the future.

Group when appropriate
: If your project consists of sub-projects with separate documentations then you
  should try to group them under a common directory.

Some bad documentation directory names are:

~~~ ruby
- cost-per-action   # Consider `cpa` or `cost_per_action`.
- skroutzeasy       # Avoid flavored names. Consider `easy`.
- api_v3            # Consider grouping, `api/v3`.
- elasticsearch-skroutz-greekstemmer    # Too long and flavored. Consider `elasticsearch/stemmer`.
~~~
</div>

##### Example

For the *Analytics* project, a sane choice for the directory name would be
`analytics`. The documentation will live in:

~~~ css
source/
+-- localizable/
    +-- analytics/
~~~

and it will be accessible at:

~~~ css
https://<%= settings.developer_domain %>/analytics/
~~~

## Index page

Each documentation directory **should** serve an index page.

##### Example

For the *Analytics* project we create the `index.html.md.erb` inside `analytics/`
directory.

~~~ css
source/
+-- localizable/
    +-- analytics/
        +-- index.html.md.erb
~~~

## Other pages

To add a documentation page just create a new file `<name>.html.md.erb` inside
your documentation directory.

##### Example

For example, we need the documentation of the *Analytics Settings API* to be a
single page within the *Analytics* documentation. To achieve this, we create the
`settings.html.md.erb` inside the `analytics/` documentation directory:

~~~ css
source/
+-- localizable/
    +-- analytics/
        +-- index.html.md.erb
        +-- settings.html.md.erb
~~~

that will be accessible at:

~~~ css
https://<%= settings.developer_domain %>/analytics/settings/
~~~

## Sidebar Entry

The `sidebar` is auto-generated based on syntax and naming conventions. To have
the documentation appear in the sidebar:

1. Update `data/docs.yml` with a new entry of your documentation pages
2. Update `locales/` with the missing translations for all flavors

### Update `data/docs.yml`

Add a new entry for your documentation and define which pages should be visible
at the sidebar.

The `data/docs.yml` file holds the documentation structure. Each root element
defines a different documentation.

##### Schema
{:.collapsible .collapsed data-toggle="collapse" data-target="#data-docs-schema" /}

<div id="data-docs-schema" class="collapse" markdown="1">
The schema of a `data/docs.yml` root element is the following:

~~~ yaml
mydoc:
  base: '/mydoc/'
  featured: true
  icon: 'fa-bug'
  pages:
    - { title: 'overview', url: '/mydoc/' }
    - { title: 'doc_page_name' }
~~~

> ##### Note
> Make sure to update locale files with the missing translations.

##### Attributes

Name          | Type    | Required  | Description
--------------| --------| ----------| ------------
`base`        | String  | Yes       | The path to the documentation directory, e.g. `'analytics/'`.
`deprecated`  | Boolean | No        | Set to `true` to label a documentation as *deprecated*.
`featured`    | Boolean | No        | Set to `true` to make the documentation featured in the home page.
`flavors`     | Array   | No        | Define which flavors the documentation will be available in.
`icon`        | String  | No        | A [FontAwesome](http://fortawesome.github.io/Font-Awesome/icons/) icon to accompany the documentation. This is required in case of a featured documentation.
`pages`       | Array   | No        | Define the pages to show in the documentation.

</div>

##### Guidelines
{:.collapsible .collapsed data-toggle="collapse" data-target="#data-docs-guidelines" /}

<div id="data-docs-guidelines" class="collapse" markdown="1">
Root keys are unique
: Obviously you should not use the same root key for different documents.
  If the one you have selected is already taken, stop whining and pick another
  one. Perhaps it's time to consider why that key was taken, find the team
  responsible by running`git blame` on `data/docs.yml` and discuss the issue
  with them.

Order matters
: The order of root keys is also the order that documents will appear in the
  sidebar (and other places too, e.g. featured documentations, documentation
  page, etc).

Pages
: Each `pages` entry is an inline collection with a required key `title`. The
  `title` value **should match** the page filename. For example, for the
  `analytics/settings.html.md.erb` page, the `pages` entry should be:
  <br/>
  `- { title: 'settings' }`
  <br/>
  The `title` value is also the key to the localization of the page title.

: As a convention, the first `pages` entry should be the *index* page. It must
  set the `url` key to the base of the documentation. For example:
  <br/>
  `- { title: 'overview', url: '/analytics/' }`
  <br/>
  For consistency, the index page should have the title `overview`.

: If you need to link to an external page resource, set it with the `url` key:
  <br/>
  `- { title: 'settings', url: 'http://www.example.com/' }`
</div>

##### Example

The entry for the *Analytics* documentation is:

~~~ yaml
analytics:
  base: '/analytics/'
  featured: true
  icon: 'fa-bar-chart-o'
  pages:
    - { title: 'overview', url: '/analytics/' }
    - { title: 'settings' }
    - { title: 'ecommerce' }
~~~

### Update `locales/`

After updating the `data/docs.yml` with the documentation pages, it is required
to update the locale files with the missing translations.

##### Example

For the *Analytics* project, we update the `locales/en.yml` locale with the
`analytics` parent title translation under the `titles` section:

~~~ yaml
titles:
  analytics: 'Analytics'
~~~

and the proper translations for each of the documentation pages under the
`docs/analytics` section:

~~~ yaml
docs:
  analytics:
    short_description: 'Analytics is a platform that...'
    overview: 'Overview'
    settings: 'Settings'
~~~

## Localization

By default documentation is served in the English language for each flavor. Define
the `locale` property at the page [frontmatter](http://middlemanapp.com/basics/frontmatter/)
section to make it available in multiple languages for a given flavor.

##### Guidelines
{:.collapsible .collapsed data-toggle="collapse" data-target="#localization-guidelines" /}

<div id="localization-guidelines" class="collapse" markdown="1">

Locale
: You should define the proper `locale` rules for each of the translated pages,
  otherwise you may end up with inconsistent page links.
</div>

##### Example

Define available locales at the [frontmatter](http://middlemanapp.com/basics/frontmatter/)
section.

~~~ yaml
---
locale:
  alve:
    - 'en'
    - 'tr'
  scrooge:
    - 'en'
  skroutz:
    - 'en'
    - 'el'
---
~~~

and render the available `page_locales` partial to notify the users that the
page is available in multiple locales.

~~~ erb
<%%= partial 'partials/page_locales' %>
~~~