Contributing to the docs

Run locally

The documentation is a Starlight project under docs/, with its own package.json and lockfile. The generators and the content check are Python scripts that read the library, so the site is built from a checkout with the library installed.

Prerequisites:

• Python 3.10 or newer, in the repository’s virtual environment, with the library, its test extra, and the documentation tools installed: griffe generates the reference pages, mypy checks the examples, and pytest runs the scripts’ tests.
• Node.js 24 and pnpm 10.34.2. npx -y pnpm@10.34.2 runs the pinned pnpm without a global install.

From the repository root:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]" -r docs/requirements.txt
npx -y pnpm@10.34.2 --dir docs install --frozen-lockfile

Keep the virtual environment active for every command below: the docs/package.json scripts call python3, and without the environment they fail with ModuleNotFoundError: griffe.

Command	What it does
pnpm --dir docs check	Runs docs/scripts/check_content.py: the content check described below.
pnpm --dir docs generate	Runs docs/scripts/gen_api.py: writes the api/ and schema/ reference pages.
pnpm --dir docs build	check, then generate, then astro build with link validation. This is what CI runs.
pnpm --dir docs dev	Starts the Astro dev server on 127.0.0.1. Run generate once first so the reference sections exist.
pnpm --dir docs preview	Serves the last build from docs/dist.
python -m pytest docs/scripts/tests	The scripts’ own tests.

With npx in place of a global pnpm: npx -y pnpm@10.34.2 --dir docs build.

Where to edit

• Authored pages are Markdown under docs/src/content/docs/: the start-here pages, configuration/, guides/, events/, advanced/, and the top-level pages.
• api/ and schema/ inside that directory are generated on every build from the installed TikTokLive and TikTokLiveProto packages and are ignored by Git. Never edit or commit them. To change a reference page, edit the docstring or signature at the source declaration.
• The event catalog on events/index.md and the grouped event pages are authored. A row’s description is compared with the README’s description of the same event, so change both together.
• The sidebar, the site title and description, the header links, and the footer are in docs/astro.config.mjs.
• The content check and the generator live in docs/scripts/, with tests in docs/scripts/tests/.

Authoring rules

The build enforces these; a page that breaks one fails pnpm --dir docs build.

• A ```python fence is a complete module: imports, a client, and an if __name__ == "__main__": block where it runs. Every fence is parsed and type-checked with mypy against the installed package, so guard Optional fields such as event.user and annotate handlers with their event class. A snippet that should not be checked goes in prose or in another fence language.
• Shell commands use ```sh fences.
• No Discord links in page text. The header button is the one Discord link on the site, and the report channel named on pages is GitHub issues.
• Links to Euler Stream are plain Markdown links, dofollow, with no rel attribute. Every page carries at least one; the SEO gate described on the hosting page checks it.
• Internal links are site-relative with a trailing slash, /configuration/signing/, and point at pages that exist; the build validates them. Event anchors are the lowercase class name on the grouped page, /events/gifts-and-goals/#giftevent.
• Frontmatter has title and description; pages in an autogenerated sidebar group also set sidebar.order.

Where facts come from

Describe the library as it is in the checkout, not as the README or an older page says it was. In order:

1. The library source: TikTokLive/client/, TikTokLive/events/, TikTokLive/proto/, and the route modules. A signature, a default, an error class, or an emitted event is what the code does.
2. The README, for the event descriptions and the wording of the landing page.
3. The retired Sphinx pages, kept in Git history: git show 884489f:docs/src/index.rst lists them, and git show 884489f:docs/src/<file> reads one.

The examples/ directory shows the intended use but is not type-checked and has drifted from the API in places; the guides are the corrected versions. When a behaviour cannot be read from the code, run it against a live room and say what was observed rather than what the schema allows; see protocol types. When the code has a bug, describe the behaviour as it is and work around it in the example, as the troubleshooting page does for this release.

The content check

docs/scripts/check_content.py runs first in every build. It reads the code statically and the authored pages, skips api/ and schema/, and prints PASS or FAIL for nine sections in this order, with a Checked ... pages summary line:

Section	Passes when
events	Every event class in custom_events.py and proto_events.py is named in backticks on some page.
catalog	events/index.md has a row for every event whose second cell is its Webcast* message, or custom.
client	Every TikTokLiveClient constructor parameter and public method or property is named in backticks on some page.
web-defaults	Every _WebDefaults field is named in backticks on some page.
routes	Every module under TikTokLive/client/web/routes/ is named in backticks on some page.
env	Every environment variable read under TikTokLive/ is named in backticks on some page.
discord	No page links to Discord; the check searches for the two Discord link domains.
readme	Every README event with a description has a catalog row with the same wording.
examples	Every Python fence parses and type-checks; a deliberately wrong canary proves mypy saw the package.

The names must appear exactly as backticked tokens, `fetch_is_live` rather than `client.web.fetch_is_live`. The check tells you what is missing; it cannot tell whether a sentence is true, so verify behaviour in the source before describing it.

Deployment

.github/workflows/docs.yml runs the scripts’ tests, the full build, and the SEO gate on every pull request that touches the docs or the library, uploads the built site as a review artifact, and on pushes to master deploys it to Cloudflare Workers at https://ttl.docs.isaackogan.com/ and publishes the redirect pages for the old GitHub Pages site. See hosting for the Worker configuration, the secrets, and how to deploy from a checkout.

DOCS_SITE sets the public origin and defaults to the custom domain; DOCS_BASE sets the deployment subpath and defaults to /. Neither needs to be set for a normal build.