doc/pages/06.contribute/05.write_documentation/write_documentation.md

---
title: Write documentation
template: docs
taxonomy:
    category: docs
routes:
  default: '/write_documentation'
---


## Via GitHub

The YunoHost documentation is managed through a [Git repository](https://github.com/YunoHost/doc).

If you are not familiar with GitHub, there is an "Edit" button at the top of each page that will redirect you to the GitHub online editor that will help you make change proposals (Pull Requests, PR).

However, if you are on an editing spree, you should fork the repository. You can then make all the commits (changes) you want on your forked repository, and submit them all at once in the same pull requests. GitHub's etiquette would advise you to gather in the same PR all related commits.

Because the online editor doesn't support uploading files, using Git is the prefered way if you need to upload media (e.g. images).

## Grav

Under the hood, the documentation is served by the [Grav CMS](https://getgrav.org/?target=_blank).

The structure of the repository is described below:

```text
+-- config
   +-- site.yaml
   +-- system.yaml
   +-- themes
       +-- yunohost-docs.yaml
          # Some settings for the documentation theme
+-- images
   # Contains the images used in the documentation pages.
+-- pages
   # The directory containing the documentation pages.
   # The pages hierarchy is reflected by the directory hierarchy.
   +-- 00.home
   +-- 01.administer
   +-- 02.applications
   +-- 03.community
   +-- 04.contribute
+-- themes
    +-- learn4
    +-- yunohost-docs
       # Contains the theme's code, which extends Learn4 theme's code
+-- .gitignore
    # Contains the instructions to not send sensitive
    # or useless files over to the Git repository
+-- README.md
```

!!!! To learn more about Grav's features, you can head over to its [documentation](https://learn.getgrav.org?target=_blank). The remainder of this page will show you some specific instructions to contribute to YunoHost's documentation.

## Grav header

Each page starts with a header that gives instructions to Grav on how to process them. Let us have a look into the header of this page:

```text
---
title: Write documentation
template: docs
taxonomy:
    category: docs
routes:
  default: '/write_documentation'
---

```

1. The header starts and ends with a line containing `---`
2. The `title` key manages the first heading title of the page, its name in the navigation menu on the left, and its name in the browser tab
3. `template` and `taxonomy` keys should always be left as is. They instruct Grav to use the proper theme and order the pages properly.
4. `routes`' `default` key makes the page available by default on `https://yunohost.org/docs/write_documentation` instead of needing to reaching it on `https://yunohost.org/docs/contribute/write_documentation`, which is where it is stored in the directory hierarchy.

## Syntax

You can use Markdown syntax, refer to the [documentation](/doc_markdown_guide) for further information.

! Note that language codes are not to be included at the beginning of the links to other documentation pages: `/en`, `/fr`, etc. are superfluous.

To improve Markdown capabilities, additional plugins are installed in Grav. You can refer to their own documentation on GitHub to see how to use them.

```text
anchors
external_links
flex-objects
highlight
image-captions
markdown-notices
presentation
presentation-deckset
shortcode-core
```

## Special pages

Some pages of the documentation are automatically or dynamically generated.

| Page          | Path  | Notes |
|---------------|-------|-------|
| Apps catalog  | `/pages/02.applications/01.catalog/apps.md` | Retrieves and processes [app.json](https://github.com/YunoHost/apps/blob/master/apps.json?target=_blank) |
| Apps helpers  | `pages/04.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md` | Generated by this [script](https://github.com/YunoHost/yunohost/blob/dev/doc/generate_helper_doc.py?target=_blank), from this [template](https://github.com/YunoHost/yunohost/blob/dev/doc/helper_doc_template.md?target=_blank) |
| Per-app documentation | `pages/02.applications/02.docs/docs.md` | Lists the subpages in the same directory which have `taxonomy.category: docs, apps` in its header |

## Host your own testing documentation

! These instructions are yet to be fully tested. Please help us by reporting any issue you may have with them.

0. Fork YunoHost documentation repository
1. Install Grav's YunoHost package: `yunohost app install grav`
2. Install the following plugins through Grav's admin panel or CLI:

```text
anchors
breadcrumbs
external_links
feed
flex-objects
git-sync
highlight
image-captions
langswitcher
markdown-notices
presentation
presentation-deckset
shortcode-core
tntsearch
```

3. Set-up Git Sync plugin.
   1. Choose GitHub and your credentials on GitHub
   2. Set the repo, e.g. `https://github.com/username/doc`
   3. Copy the Webhook's URL, e.g. `https://grav.example/_git-sync-ca25c111f0de`
   4. Basic settings > Folders to Sync: `pages` `images` `themes`
   5. Git Repo Settings > User not required: Enabled
   6. Git Repo Settings > Web Hooks secret: Enabled
   7. Advanced settings > local branch: `master`
   8. Advanced settings > remote branch: `master`  
(you can change `master` if you want to work on another branch, but do not forget to create it on GitHub first)
   9. Advanced settings > Committer Name: your GitHub username
10. Advanced settings > Committer Email: your email saved on GitHub
11. Save and Reset Local Copy
12. Set `commits` and `tree` keys in `config/themes/yunohost-docs.yaml` to point to your fork's repository
4. Make sure `user/pages/01.home` and `user/pages/02.typography` directories are deleted.
5. Configuration > System:
   1. Language > Supported: `en` `fr` `de` `es` `ar`
   2. Language > Override Default Language: `en`
   3. Language > Set language from browser: `Yes`
   4. HTTP Headers > Etag: `Yes`
   5. Advanced > Blueprint Compatibility: `Yes`
   6. Advanced > YAML Compatibility: `Yes`
   7. Advanced > Twig Compatibility: `Yes`