Get GAXPRO
Content

Docs Articles: content/docs/*.md

How to add documentation pages in GAX Pro. Covers frontmatter, sort order, sidebar navigation, search, and the docs layout.

Docs Articles: content/docs/*.md

Where Docs Pages Live

Documentation pages are Markdown files inside:


content/docs/

The controller page content/docs.md handles the docs listing. Each file in content/docs/ becomes a page at /docs/[filename]/. For example:

  • content/docs/installation.md → /docs/installation/
  • content/docs/configuration.md → /docs/configuration/

Docs Page Frontmatter

Every docs page has the same frontmatter structure:


---
layout: docs
sort: 2
title: "Installation: Go and Required Tools"
description: "Step-by-step guide to installing Go on Windows, macOS, and Linux."
image: "/images/go-ssg5.webp"
label: "Setup"
canonical: "https://gaxpro.axcora.com/docs/installation/"
---
  • layout: docs — uses the docs layout with sidebar
  • sort — controls the order in the sidebar (lower number = higher position)
  • title — shown as the page heading and in the sidebar
  • description — used for SEO and the sidebar search
  • image — hero image at the top of the page
  • label — a short category label above the title
  • canonical — the canonical URL

The sort field is required. Pages without it appear at the bottom of the sidebar.

How the Docs Sidebar Works

The docs layout renders a sidebar with all docs pages. The sidebar is built from:

1. The collections.docs loop in templates/layouts/docs.gax

2. The sort field in each page's frontmatter

3. The docs.js script in public/js/

The sidebar sorts by sort (ascending). Pages with sort: 1 appear first, sort: 2 second, and so on. Pages without a sort field appear at the bottom, sorted alphabetically.

The controller page content/docs.md uses sort: 0, so it appears at the top of the sidebar.

The docs layout includes a search input. The search filters pages by title and description:


render(docs.filter(function (doc) {
  var t = String(doc.title).toLowerCase();
  var d = String(doc.description).toLowerCase();
  return t.indexOf(q) !== -1 || d.indexOf(q) !== -1;
}));

To make a page searchable, add a description field. Pages without a description can still be found by title, but the description improves search relevance.

Writing the Docs Body

Below the frontmatter, the body is standard Markdown:


## What You Need to Install

GAX Pro requires two things:

1. Go (version 1.21 or newer)
2. A terminal

## Install Go on Windows

Download the installer from go.dev/dl and run it.

go version



## Next Step

- **[Download Source Code](/docs/download-source/)**

The body supports headings, lists, links, images, code blocks, tables, and blockquotes.

Heading Structure

The docs layout renders the title as the H1 heading. Start the body with H2 headings:


## First Section

Content here.

### Subsection

Content here.

## Second Section

Content here.

Using H1 in the body creates a duplicate heading. The page has two H1s, which is a minor SEO issue.

Adding a New Docs Page

To add a docs page:

1. Create a new Markdown file in content/docs/

2. Use a descriptive filename with hyphens — my-new-topic.md

3. Add frontmatter with layout: docs, sort, title, description, and canonical

4. Write the body in Markdown

5. Save the file and rebuild

Choose a sort value that places the page in the right position. If you add a page between sort: 5 and sort: 6, use sort: 5.5 or renumber the following pages.

Example minimal docs page:


---
layout: docs
sort: 16
title: "My New Topic"
description: "A short description of the topic."
image: "/images/go-ssg4.webp"
label: "Reference"
canonical: "https://gaxpro.axcora.com/docs/my-new-topic/"
---

## Overview

Content here.

## Examples

Content here.

Removing a Docs Page

To remove a docs page, delete its Markdown file from content/docs/. The sidebar updates automatically on the next build.

Common Errors

Page shows 404 — the file is not in content/docs/, or the filename is misspelled.

Page does not appear in the sidebar — the frontmatter is missing layout: docs, or the collection in content/docs.md does not include the folder.

Page appears at the bottom of the sidebar — the sort field is missing. Add a number to position it correctly.

Search does not find the page — the description field is missing or too short. Add a descriptive sentence.

Sidebar links are broken — the url generated from the filename does not match. Check that the filename uses lowercase words and hyphens.

Build fails — YAML syntax error in frontmatter. Check indentation and quotes.

Next Step

Docs pages are set. Next, set up the tags page:

Need Help?

  • Contact us — if a docs page does not render correctly