Documentation

Overview
Guidelines
Style
- Extensions and post-processing
Testing your documentation
Submitting patches for documentation and the website

Overview

Documentation is in ::docs and is entirely in markdown with Maruku extensions.

Guidelines

DO document Exherbo-specific tools and processes.
DO document Exherbo developer workflow and practices.
DO NOT document basic UNIX commands or information.
DO NOT document steps for package installation, configuration and usage.

Style

Your documentation must conform to the existing documentation style. A template has been provided for you in the file template.mkd.tmpl.

Always include the Title and CSS headers.
Include the head and foot templates at the beginning and end of your document, respectively.
Include a copyright notice just before the footer.

Extensions and post-processing

There’s a few changes to the raw markdown that will occur when they are converted to HTML.

[pkg:category/package-name] will be converted to links to packages in Summer. (ex. sys-apps/paludis)
[pkg:repository/repository-name] will be converted to links to the corrisponding repository page in Summer. (ex. repository/arbor)
[::repository] will be converted to a link to the repository on Git. (ex. ::docs)
Page titles (Title: ) will have “Exherbo - ” appended to them.

Testing your documentation

Maruku is required to render the markdown into html. Run make in the base directory of the documentation sources and point your web browser at the files.

The CSS is not included in the repository, so there won’t be any formatting.

Submitting patches for documentation and the website

We use the Creative Commons Attribution Share Alike 3.0 license for all documentation and website content. Contributions using other licenses are unlikely to be accepted.
Patches should be contributed via our Gitlab. The docs repository resides here.

This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License.
You can share, copy, redistribute and transform this document for any purpose, including commercial, but you must give appropriate credit and share under the same license as the original document.