Getting started

Quick guide to get you started with apos-docs.

Setup

In your GitHub repository’s root, you will need the following:

README.md
docs/getting-started.md
docs/img/Icon.png
docs/_data/nav.yml

README.md and getting-started.md are just regular markdown files. You can fill them both with the following content for now:

# Title

Hello World!

You can add links to the sidebar by creating the file docs/_data/nav.yml. You can replace the GitHub url for you own in social.

links:
  - title: Getting Started
    url: /getting-started/
    svg: <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" />

social:
  - title: GitHub
    url: https://github.com/Apostolique/apos-docs
    svg: <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12" />

links are shown at the top. The svg is optional.

social links are shown at the bottom, the svg is required and the title is used for screen readers or terminal browsers.

A link can hold its own links list to group pages under it. This nests as deep as you need:

links:
  - title: Getting Started
    url: /getting-started/
  - title: Reference
    url: /reference/
    links:
      - title: Buttons
        url: /reference/button/
      - title: Panels
        url: /reference/panel/

For the links, find svg icons from https://heroicons.com/. Pick the medium version of your chosen icon. Only include the path part of the svg.

For the social links, find svg icons from https://simpleicons.org/.

Pipeline

You can automated the site’s build process with a GitHub Actions workflow.

Create a .github/workflows/documentation.yml file with the following content:

name: Build documentation

on:
  push:
    branches:
    - 'main'
    paths:
    - 'docs/**'
    - 'README.md'
    - 'CHANGELOG.md'
    - '.github/workflows/documentation.yml'
  workflow_dispatch:

env:
  TITLE: Apos.Input
  DESCRIPTION: Input library for MonoGame.
  BASE: Apos.Input
  REPO: https://github.com/Apostolique/Apos.Input/tree/main/
  URL: https://apostolique.github.io/Apos.Input/

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22.x'
    - name: Install apos-docs
      run: npm install apos-docs@^0.7.0 -g
    - name: Use apos-docs
      run: |
        apos-docs -t '${{ env.TITLE }}' -d '${{ env.DESCRIPTION }}' -b '${{ env.BASE }}' -r '${{ env.REPO }}' -u '${{ env.URL }}'
        cd apos-docs
        npm ci
        npm run build
        cd -
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./apos-docs/_site

Edit the environment variables for your project:

env:
  TITLE: Apos.Input
  DESCRIPTION: Input library for MonoGame.
  BASE: Apos.Input
  REPO: https://github.com/Apostolique/Apos.Input/tree/main/
  URL: https://apostolique.github.io/Apos.Input/

The TITLE variable lets you define the project name to show on the sidebar.

THE DESCRIPTION variable is used as metadata in the site.

The BASE variable lets you define the subdirectory that the site will end up in. For a repository-level gh-pages deployment [username].github.io/[repository name], you should set the value to [repository name]. For a user or organization site served from the domain root, set it to ~.

The REPO variable is used to generate the edit links for each pages.

The URL variable is the address the finished site lives at. It’s what lets apos-docs tell
your own pages apart from everyone else’s: a full link that starts with this url is treated as
an internal link, anything else gets target="_blank". Leave it out and every absolute link to
your own site opens in a new tab.

npm install apos-docs@^0.7.0 -g pins the generator to a major version so a new release
can’t change your site without you asking for it. Bump it when you want the new version.

npm ci installs the exact versions apos-docs was tested with, instead of resolving fresh
ones on every run. Two builds of the same commit produce the same site.

Other options

-a, --analytics takes the measurement id of a Google Analytics 4 property, for example
G-AB1CD2EFGH, and adds the tracking snippet to every page. Leave it out and no analytics
code is included at all.

-p, --path points at the directory holding your markdown, in case you don’t want to call it
docs. It defaults to docs.

Run apos-docs --help for the full list.

Preview locally

If you want to see your docs before pushing, add --serve to the same command. It builds the
site, serves it on http://localhost:8080/, and rebuilds whenever you edit your markdown:

npm install apos-docs@^0.7.0 -g
apos-docs -t 'Apos.Input' -d 'Input library for MonoGame.' -b 'Apos.Input' -r 'https://github.com/Apostolique/Apos.Input/tree/main/' --serve

This is the only step that needs anything installed on your machine, and it’s optional. The
GitHub Actions pipeline above still handles everything on its own.

GitHub Pages

In your repository’s settings, go in the options and find the GitHub Pages section. In the Source, select the gh-pages branch and hit save.

Changelog

If your repository root has a CHANGELOG.md, it’s picked up automatically and published at
/changelog/. There’s nothing to configure, and nothing happens if the file doesn’t exist.

Its table of content only lists the top level headings, so a changelog written with one ##
heading per release gets a clean list of versions instead of every bullet underneath them.

Add it to the sidebar yourself if you want a link to it:

links:
  - title: Changelog
    url: /changelog/

The workflow above already rebuilds when CHANGELOG.md changes.

Draft

If a page isn’t ready to be published, you can append .draft to the file name. For example: name.md should become name.draft.md.

_{Edit this page on GitHub}

On this page