No articles match the selected filter.


Presidium supports semantic versioning of your documentation when publishing to Github pages.

Github Pages

Presidium versioning relies on the use of the gh-pages branch to publish current and versioned documentation.

To use Presidium versioning, you will need to make you sure have a gh-pages branch set up in your repository. Skip these steps if you already have a branch set up.

  1. Change the directory to the root of your project:
cd path/to/your/project

If the branch already exists (be sure you know what you are doing), you can clean gh-pages and start again:

$ git push origin --delete gh-pages
$ git branch -D gh-pages
  1. Create a new gh-pages branch with nothing in it:
$ git checkout --orphan gh-pages && git reset --hard
$ git commit --allow-empty --m "Initialize gh-pages"
$ git push -u origin gh-pages
$ git checkout master

Update .gitignore

Presidium uses a hidden folder as a staging area for publishing. To make sure you don’t accidentally commit this folder, run the following command:

$ echo ".versions" >> .gitignore


Update Variables in _config.yml

Presidum supports the use of simple variables in _config.yml. To use versioning, you must make sure that any helper variables that include the base url of your site are defined using a ${...} variable.

For example, this is correct:

baseurl: /myRepositoryName
code_examples: ${baseurl}/media/code_examples

This is incorrect:

baseurl: /myRepositoryName
code_examples: /myRepositoryName/media/code_examples

Make sure you don’t introduce circular dependencies when using variables.

Set the Base URL & Turn on Versioning

To use Presidium versioning on gh-pages, you must use the base url of the repository. Make sure that this is set in _config.yml in the root of your project. (Note the lack of a trailing slash.)

baseurl: /myRepositoryName

# Optional Support For Versioning
versioned: true


To publish a specific version:

$ npm run gh-pages -- -v 1.2

To publish the latest version:

$ npm run gh-pages

Versioning Conventions

  • Presidium will display only the latest five semantically versioned releases of your documentation.
  • Presidium only supports numeric semantic versions.
  • Presidium names the latest version as ‘latest’. This means that if you have versions 1.0, 1.1, 1.2, 1.3, 1.5, you will see: latest, 1.5, 1.4, 1.3 and 1.2.

Known Issues

  • The versioning UI component is not yet responsive.
  • A user cannot view versions by serving the documentation locally.
  • Turning off versioning does not prevent access to the version if the url is known.
  • Currently, only publishing to Github pages is supported.
  • If the use of a CNAME is disabled, it is not removed from .versionswhen republished.

© Copyright 2018 SPAN Digital

Generated on Nov 21, 2018