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 there might be some differences. (We will switch to GFM one day.)

Content is organized in the content directory:

Content structure

URLs map to this structure pretty closely, basically just omitting the two-digit prefixes (the purpose of which is just to order things) and the file extensions. For example, content/en/03-sync/02-cloning.md is available at /en/sync/cloning.

Section home pages are represented by special _index.md files. For example, content/en/03-sync/_index.md is available at /en/sync.

Site navigation also reflects the file / folder structure, both in the sidebar and the "Next / Previous" links at the bottom of each topic. Documents' H1 determine the texts rendered.

Docs versioning

We use the Feature Toggle approach to maintain multiple versions of the documentation. There are no branches like versionpress-1.0 or versionpress-2.0, all is committed into the master and rendered based on 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 in its front matter.
  • The global configuration indicates which version to render, and for example if the shown version should be 1.0, the topic on WP-CLI is excluded from the navigation.

The since: tag can be specified either for a specific page at the top of the Markdown document or for the whole section in its config.yaml, see e.g. the sync section's config.yaml.

Authoring documentation

  • Start each file with an H1 header (# Some Title). This MUST be the first non-front-matter line of the document; the navigation system depends on it.
  • 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 into Markdown like this:
<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. Supported CSS classes are note (green), tip (blue), important (orange) and warning (red), the syntax is:
<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]. They will be highlighted in yellow and should be used rarely, possibly in alpha / beta versions of the doc topic.

Previewing and deploying updated docs

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. The updates are currently deployed manually.

Localization

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

Clone this wiki locally