Versioning


No articles match the selected filter.

Setup

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

Configure

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

Run

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 Sep 19, 2018