Recipes


No articles match the selected filter.

Source Control

Approaches

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:

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.


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
    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
    

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 _index.md file inside the directory containing a section.

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

Please note that 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)


Hosting

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
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.


© Copyright 2022 SPAN Digital

Generated on Jun 24, 2022