Quick Menu

Write documentation

Via GitHub

The YunoHost documentation is managed through a Git repository.

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.

The structure of the repository is described below:

+-- 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. 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:

---
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 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.

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
Apps helpers pages/04.contribute/04.packaging_apps/11.helpers/packaging_apps_helpers.md Generated by this script, from this template
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.

  1. Fork YunoHost documentation repository
  2. Install Grav's YunoHost package: yunohost app install grav
  3. Install the following plugins through Grav's admin panel or CLI:
anchors
breadcrumbs
external_links
feed
flex-objects
git-sync
highlight
image-captions
langswitcher
markdown-notices
presentation
presentation-deckset
shortcode-core
tntsearch
  1. 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
  2. Advanced settings > Committer Email: your email saved on GitHub
  3. Save and Reset Local Copy
  4. Set commits and tree keys in config/themes/yunohost-docs.yaml to point to your fork's repository
  5. Make sure user/pages/01.home and user/pages/02.typography directories are deleted.
  6. 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

¿Encontraste errores? ¿Crees que puedes mejorar esta documentación? Simply click the Edit link at the top of the page, and then the icon on Github to suggest changes.