---
title: Adding Documentation
---

The [documentation gerrit
repository](https://gerrit.automotivelinux.org/gerrit/admin/repos/AGL/documentation)
contains AGL documentation website template and content, rendering is visible at
[https://docs.automotivelinux.org](https://docs.automotivelinux.org).
The documentation site is hosted on
[readthedocs](https://readthedocs.org/projects/automotivegradelinux/) and
corresponding builds are mentioned
[here](https://readthedocs.org/projects/automotivegradelinux/builds/).

## Download Repository


Clone with commit-msg hook :

```sh
$ git clone "ssh://<LFID>@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 <LFID>@gerrit.automotivelinux.org:hooks/commit-msg "documentation/.git/hooks/"
```

## Building a local site

1. Change into the directory

    ```sh
    $ cd documentation
    ```

2. Install MkDocs and rtd-dropdown theme

    ```sh
    $ sudo pip install -r requirements.txt
    ```

3. If pip is not already installed then install it 
    ```sh
    $ sudo apt-install python3-pip
    ```


4. Serve locally (default rendered at [127.0.0.1:8000/](127.0.0.1:8000/)):

    ```sh
    $ sudo mkdocs serve
    ```

Process to **add new or edit existing** markdown files to AGL documentation:

## Directory Structure

Find existing or add new markdowns in the following directory structure.

```sh
documentation
├── docs
│   ├── 1_Getting_Started
│   │   ├── 1_Quickstart
│   │   └── 2_Building_AGL_Image
|   ├── .....
|   |
|   ├──<Chapter_Number>_<Chapter_Name>
|   |   ├──<Subchapter_Number>_<Subchapter_Name>
|   |   |   ├──<Index_Number>_<Markdown_Title>.md
|   |   |   ├── .....
```
**File Naming convention** AGL follows Snake Case (snake_case) naming convention to name the documentation files.
This type of naming combines words simply by replacing the space with an underscore (_).
All the names will also include a index number before the name.
Index number will use two digit numbers from 01-99 followed by name of the file.
For example: If the file name is Build Process then it will be written as 01_build_process.md

**Note:** If a file needs to be inserted in between already created sequences, then the index number will be the last index number followed by new numbering. For example, A new file is inserted between 06-07, then the index number for the new file will be 07_01, as in gist sorting, 07_01 will appear after 06 and before 07.

## Markdown Formatting

  1. Add following at the start of each markdown :

    ```sh
    ---
    title: <enter-title>
    ---
    ```

  2. Internal Linking :

    ```sh
    [<enter-title>](../<Chapter-Number>_<Chapter-Name>/<Subchapter-Number>_<Subchapter-Name>/<Index-Number>_<Markdown-Title>.md)



    ```

## Test Hyperlinks
[Broken Link Checker](https://github.com/stevenvachon/broken-link-checker) is a tool that allows to
check all the hyperlinks in the site.

For testing hyperlinks as soon as the local site is running, do:

```sh
$ blc http://localhost:8000 -ro
```


For testing hyperlinks of live website do:

```sh
$ blc https://docs.automotivelinux.org/en/master/ -ro
```

The ```Broken Link Checker``` output will display the broken link and there location in
the site.


## Submitting changes

1. Install Git Review

    ```sh
    #recent version of git-review  (>=1.28.0 is required)
    $ sudo pip3 install git-review 
    ```

2. Write commit message (**Note:** Please follow [submitting changes](./04_Submitting_Changes.md) guideline to write your commit message.)

    ```sh
    # track all the new changes
    $ git add .

    # Write the commit message
    $ git commit --signoff
    ```

3. Push changes for review to Gerrit

    ```sh
    # first time only
    $ git review -s

    # then to push use
    $ git review
    ```