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. Register the repo (one time). Open a PR on GoTab-Inc/docs adding your repo to sources.json:

"my-service": {
  "source": "GoTab-Inc/my-service",
  "path": "docs",
  "ref": "main",
  "targetDir": "tools/my-service"
}

Your pages appear at docs.gotab.org/tools/my-service/, under Internal Tools. Everything under tools/ is internal, even pages marked access: public.

To publish two folders to different places, such as pages plus agent skills, use mappings instead of path / targetDir. Each mapping copies its whole folder, so keep the folders separate:

"my-service": {
  "source": "GoTab-Inc/my-service",
  "ref": "main",
  "mappings": [
    { "from": "docs/guides", "to": "src/content/docs/tools/my-service" },
    { "from": "docs/skills", "to": "src/content/docs/skills/my-service" }
  ]
}

3. Let the build read a private repo. The docs build reads repos through the docs GitHub App, so ask a GitHub org admin to add your repo to the App’s installation. Public repos need nothing extra.

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/ ──sources.json──→ 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