Adding Documentation

Publish Your Repo’s Docs in 3 Steps

Your docs stay in your repo. The docs site pulls them at build time — nothing gets copied.

Step 1. Create a docs/ folder in your repo with markdown files:

my-service/
└── docs/
    ├── index.md          # Landing page for your service
    ├── setup.md          # Additional pages
    └── api-guide.md

Every file needs frontmatter at the top:

---
title: My Service
description: What this page covers.
access: public
---

Your content here.

Set access: public on pages that should be visible to non-employees on docs.gotab.io. Omit it (or set internal) for employee-only pages on docs.gotab.org.

Step 2. Get an API key — create one at https://auth.gotab.org/keys scoped to docs.gotab.org/api/*. Add it as DOCS_API_TOKEN in your repo’s GitHub Settings → Secrets and variables → Actions.

Step 3. Add this file to your repo:

.github/workflows/publish-docs.yml

name: Publish Docs

on:
  push:
    branches: [main]
    paths: ['docs/**']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Register and rebuild docs
        run: |
          curl -sf -X POST https://docs.gotab.org/api/rebuild \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer ${{ secrets.DOCS_API_TOKEN }}" \
            -d '{
              "source": "GoTab-Inc/${{ github.event.repository.name }}",
              "path": "docs"
            }'

That’s it. Push to main and your docs appear at docs.gotab.org/tools/<your-repo-name>/.

---

How It Works

Your repo is registered as a doc source. When the docs site builds, it pulls your docs/ folder directly from GitHub, builds it into the site, and deploys. Your files are never committed to the docs repo.

your-repo/docs/   ──registered──→   sources.json   ──CI build──→   pulls docs/
                                    (pointer only)                  from your repo
                                                                         │
                                                              builds both sites
                                                              ├─ docs.gotab.org (all)
                                                              └─ docs.gotab.io (public only)

The first time you call /api/rebuild, it registers your repo in sources.json (a tiny config file — just a pointer, not your files) and triggers a build. Subsequent calls skip the registration if nothing changed and just trigger the rebuild.

Access Control

Pages default to internal only. Set access: public in frontmatter to publish to docs.gotab.io.

You can also mix public and internal content on the same page:

This content is visible on both sites.

:::internal
This section is only visible to GoTab employees on docs.gotab.org.
On docs.gotab.io it's stripped at build time — it never reaches the browser.
:::

This content is also visible on both sites.

Frontmatter	Behavior
(omitted)	Internal only — docs.gotab.org with SSO
access: public	Both sites
:::internal block	Stripped from public site

Rebuild API

Manage doc sources programmatically. Auth via cf_sso API key (Authorization: Bearer sso_...):

# Register (or trigger rebuild if already registered)
curl -X POST https://docs.gotab.org/api/rebuild \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sso_..." \
  -d '{ "source": "GoTab-Inc/my-service", "path": "docs" }'

# List all registered sources
curl https://docs.gotab.org/api/rebuild \
  -H "Authorization: Bearer sso_..."

# Unregister
curl -X DELETE https://docs.gotab.org/api/rebuild \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sso_..." \
  -d '{ "source": "GoTab-Inc/my-service" }'

Example Doc File

Here’s a minimal docs/index.md for a service:

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

## Overview

The Payment Service handles all payment processing for GoTab.

## Authentication

All requests require a Bearer token from the GoTab OAuth endpoint.

:::internal
### Internal: Debug Endpoints

POST `/internal/payments/:id/retry` — retry a failed payment.
Requires `admin` role.
:::

## Endpoints

### Create Payment Intent

POST `/v2/payments/intents`

Creates a new payment intent for a tab.

Other Ways to Edit

• GitHub editor: Edit markdown directly at github.com/GoTab-Inc/docs_content — GitHub renders Mermaid diagrams in preview
• Direct PR: Clone GoTab-Inc/docs_content, edit files in docs/, open a PR
• API reference: OpenAPI specs in public/specs/ power the interactive tester at /api-reference

LLM Access

Both sites expose content for LLM consumption:

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