Recipes

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.

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:

config.yaml
go.mod
content/
static

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

docs/public

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

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

   module:
     mounts:
       - source: content
         target: content
   

3. Create a content directory and add your markdown files. E.g.

   ├── config.yml
   └── content
       └── glossary
           ├── _index.md
           └── link.md
   

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.

   module:
     imports:
     - path: <REPO_URL_OF_SUBMODULE>
       mounts:
       - source: content
         target: content
   

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

Sections and articles by default are ordered by file path. To make it easier to track the order of articles you can prefix your filenames and directories (not _index.md files) with a number, for example, 01-article.md.

Note: The number is added to the URL, for example, reference/01-section. To remove this add url: reference/section to the front matter of the section’s _index.md file.

The main sections (for example, Reference and Overview) are ordered by their weight value in the config.yml. For more information on weight, see below:

Sort Using Weight

In the project’s conifg.yml, under params:, change sortByFilePath: true to sortByFilePath: false to disable sorting by file path.

params:
    sortByFilePath: false

Sections and articles can be arranged using the weight key in the front matter of each file. For specifying section level titles and ordering use the _index.md file inside the directory for that section. Should a weight not be specified and sortByFilePath: false Hugo will fall back to the following to order content: Data > Link Title > FilePath. For more information, see Order Content in the Hugo documentation.

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

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

Note: For Directory-2/_index.md file we specify weight as 2, as in this case, this weight determines the ordering for the entire section with respect of its siblings (article-1.md, article-2.md, article-3.md, article-4.md)

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
on:
  - push

jobs:
  gh-pages:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 0
          persist-credentials: false
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.87.0'
          extended: true
      - name: Build
        run: hugo --minify --baseURL `https://<ORGANIZATION>.github.io/<REPOSITORY_NAME>`
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          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:

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

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.