Presidium supports semantic versioning of your documentation when publishing to 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.
- Change the directory to the root of 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
- 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
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
For example, this is correct:
This is incorrect:
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.)
# Optional Support For Versioning
To publish a specific version:
$ npm run gh-pages -- -v 1.2
To publish the latest version:
- 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.
- 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