---
title: Rédaction de la documentation
template: docs
taxonomy:
    category: docs
routes:
  default: '/write_documentation'
---

## Via GitHub

La documentation de YunoHost est gérée sur un [dépôt Git](https://github.com/YunoHost/doc).

Si vous n'êtes pas familier avec GitHub, il y a un bouton "Éditer" en haut de chaque page qui vous redirigera vers l'éditeur en ligne de GitHub et qui vous aidera à proposer vos modifications (appelées *Pull Requests*).

Directement sur GitHub, vous pouvez faire un *fork* du dépôt, y faire vos modifications, et envoyer vos *pull requests*.

Puisque l'éditeur en ligne ne permet pas d'ajouter des fichiers, utiliser Git par la ligne de commande est la méthode recommandée si vous voulez ajouter des médias (comme des images).

## Grav

Sous le capot, la documentation est déployée avec le [CMS Grav](https://getgrav.org/?target=_blank).

La structure du dépôt est décrite ici:

```bash
+-- config
   +-- site.yaml
   +-- system.yaml
   +-- themes
       +-- yunohost-docs.yaml
          # Quelques paramètres pour le thème de la documentation
+-- 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.administrate
   +-- 02.applications
   +-- 03.community
   +-- 04.contribute
+-- themes
    +-- learn4
    +-- yunohost-docs
       # Contient le code du thème, qui est une extension du thème Learn4
+-- .gitignore
    # Contient les instructions pour ne pas envoyer de fichier
    # sensible ou inutile vers le dépôt Git
+-- README.md
```

!!!! Pour en apprendre plus sur les fonctionnalités de Grav, vous pouvez consulter sa [documentation](https://learn.getgrav.org?target=_blank) (en anglais). Le reste de cette page donne quelques consignes spécifiques pour contribuer à la documentation de YunoHost.

## L'en-tête des pages Grav

Chaque page commence par un en-tête qui donne les instructions à Grav sur comment la traiter. Regardons l'en-tête de cette page :

```
---
title: Rédaction de la documentation
template: docs
taxonomy:
    category: docs
routes:
  default: '/write_documentation'
---

```

1. L'en-tête commence et finit par une ligne contenant `---` ;
2. La clé `title` gère le premier titre de la page, son nom dans le menu de navigation à gauche, et son nom dans l'onglet du navigateur ;
3. Les clés `template` et `taxonomy` doivent toujours être inclues et laissées telles quelles. Elles informent Grav sur quel thème appliquer aux pages, et permettent de les ordonner correctement.
4. La clé `routes` et son enfant `default` font que la page est accessible par défaut à l'adresse `https://yunohost.org/docs/write_documentation` au lieu de devoir la chercher à l'adresse `https://yunohost.org/docs/contribute/write_documentation`, qui correspond à son emplacement réel dans la hiérarchie des dossiers.

## Syntaxe

Vous pouvez utiliser la syntaxe Markdown, consultez la page de [documentation dédiée](/doc_markdown_guide) pour plus d'information.

Pour étendre les fonctionnalités de Markdown, des extensions ont été ajoutées à Grav. Vous pouvez consulter leur propre documentation sur GitHub pour découvrir comment vous en servir.
```text
anchors
external_links
flex-objects
highlight
image-captions
markdown-notices
presentation
presentation-deckset
shortcode-core
```

## Pages spéciales

Quelques pages de la documentation sont générées automatiquement ou dynamiquement.

| Page          | Chemin | Notes |
|---------------|--------|-------|
| Catalogue d'applications  | `/pages/02.applications/01.catalog/apps.md` | Récupère et traite le fichier [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` | Générée par ce [script](https://github.com/YunoHost/yunohost/blob/dev/doc/generate_helper_doc.py?target=_blank), à partir de ce [canevas](https://github.com/YunoHost/yunohost/blob/dev/doc/helper_doc_template.md?target=_blank) |
| Documentation des apps | `pages/02.applications/02.docs/docs.md` | Liste les sous-pages du même dossier qui ont les clés `taxonomy.category: docs, apps` dans leur en-tête |

## Hébergez votre propre documentation de test

! Ces instructions ne sont pas encore complètement testées. Aidez-nous en nous rapportant tout problème que vous rencontriez.

0. *Fork* le dépôt de la documentation YunoHost sur GitHub
1. Installez l'app Grav pour YunoHost : `yunohost app install grav`
2. Installez les extensions suivantes via l'admin ou la ligne de commande de Grav :
```text
anchors
breadcrumbs
external_links
feed
flex-objects
git-sync
highlight
image-captions
langswitcher
markdown-notices
presentation
presentation-deckset
shortcode-core
tntsearch
```
3. Paramétrez l'extension Git Sync.
   1. Choisissez `GitHub` et vos identifiants GitHub
   2. Entrez l'adresse de votre *fork*, par exemple `https://github.com/username/doc`
   3. Copiez l'URL du webhook, par exemple `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`  
(vous pouvez changer `master` en une autre branche si vous le souhaitez, mais n'oubliez pas de la créer au préalable sur GitHub)
   9. "Advanced settings" > "Committer Name" : votre nom d'utilisateur sur GitHub
  10. "Advanced settings" > "Committer Email" : votre email renseigné sur GitHub
  11. Enregistrez et cliquez sur "Reset Local Copy"
  12. Renseignez les adresses dans les clés `commits` et `tree` dans `config/themes/yunohost-docs.yaml` pour quelles pointent vers l'adresse de votre *fork* sur GitHub
4. Assurez-vous que les dossiers `user/pages/01.home` et `user/pages/02.typography` sont supprimés.
5. Dans l'administration de Grav, dans "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`