Adding Documentation

The docs site builds from two kinds of content:

• This repo (GoTab-Inc/docs_content) for operator help, training, guides, concepts, reference and cross-cutting skills.
• Registered repos. Any GoTab repo can publish its own docs/ folder, so a service’s docs live next to its code.

Both sites build from the same content:

Site	Shows	Audience
docs.gotab.org	Every page	GoTab employees (SSO)
docs.gotab.io	Only pages marked access: public	Everyone

Writing a page

Every page is a Markdown (.md) or MDX (.mdx) file with frontmatter:

---
title: Payment Service
description: Payment processing APIs and integration guide.
access: public
sidebar:
  order: 2
---

Start with what the reader needs, in a sentence or two.

## A section heading

Field	Required	Notes
title	Yes	Rendered as the page’s H1, so don’t add another # Title in the body.
description	Yes	One sentence. Search results and llms.txt show it, so say what the page answers.
access	No	public publishes to docs.gotab.io. Leave it out, or set internal, for employee-only pages.
sidebar.order	No	Position within its sidebar section; lower comes first.

Writing tips:

• Lead with what the reader is trying to do, then the steps. Background and design go last.
• Keep ## / ### headings short; they become the page’s table of contents and link anchors.
• Show real commands, queries and config in fenced code blocks. Check they work before publishing.
• Link to other pages with site paths (/reference/access-control/) or relative links. Within a registered repo’s folder, relative links like ./setup/ keep working wherever the folder is mounted.
• Mermaid diagrams work in a ```mermaid block.

Mixing public and internal content

A public page can hold employee-only sections:

This content is visible on both sites.

:::internal
Only GoTab employees see this, on docs.gotab.org.
The public build strips it, so it never reaches the browser.
:::

Publishing a repo’s docs

Your docs stay in your repo; the docs build pulls them each time it runs.

1. Add a docs/ folder with Markdown pages written as above. index.md is the landing page.

my-service/
└── docs/
    ├── index.md
    ├── setup.md
    └── api-guide.md

2. Publish from your repo: commit docs/publish.yaml. Nothing changes in GoTab-Inc/docs; every docs build looks for this file in each repo it can read.

docs/publish.yaml

pages:
  - from: docs/guides
    to: tools/my-service
  - from: docs/skills
    to: skills/my-service

• from is a folder in your repo; to is where it appears on the site (tools/my-service → docs.gotab.org/tools/my-service/). Each entry copies its whole folder, so keep pages and skills in separate folders.
• Images or videos your pages use go in an optional assets list, published to images/<name> or videos/<name>.
• ref is optional (default: your default branch). The manifest itself is never published.

Folders nest: you can publish inside another repo’s folder (tools/my-service sits inside docs_content’s site root), and where both have the same file, the more specific folder’s copy wins. Two repos can’t publish the same folder: the older repo keeps it and the other is skipped. A taken folder or a bad manifest skips your repo with a warning in the build log, and a bad or duplicate skill name skips that skill. Your repo can never break the build for anyone else. docs_content publishes the same way, with its own docs/publish.yaml.

Access is each page’s own access: frontmatter, everywhere: access: public also puts a page on docs.gotab.io, including pages under tools/. Anything else stays internal (docs.gotab.org only).

3. Let the build read a private repo. The docs build finds and reads repos through the docs GitHub App, so a private repo needs the App installed (ask a GitHub org admin, unless it’s installed on all repos).

4. Rebuild on push. Add this workflow to your repo. It pings the two Workers Builds deploy hooks, and no GitHub token is involved:

.github/workflows/rebuild-docs.yml

name: Rebuild docs
on:
  push:
    branches: [main]
    paths: ['docs/**']
  workflow_dispatch:
jobs:
  rebuild:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        hook: [DOCS_INTERNAL_DEPLOY_HOOK, DOCS_PUBLIC_DEPLOY_HOOK]
    steps:
      - env:
          HOOK: ${{ secrets[matrix.hook] }}
        run: |
          if [ -z "$HOOK" ]; then
            echo "::error::${{ matrix.hook }} isn't available to this repo. It should be a GoTab-Inc org secret shared with all repositories."
            exit 1
          fi
          curl -sf -X POST "$HOOK"

DOCS_INTERNAL_DEPLOY_HOOK and DOCS_PUBLIC_DEPLOY_HOOK are GoTab-Inc org secrets shared with all repositories, so there’s nothing to set up in your repo. Don’t add repo secrets with the same names: a repo secret overrides the org secret, and it goes stale when the hooks are rotated.

If the job fails with “isn’t available to this repo”, the org secrets are missing or restricted; ask a GitHub org admin. Even without the workflow, your changes publish on the next docs build that anyone triggers.

How it works

your-repo/docs/ ──publish.yaml──→ pull-sources (docs build)
                                     ├─ docs.gotab.org (all pages)
                                     └─ docs.gotab.io  (access: public only)

The build syncs incrementally: it skips a source whose commit hasn’t changed and downloads only the files that did.

Editing pages in this repo

• On the site: the Edit page link opens the article editor.
• On GitHub: edit files under docs/ in GoTab-Inc/docs_content. A merge to main rebuilds both sites.
• API reference: OpenAPI specs in public/specs/ drive the interactive tester at /api-reference.

LLM access

Both sites expose content for LLMs and agents:

Endpoint	Format	Description
/llms.txt	Text	Index of all pages with titles and URLs
/llms-full.txt	Text	Full content of all pages concatenated
/api/knowledge	JSON	Knowledge base articles with category filtering