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).
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.
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'
---
---
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 tabtemplate
and taxonomy
keys should always be left as is. They instruct Grav to use the proper theme and order the pages properly.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.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
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 |
These instructions are yet to be fully tested. Please help us by reporting any issue you may have with them.
yunohost app install grav
anchors
breadcrumbs
external_links
feed
flex-objects
git-sync
highlight
image-captions
langswitcher
markdown-notices
presentation
presentation-deckset
shortcode-core
tntsearch
https://github.com/username/doc
https://grav.example/_git-sync-ca25c111f0de
pages
images
themes
master
master
master
if you want to work on another branch, but do not forget to create it on GitHub first)commits
and tree
keys in config/themes/yunohost-docs.yaml
to point to your fork's repositoryuser/pages/01.home
and user/pages/02.typography
directories are deleted.en
fr
de
es
ar
en
Yes
Yes
Yes
Yes
Yes
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to suggest changes.
Powered by Grav + with by Trilby Media. • Terms of Service