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.administrate +-- 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' ---
titlekey manages the first heading title of the page, its name in the navigation menu on the left, and its name in the browser tab
taxonomykeys should always be left as is. They instruct Grav to use the proper theme and order the pages properly.
defaultkey makes the page available by default on
https://yunohost.org/docs/write_documentationinstead 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:
/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.
||Retrieves and processes app.json|
||Generated by this script, from this template|
||Lists the subpages in the same directory which have
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
masterif you want to work on another branch, but do not forget to create it on GitHub first)
config/themes/yunohost-docs.yamlto point to your fork's repository
user/pages/02.typographydirectories are deleted.
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.