Teable Help

新增或改写页面前，请阅读 Help 页面 SEO 与统计规范，包含标题、描述、多语言、内链、埋点及发布验收要求。

Development

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

npm i -g mintlify

Run the following command at the root of your documentation (where docs.json is)

mintlify dev

Paste Image

Use the Paste Image extension to paste images into the markdown file. Open mdx file and press cmd + option + v to paste image.

Image Assets

Images are shared repo assets. Keep paths stable, names searchable, and rendering consistent.

When a change includes images, ask the agent to read this section first and commit only images processed according to these rules.

Folder Rules

• Use images/{top-level-group}/{topic}/.
• Top-level groups: docs, selfhosted, api, security, changelog.
• docs maps to the Help Center Docs tab. Do not flatten images/docs/{topic}/ into images/{topic}/.
• {topic} maps to the navigation name in docs.json, such as ai, base, space, sso, authority-matrix, get-id, or activate.
• Do not put new screenshots in the images/ root.
• Do not commit random staging folders.
• Put unreferenced images in images/orphans/YYYY-MM-DD/... first. Do not delete them directly.
• Docs pages must not reference images/orphans/....

Naming

Use this format:

images/{top-level-group}/{topic}/YYYY-MM-DD-page-slug-purpose.png
images/{top-level-group}/{topic}/YYYY-MM-DD-page-slug-purpose.webp
images/{top-level-group}/{topic}/YYYY-MM-DD-page-slug-purpose-zh.png

• Date = day the image enters the docs repo.
• Page slug = docs page or feature area.
• Purpose = visible UI or action. Do not use image1 or random hashes.
• Use .png for static UI screenshots.
• Prefer .webp for animated screenshots.
• English-only screenshot = shared asset. Do not add -en.
• Chinese-specific screenshot = add -zh.

Image Handling

• Logos, inline icons, external button images, videos, and historical changelog media do not need screenshot styling.

MDX Usage

Use explicit <img> for docs screenshots:

<img
  src="/images/docs/ai/YYYY-MM-DD-page-slug-purpose.png"
  alt="AI Chat context selector"
  className="docs-screenshot"
/>

• Use className="docs-screenshot" for new PNG/WebP docs screenshots under images/docs/, images/api/, images/selfhosted/, and images/security/.
• Alt text must be non-empty.
• Alt text describes the visible UI or action. Do not use screenshot or the file name.
• Do not use ![](...) for new docs screenshots.
• Avoid width="400", percentage widths, and one-off image sizing.
• Changelog images keep their historical display. Add useful alt text when context exists. Do not add docs-screenshot blindly.

Publishing Changes

Changelog entries must be ordered by release date, newest first, in every language. Backfilled releases belong below newer announcements, even when published later. Keep same-day entries in their existing editorial order.

Before publishing a changelog, run:

python3 scripts/changelog_maintenance.py --write
python3 scripts/changelog_maintenance.py
python3 scripts/changelog_order.py --write
python3 scripts/changelog_order.py

The Changelog date order workflow validates all current language changelogs on pull requests and pushes. It also corrects ordering after direct writes to main, including automated backfills. This repair happens after the push; publishers should run maintenance and the sorter before committing to avoid a temporarily misordered deployment. The sorter checks current pages; the Docs SEO workflow also validates monthly and annual history.

The Teable Publish Website Changelog automation (also used by the scheduled publisher) sorts and validates its English and Chinese entries before creating GitHub blobs. It embeds the functions from scripts/changelog_publisher_order.cjs; keep that copy synchronized with this tested source when updating the automation. Run its regression checks with node --test scripts/test_changelog_publisher_order.cjs.

Push to origin main branch, the changes will be deployed to production automatically.

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Page loads as a 404 - Make sure you are running in a folder with docs.json

Changelog history and local preview

The main */changelog.mdx pages contain recent releases. January–September 2026 entries live in */changelog-2026-MM.mdx; annual 2024 and 2025 pages retain their existing URLs. Monthly pages and their RSS feeds are reachable from the changelog navigation and the history links at the end of the main page.

Use ## for a release title and ### for its subsections. The page title provides the single H1. Preserve explicit heading IDs and adjacent legacy <span id> aliases: Mintlify normalizes custom heading IDs differently from some historical automatic IDs. The main page's data-changelog-* attributes route previously shared hashes to the correct month. Keep those attributes after the last Update so the publisher can prepend entries without moving the history footer.

Run node --test scripts/test_changelog_navigation.cjs and the publisher tests when changing history navigation. RSS generation and hosted permanent redirects need a deployed preview; the local CLI does not serve RSS feeds.

For this large multilingual repository, a reliable local preview command is:

ulimit -n 65536
NODE_OPTIONS=--max-old-space-size=8192 npx --yes mintlify@4.2.1059 dev --no-open

Restart the preview after a large batch of MDX edits before checking the rendered pages, to avoid accumulating hot-reload memory during a full-site review.

Automated changelog writes are also checked with:

python3 scripts/changelog_maintenance.py --write
python3 scripts/changelog_maintenance.py

Maintenance keeps the newest published month at the main URL, moves older entries into monthly history (or an existing annual page), and merges historical republications by release date. It preserves old heading/date aliases, updates history navigation and routing metadata, removes unsupported custom JSON-LD, and gives new headings stable IDs. Messages for newly generated pages live in .github/changelog-locales.json. Annual heading aliases are retained so future backfills cannot renumber old automatic IDs.

Publishers should run maintenance before committing. The existing main-branch repair workflow also runs it after direct automated writes, using the same retry behavior as date-order repairs. PR checks have read-only permissions.

Date-based publishers must use one Update per date. If historical data has multiple entries on the same date, maintenance preserves their order when untouched and rejects ambiguous republications. Currently combine the intended content into one Update. Supporting separate entries on the same date requires a future publisher identity format. This prevents both silent content loss and duplicate date IDs generated by Mintlify.

SEO checks

Install the validation dependencies and run the read-only source checks before publishing documentation:

python3 -m pip install -r scripts/requirements-seo.txt
python3 scripts/check_docs_seo.py
python3 -m unittest discover -s scripts -p 'test_*.py'
node --test scripts/test_*.cjs
npx --yes mintlify@4.2.1059 validate
npx --yes mintlify@4.2.1059 broken-links --check-anchors --check-redirects

The Docs SEO workflow runs these commands on pull requests and main. Source checks cover localized metadata, body heading levels, crawlable cards, navigation, retired-page policies, changelog periods and previously published hashes.

After starting the local preview above, check the generated HTML:

python3 scripts/check_rendered_seo.py --base-url http://localhost:3000

This checks every changelog, historical hash, native documentation card, intentional hidden/archive page and the core guides in all locales. Add --all to inspect every current MDX page. The command compares rendered titles, H1s, descriptions, robots, card destinations and any JSON-LD against the sources and documented indexing policy. It also checks duplicate content IDs and retired-route redirect destinations; local redirects may use 307 even for permanent rules. It only reads HTML and does not send analytics events.

Before release, verify a deployed preview's canonical and reciprocal hreflang URLs, sitemap exclusions, RSS contents, permanent redirects and actual GA4 event receipt. These platform-managed behaviors cannot be proved by the local CLI.