Repository navigation
📚 Add Markdown content negotiation guide and fix docs tables - #58
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…rkdown-content-negotiation-guide
| pnpm add -D @types/negotiator | ||
| ``` | ||
|
|
||
| <Callout variant="warning" body="MDX can contain JSX and TinaCMS components. Most AI agents can still read it, but clients that require CommonMark may need a separate MDX-to-Markdown conversion step." /> |
There was a problem hiding this comment.
The preview shows the whole guide as raw source, because this string body fails the MDX parse.
There was a problem hiding this comment.
✅ Switched to the JSX body form the other docs use.
| Create a server endpoint for the source MDX: | ||
|
|
||
| ```typescript | ||
| // src/pages/_markdown/[...slug].ts |
There was a problem hiding this comment.
When I ran this on Astro 7, every text/markdown request returned a 404 because Astro skips _ folders under src/pages, and after a rename every path served index.mdx.
There was a problem hiding this comment.
✅ Moved the endpoint to src/pages/api/markdown and switched to context.rewrite, because next() kept the docs route params. Tested on Astro 7.4.7.
|
|
||
| Also test negotiation at both `/docs` and a nested docs URL: | ||
|
|
||
| | `Accept` header | Expected response | |
There was a problem hiding this comment.
Once the page parses this table renders with no rows, the same as the six tables on https://tina.io/docs/tinacloud/network-requirements, because table.tsx misses them.
There was a problem hiding this comment.
✅ table.tsx now renders what TinaMarkdown passes. This also restores the six tables on network-requirements, and I added an e2e check.
| response.appendHeader("Vary", "Accept"); | ||
| const type = new Negotiator({ | ||
| headers: { accept: request.headers.accept ?? "*/*" }, | ||
| }).mediaType(["text/html", "text/markdown"]); |
There was a problem hiding this comment.
When I ran the Vite example, text/* returned a 404 with no content type, where the table below expects HTML.
There was a problem hiding this comment.
✅ text/* now returns HTML. Vite only runs its HTML fallback when Accept names text/html or */*, so the example appends text/html for HTML requests.
|
Hey Isaac, Could you update this branch from main when you push the fixes? It's 9 commits behind and the checks are strict, so it can't merge until then. |
…t-negotiation-guide
- Use a JSX body on the callout so the page parses - Move the Astro endpoint out of the underscore folder and use context.rewrite so params match the rewritten route - Normalise Accept in the Vite example so Vite's HTML fallback runs - Render docs tables from the thead and tbody TinaMarkdown passes, which also restores the tables on other docs pages Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- State the guide's content layout, draft, and basePath assumptions - Keep the original Accept value in the Vite example so CSS still loads - Style links and code in table cells, restore the header divider - Add an e2e check for Markdown table rows Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
isaaclombardssw
changed the title
|
Updated from main and pushed the fixes. Checks are green. |
Add a guide for serving source MDX at existing page URLs when clients prefer Markdown. The Next.js 15 example matches TinaDocs' shipped middleware; Astro and Vite use the same
negotiatorselection for quality values, wildcards, and media-type casing.The guide covers
Vary: Accept, CDN cache separation, static-hosting limits, Astro's request-time rendering and source-file requirements, its content layout and draft assumptions, and a negotiation test matrix. Added to Technical Guides navigation.This also fixes the shared table renderer, so it affects every docs page with a Markdown table.
table.tsxlooked for rows in a shape TinaMarkdown doesn't pass, so tables rendered empty, including on the live network-requirements page. It now uses TinaMarkdown'str,th, andtdcomponents. Cells skip the rest of the component mapping, so link and code styles sit on the table.Validation:
pnpm tinacms build --local --skip-cloud-checks, Biome, andtsc./docsand nested paths: Next.js 15.5.29 (next start), Astro 7.4.7 (Node adapter), Vite 8.3.6 (dev and preview). Not tested on a CDN.tests/e2e/tables.spec.ts; Playwright passes against a local dev server, excluding the search specs.Related: tinacms/tina-docs#355; tinacms/tina.io#4896.