No articles match the selected filter.

Source Control


Presidium content can be managed in various ways depending on your project needs. Content may be hosted in:

  • A dedicated repo that only contains documentation
  • A sub-folder of an existing repo

A dedicated repo is simpler to configure and easier to manage independently. Managing content within in a sub directory inside the source code repo keeps everything in one place and makes it easier to update the documents while changing the code.

Sub Folder

Presidium can exist within a sub-folder of an existing source code repository, for example, /docs.

Getting Presidium

The easiest way to incorporate Presidium into your project is to run the wizard from your project root:

presidium init

And specify Project Name as docs, so that, Presidium creates and empty Presidium site under docs/ folder.

The contents of your docs/ folder should look something like this:


Add the following to your project’s .gitignore file:


From this point on, you can follow instructions in the Getting Started section. The only difference is that your documentation root is /docs.

Sub Module

If you want to store your documentation in a separate repository or share documentation between projects you can use submodules. Use the following steps to set up a submodule.

  1. Create a new repository for you module.
  2. Create a config.yml file and add the following
        - source: content
          target: content
  3. Create a content directory and add your markdown files. E.g.
    ├── config.yml
    └── content
        └── glossary
  4. Commit and push your changes
  5. To use your submodule, add it to the imports section of your project’s config.yml file. E.g.
      - path: <REPO_URL_OF_SUBMODULE>
        - source: content
          target: content

Content Structure

Directory Structure

When you create a Presidium site using the CLI init command, Presidium creates the directory structure for the selected template.

Sections and articles are arranged using the weight key in the front matter of each file, and to specify section level title and ordering you may use the file inside the directory containing a section.

The following is an example of how you can order and organize files and directories:

    ├── // Specify weight 1 here in front matter
    ├── Directory-2
    │   ├── // Specify weight 1 here in front matter
    │   ├── // Specify weight 2 here in front matter
    │   ├── // Specify weight 2 here in front matter, this will set `Directory-2` as the second item in the parent section
    ├── // Specify weight 3 here in front matter
    ├── // Specify weight 4 here in front matter
    └── // Specify weight 1 here in front matter

Please note that for Directory-2/ file we specify weight as 2, as in this case, this weight determines the ordering for the entire section with respect of its siblings (,,,

Using File Path Sorting

Add sortByFilePath: true under params: in the project’s config.yml to enable sorting by filepath. This will allow you to prefix your filenames and directories (not files) with a number instead of having to use weight in the front matter, for example, The entry in the config file should resemble the example below:

    sortByFilePath: true

Note: The main sections (for example, Reference and Overview) still have their weights set in the config.yml.


Github Pages

GitHub Pages provides a quick and convenient means of hosting and serving your documentation from a Github repository. The recommended way to host your Presidium site in Github Pages is to use GitHub Actions

If you are using GitHub Actions for the first time you can simply create a push.yaml file under .github/workflows and define your GitHub Pages job, if you already using GitHub Actions, you can simply add a job to deploy your documentation and configure your baseURL accordingly:

name: Presidium Github Pages
  - push

    runs-on: ubuntu-20.04
      group: ${{ github.workflow }}-${{ github.ref }}
      - uses: actions/checkout@v2
          submodules: true
          fetch-depth: 0
          persist-credentials: false
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
          hugo-version: '0.87.0'
          extended: true
      - name: Build
        run: hugo --minify --baseURL `https://<ORGANIZATION><REPOSITORY_NAME>`
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

If your documentation site uses private repository modules, you need to change the git config in order to be able to fetch from private repositories:

      - uses: actions/checkout@v2
          submodules: true
          fetch-depth: 0
          persist-credentials: false
      - name: Inject Golang Git Config
        run: git config --global url."https://${PRIVATE_GITHUB_TOKEN}".insteadOf ""

Note that we are using the environment variable PRIVATE_GITHUB_TOKEN which you need to create in your repository Settings > Secrets, containing a personal access token capable of downloading your private resources.

© Copyright 2022 SPAN Digital

Generated on Oct 24, 2022