# 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:
social:
- title: GitHub
url: https://github.com/Apostolique/apos-docs
svg:
```
`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.
For the links, find svg icons from . Pick the *medium* version of your chosen icon. Only include the path part of the svg.
For the social links, find svg icons from .
### 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:
paths:
- 'docs/**'
- 'README.md'
- 'CHANGELOG.md'
- '.github/workflows/documentation.yml'
env:
TITLE: Apos.Input
DESCRIPTION: Input library for MonoGame.
BASE: Apos.Input
REPO: https://github.com/Apostolique/Apos.Input/tree/main/
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Use Node.js
uses: actions/setup-node@v1
with:
node-version: '14.x'
- name: Install apos-docs
run: npm install apos-docs -g
- name: Use apos-docs
run: |
apos-docs -t '${{ env.TITLE }}' -d '${{ env.DESCRIPTION }}' -b '${{ env.BASE }}' -r '${{ env.REPO }}'
cd apos-docs
npm install
npm run build
cd -
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
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/
```
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]`.
The `REPO` variable is used to generate the edit links for each pages.
## 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.
## 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`.