Skip to content
This repository was archived by the owner on Mar 21, 2019. It is now read-only.

Home

Jump to bottom
Borek Bernard edited this page Nov 4, 2015 · 4 revisions

VersionPress Documentation

VersionPress uses a docs system inspired by Composer Docs, Git Book or Azure Docs. The content is authored as a set of Markdown files in this repo and eventually published at docs.versionpress.net.

Overview

Documentation is written in Markdown, specifically in the MarkdownDeep dialect with extra mode switched on. This makes it pretty close to GitHub Flavored Markdown (GFM) although not exactly the same. We will probably switch to GFM at some point in the future.

Content is organized in the content directory like this:

Content structure

If you visit the docs site you will see that it pretty closely maps to the site structure and also the URLs. The whole system is heavily based on conventions, the most important ones being:

  • URLs are the file paths stripped of the two-digit prefix and the file extension. For example, content/en/03-sync/02-cloning.md is available as docs.versionpress.net/en/sync/cloning.
    • _index.md is a special file that renders the section homepage and is available at a virtual "parent" URL, for example, content/en/03-sync/_index.md is available as /en/sync. The same could be achieved by creating a content/en/sync.md file.
  • Main navigation reflects the file structure, including ordering. That's why there is the (optional) two-digit prefix.
  • Document's H1 (usually the first line containing # Some Title) becomes the ToC title used in the main navigation and other navigational features.

Some minor things are configured in config.yaml files (see below) but convention is generally preferred over configuration.

Docs versioning

We use the Feature Toggle approach instead of the more common but also cumbersome Git branches approach. This means that we only have a single set of docs articles for all versions of VersionPress, all committed to the master branch, and what is shown or hidden on the docs site is determined by version toggles.

The system works like this:

  • Doc topics optionally specify which version they apply to using the since: tag. For example, the topic on WP-CLI commands is available since VersionPress 2.0 and the file indicates this with since: 2.0.
  • The global configuration indicates which version to render, and for example if the shown version should be 1.0, the topic on WP-CLI will not be shown in the navigation. If the user still somehow visits the page, he/she will not see the content, just a message that this topic is being prepared for the future.

The since tag can be specified either for a specific page at the top of the Markdown documents in the so called front matter block, or for the whole section in its config.yaml (see e.g. the sync section).

Authoring documentation

  • Start each file with an H1 header (# Some Title). This will also be used in the navigation.
    • The only thing that can go before the header is the front matter section.
    • Use atx-style headers, i.e., # H1, ## H2, etc.
  • Use Title Case for H1 headers, Sentence case for H2 and below.
  • Images: put them in the content/media folder, max 700px wide, optimize them and reference relatively. Include them like this into the Markdown:
<figure style="width: 80%;">
  <img src="../../media/image.png" alt="Alt text" />
  <figcaption>Image caption</figcaption>
</figure>
  • Notes / warnings / tips can be written in special boxes using the following syntax. Supported CSS classes are note (green), tip (blue), important (orange) and warning (red).
<div class="note">
  <strong>Note title</strong>
  <p>This will be rendered in a highlighted box.</p>
</div>
  • TODO markers can be written as [TODO] or [TODO some arbitrary text] which will be highlighted in yellow. Should only be used occasionally, e.g., in alpha and beta versions of the documentation.

Previewing documentation

The engine running the docs site is an internal project at the moment so the only way to preview the pages is to use some Markdown editor.

We plan to open source the docs engine we use.

Localization

We currently only have an English version living in the content/en directory. In the future, localized versions will live in sibling directories.

Localization is not fully worked out yet.

Clone this wiki locally