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.

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

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.

Edit this page on GitHub