apos-docs/docs/getting-started.md

Documentation static site generator built with Eleventy.

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

```md
# Title

Hello World!
```

### Navigation

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

```yml
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:

```yml
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:
```yml
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:

```yml
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:

```sh
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:

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