docs: scaffold Trace FX developer documentation#1
Merged
marioalvial merged 11 commits intomainfrom Apr 14, 2026
Merged
Conversation
Removes example pages (ai-tools, essentials, api-reference, development), placeholder snippets, and AGENTS.md to make room for Trace FX docs.
New folder layout: guides/, journeys/, webhooks/, reference/, apis/. OpenAPI specs for fx-account (scoped to /api) and fx-payment (scaffold). 7 reusable snippets, updated docs.json with two-tab nav (Guides + API Reference), SEO metadata, and base URLs. CLAUDE.md and CONTRIBUTING.md with terminology, rules, and conventions.
Dual-layer validation adapted from trace-knowledge-base vault: - 7 evals: frontmatter, content-depth, descriptions, orphans, navigation coverage, freshness, OpenAPI completeness - 3 PostToolUse hooks: frontmatter validation (blocking), body section template check (warning), description quality (warning) - 8 page-type templates defining required sections - /evaluate skill for running evals - GitHub Actions CI pipeline (mint build, broken-links, accessibility, markdownlint, gated eval thresholds) - Shared Python library (_lib.py) for evals and hooks
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
- mint build -> mint validate (build is not a valid CLI command) - mint accessibility -> mint a11y (correct alias) - Disable MD037 (false positives from MDX comment syntax) - Disable MD007, MD032 (MDX comments with indented lists) - Lower openapi-completeness threshold to 0 for scaffold phase
- Re-enable MD007 and MD032 markdownlint rules; fix the actual cause (indented list inside MDX comment in errors-catalog.mdx) - OpenAPI completeness: restore 50% threshold, use continue-on-error so the check reports score without blocking PRs during scaffold phase
Hooks were defining their own copies of FRONTMATTER_RE, PLACEHOLDER_PATTERNS,
PAGE_TYPE_RULES, and parsing functions. This caused maintenance drift risk and
a bug in validate-body-sections.py where infer_type() hardcoded "api-docs" in
the path, breaking page type inference when the repo is cloned elsewhere.
- Extract load_hook_input() and abs_to_rel() helpers into _lib.py
- Rewrite all 3 hooks to import from _lib.py (net -64 lines)
- Fix hardcoded path: use REPO_ROOT-based abs_to_rel() + infer_page_type()
- Narrow bare except in freshness-checker.py to (OSError, ValueError)
- Add missing example: {} to fx-payment ErrorResponse.details for consistency
freshness-checker provides no useful signal — it trivially passes on new pages and its 90-day global threshold doesn't fit docs with varying update cadences. Removed the eval, its CLAUDE.md entry, and /evaluate skill references. Also fix docs.json seo.indexing: "navigated" is not a valid Mintlify enum value — corrected to "navigable", which was breaking both the Mintlify Deployment check and the CI build validation job.
Remove endpoint nav entries and reference overview pages from docs.json — Mintlify can't generate pages from schema-less stub operations, which was breaking mint validate with 14 warnings. OpenAPI YAML files stay in apis/ for future use. The API Reference tab, openapi config, and reference pages will be re-added when schemas are fleshed out. Also removes the openapi-completeness CI job (no endpoint pages to validate until the tab returns).
The errors-catalog reference page was removed when deferring the API Reference tab. Point the snippet to guides/principles/errors instead.
Primary #16A34A fails WCAG AA contrast (3.30:1 vs 4.5:1 required). Switch to #15803D (5.02:1) which passes AA and stays in the Trace green family.
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
What's included
Documentation structure
OpenAPI specs (deferred from navigation)
apis/fx-account/openapi.yml— 1 fully specified endpoint (GET /api/accounts/{accountId})apis/fx-payment/openapi.yml— 13 endpoint scaffolds awaiting request/response schemasQuality system
Rules & conventions
Changes during review
freshness-checkereval (irrelevant for a docs site with varying update cadences)mint validate)openapi-completenessCI job (re-add when API Reference tab returns)seo.indexingtypo ("navigated"→"navigable")#16A34A→#15803D, 3.30:1 → 5.02:1)Test plan