--- 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://@gerrit.automotivelinux.org:29418/AGL/documentation" && scp -p -P 29418 @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. 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 | ├── ..... | | | ├──_ | | ├──_ | | | ├──_.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: --- ``` 2. Internal Linking : ```sh [](../_/_/_.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 ```