Changelog

Highlights

Windows fix for projects that live on a different drive than the installed tangly (issue #6).

• Cross-drive projects render again. With your docs on E:\ and a global tangly on C:\, pages rendered blank: Astro stored an absolute drive-letter path for each page, and resolving it read the E: drive as a URL scheme (ERR_INVALID_URL_SCHEME). Those paths are now rewritten to file:// URLs before resolution, so cross-drive builds and dev servers work. Same-drive Windows and macOS/Linux were never affected. (9200ec9)

Changes

Fixes

• fix(plugin): resolve a cross-drive ERR_INVALID_URL_SCHEME that blanked pages when the project and the runtime were on different Windows drives (9200ec9)

Tests

• test(build): add a windows-latest CI gate that subst-maps a virtual drive to reproduce the cross-drive case before every release

Highlights

Hardening pass driven by a real-world 275-page Mintlify migration deployed to Cloudflare Workers static assets.

• check passing now predicts build passing. Every page is parsed with the build’s MDX syntax config, and JSX expressions are scope-checked: a literal {snake_case} placeholder in prose (valid MDX, dies at prerender with a ReferenceError) is reported at check time as file:line:col with a wrap-in-backticks hint. (f78a22c)
• Build failures point at your source file. A prerender error used to surface as a 30-line stack into .prerender/chunks/<page>_<hash>.mjs; the build now re-runs the MDX scan for an exact source diagnosis and otherwise maps the chunk name back to the page. (b0fb2a1)
• dist/ no longer ships repo internals. .git gitlink files (submodule checkouts leaked a local path), dotfiles, Makefile, wrangler.*, vercel.json, netlify.toml, and *.bak are excluded by default; .well-known/ and .nojekyll still ship, and a !pattern in .tanglyignore re-includes anything overridable. (c5b025c)

Changes

Features

• feat(theme-ui): emit a <meta name="generator" content="Tangly vX.Y.Z"> tag in every page head, so the framework and version of a built site can be identified over plain HTTP (curl the page and grep name="generator"). The version is injected by the Tangly integration as import.meta.env.TANGLY_VERSION.
• feat(cli): check parses MDX and flags unbound expression identifiers before they become prerender ReferenceErrors (f78a22c)
• feat(cli): build failures report the source .mdx at file:line:col instead of a prerender chunk stack (b0fb2a1)
• feat(cli): migrate rewrites Mintlify alias themes to tang and prompts for siteUrl when absent (7ff04ca)

Fixes

• fix(build): stop shipping repo internals (.git gitlink, dotfiles, Makefile, wrangler.*, *.bak) into dist/ (c5b025c)
• fix(theme-ui): keep page chrome (contextual menu, breadcrumbs, pagination, TOC) out of the Pagefind search index (e3723c6)

Docs

• docs(guides): Cloudflare Workers static-assets deploy recipe — html_handling: "drop-trailing-slash" (output is directory-style but canonicals are no-slash) and not_found_handling: "404-page"

Highlights

This release is a broad compatibility-hardening pass: we ported six real-world Mintlify documentation sites (an OpenAPI reference, a legacy mint.json project, a multi-tab developer portal, a Mermaid/snippets-heavy site, and the official Mintlify docs) and closed every parity gap they surfaced.

• OpenAPI with zero wiring. A root openapi.json / openapi.yaml / openapi.yml is now auto-discovered, so pages with openapi: "METHOD path" frontmatter render the full split-layout playground without any api.openapi config. (ce13ae4)
• Anchors-as-navigation. A top-level navigation.anchors[] entry that wraps whole tabs/groups now resolves. Sites whose entire sidebar lives under an anchor previously rendered with an empty sidebar; now every page is reachable. (652d7fb)
• Split your docs.json across files. JSON $ref includes ({ "$ref": "./redirects.json" }, per-language nav files) resolve before validation, with #/pointer fragments, nested refs, and cycle detection. (0074c72)
• Full-bleed landing pages. The custom and frame page modes now drop the sidebar and render edge-to-edge; center drops the sidebar too. Default/wide/api pages are unchanged. (969a723)
• Real home pages. A root index.mdx renders at / (not just a redirect splash), with draft visibility honored and / + /index canonicalized so they don’t compete as duplicate content. (738f6b4)
• Reusable snippet imports + a Link component. import of an /snippets/* Markdown file now resolves against your project root, and Link (with href) is a built-in.
• Live .jsx/.tsx snippets, and smarter MDX snippets. A React component snippet imported from /snippets/*.jsx renders as an interactive Preact island: hooks work as globals the way Mintlify exposes them, client:visible is auto-attached so it hydrates, and react/react-dom alias to preact/compat. Pages with no JSX snippet ship zero extra client JS. An imported .mdx snippet now inherits the page’s component set, so a snippet that uses Note/Card (or imports another snippet) renders correctly. (9cbcfbb, 2e2ed18)
• Comprehensive Font Awesome icons. About 880 Font Awesome names now resolve to Lucide glyphs (FA 6 renames like magnifying-glass, directional angle-*/caret-* families, and nearest-glyph picks), so icons carried over from Mintlify render unchanged. Names with no Lucide equivalent fall back to a help-circle. (7684d72)

Changes

Features

• feat(manifest): auto-discover root OpenAPI spec (ce13ae4)
• feat(manifest): resolve top-level anchors as navigation containers (652d7fb)
• feat(manifest): resolve docs.json $ref includes (0074c72)
• feat(manifest): render the default version/language nav variant (b13500c)
• feat(theme-ui): full-bleed landing layout for custom/frame modes (969a723)
• feat(theme-ui): add Link component (e62d557)
• feat(plugin): resolve /snippets/ imports against the project root (8a9d3b7)
• feat(theme-ui): comprehensive Font Awesome to Lucide icon coverage (7684d72)
• feat(runtime): render JSX/TSX snippets as preact islands (9cbcfbb)
• feat(runtime): imported MDX snippets inherit the page component set (2e2ed18)

Fixes

• fix(runtime): render the root index page at the site root (738f6b4), gate it on draft visibility (fa1eb21), and canonicalize / + /index (5e40d0f)
• fix(manifest): exclude project meta files from page discovery (da213f8), case-insensitively (1e902e5), plus root public/static/assets (fe2f9b4)
• fix(manifest): render only one default nav variant (b2d44be) and error on an unresolved $ref pointer (b49fed4)
• fix(theme-ui): expand Font Awesome to Lucide icon aliases (bdfe738, 00f653e, 866214e, e5f7e22)

Tests

• test(manifest): cover meta-file exclusion + OpenAPI auto-discovery (4dedaac), anchors-as-nav (504ac69), $ref resolution (af8e8b2), and the draft-home invariant (1c1a588)
• test(runtime): cover snippet island injection + MDX snippet component threading (9cbcfbb, 2e2ed18)

Highlights

• Refined code highlighting out of the box. The default Shiki theme is now Vitesse (vitesse-light / vitesse-dark), replacing github-light / github-dark. It reads warmer and more editorial, and the dark background blends with the ink page surface instead of sitting on a mismatched slab. Any bundled Shiki theme still works via code.theme.
• Branded loading splash. The root route now shows a full-page splash with your logo (or the site name) over an accent-coloured loader, adopting the active theme’s colours and fonts, in place of the old bare “Loading…” text. It works across every theme with no per-theme code.
• Independent, changed-only releases. Releases now publish only the packages whose source actually changed, at independent versions. This is the first release cut that way: schema, theme-ui, and tangly ship at 0.1.7 while the five leaf themes stay at 0.1.6 and pick up the new shared code through caret ranges.

Accessibility: secondary (“muted”) text now meets WCAG AA contrast in both light and dark.

Changes

Features

• feat(runtime): default code highlighting to vitesse (a474da0)
• feat(theme-ui): branded full-page loading splash (21f5297)
• feat(website): robots.txt, OG card, non-redirecting sitemap (e38ca9f)

Fixes

• fix(theme-ui): raise muted text contrast to WCAG AA (a7d9cf3)
• fix(website): a11y label-in-name + alt text, CSP, video demo (19ae33b)

Refactors

• refactor(schema): host resolveSite to break the theme-ui / tangly cycle (6c6945d)

Build

• build(release): publish only changed packages at independent versions (4ed8f7c)

Highlights

• Version provenance in every command. tangly check, build, and migrate now stamp the running version into their output, and validation errors print a footer naming the version that produced them. This makes the most common upgrade false alarm self-diagnosing: a stale global install (npm i -g tangly) shadowing a freshly-updated local one on PATH, where npm list tangly reports the new version but the typed tangly command still runs the old global. The footer points you straight at tangly --version.
• Update notifier. In an interactive terminal, the CLI checks npm at most once every 12 hours and prints a one-line notice when a newer tangly is published, with the upgrade command. It is fail-silent (offline or slow registry: nothing prints), never runs in CI or piped output, and opts out with TANGLY_NO_UPDATE_CHECK or NO_UPDATE_NOTIFIER.

Prompted by @quader864’s follow-up on #6: the reported errors were a stale global binary, not a schema bug. These changes make that obvious next time.

Changes

Features

• feat(cli): stamp running version in output + npm update notifier (#6, 0f437cc)

Highlights

• Friendly, key-by-key config errors. When docs.json does not validate, tangly check, migrate, dev, and build now print an exhaustive, readable report instead of a raw Zod dump. Each problem names the key (with a navigation.tabs[1].groups[0].pages style path), the line number, a plain-English reason, the offending value, and a suggested fix (Mintlify rename hints plus did-you-mean for misspelled enum values). Malformed JSON points a caret at the exact line and column.
• Broader Mintlify compatibility. A group inside a tab can now carry its own openapi spec and expands into endpoint pages nested under that group ({ source, directory } object refs scope the generated slugs under directory). Many more real-world docs.json shapes parse unmodified: groups without pages, banner critical tone and color, errors.404 title/description, icons.library: "tabler", background.image light/dark pairs, object-form styling.codeblocks, bare-font-face fonts, metadata.timestamp, navbar social links and primary CTAs, api.auth.default, contextual.display, and thumbnails.appearance/fonts.
• Extensive Mintlify backwards-compat CI. Tangly now vendors 24 real published docs.json configs from across the ecosystem (bun, ngrok, Cobo, Hyperswitch, Upstash, Portkey, and more, spanning six themes and 2KB to 180KB) and parses every one in CI, so a future change that breaks compatibility with a real Mintlify project fails the build.

Thanks to @quader864 for the detailed report in #6 that drove this round of compatibility work.

Changes

Features

• feat(cli): friendly, key-by-key docs.json validation errors (#6, 5be6200)
• feat(manifest): expand group-level OpenAPI specs (#6, 5f7ee98)
• feat(website): showcase social cards and agent-markdown features (b73bffc)
• feat(website): live GitHub stars + version/release pill in header (d08ed8a)

Fixes

• fix(cli): surface friendly config errors from dev/build + migrate JSON (93a2bfd)
• fix(schema): accept navbar/api/contextual/thumbnails shapes + 16 configs (#6, 19f72ea)
• fix(manifest): scope object-ref openapi pages under directory (#6, a9880d7)
• fix(schema): accept more Mintlify docs.json shapes (#6, 51774e4)
• fix(website): show 5 themes with docs.json theme field, starter as scaffold (141efb8)

Docs

• docs: sync npm/GitHub READMEs, correct theme and component counts (cfcbf66)

CI

• ci(smoke): Windows CI leg + parity tests vs real Mintlify configs (#6, f358fb6)

Tests

• test(schema): use Mintlify pages-nesting in #6 nested-group fixture (#6, 2a1b4bb)

Highlights

• Windows is unblocked. tangly dev and tangly build crashed on Windows with TypeError [ERR_INVALID_URL_SCHEME]: The URL must be of scheme file. The content loader handed your project root to Astro as a raw path string, and a drive-letter path like E:\project parses its E: as a URL scheme. The root is now passed as a proper file: URL, so it resolves on every platform (#6).
• Mintlify api.playground.display is accepted. Mintlify renamed api.playground.mode to display (interactive / simple / none / auth). Unmodified projects hit Unrecognized key: "display" on parse. The value now normalizes to Tangly’s native mode (none maps to hide, auth to interactive) across dev, build, check, and migrate.

Changes

Fixes

• fix(schema): alias api.playground.display to native mode (666771a)
• fix(runtime): pass file URL as glob base for Windows compat (15ad9aa)

Highlights

• Social cards, generated per page. Drop a docs link in Slack, iMessage, or X and it unfurls with a branded 1200x630 Open Graph image instead of rendering blank. Each card is built from the page title, description, owning tab, theme, and your colors and logo. Cards prerender to /og/<slug>.png at build and render on demand under tangly dev, so you can preview them live. Per-theme styling (tang, pith, pip, readable, geist each get their own look). Generation turns on automatically once a site URL resolves. Customize with thumbnails in docs.json, override one page with seo.ogImage in frontmatter, set a single static image site-wide with thumbnails.image, or turn it off with thumbnails.enabled: false. Drafts and noindex pages get no card.
• Per-environment site URLs. Canonical tags and og:image now resolve per deploy instead of always baking the production host. --site-url / TANGLY_SITE_URL override it, Vercel / Netlify / Cloudflare Pages deploy URLs are auto-detected, and tangly dev uses the live request origin. Preview and staging deploys point og:image at the current deploy (so the image resolves), keep canonical on production (so previews never compete in search), and emit robots: noindex. A new --env production | preview flag drives the posture where a platform exposes no production signal.

Changes

Features

• feat(schema): add thumbnails social-card config to docs.json (51524ac)
• feat(runtime): prerender Open Graph social cards per page (e7596e0)
• feat(theme-ui): shared Seo component, wire generated og:image (16d64c6)
• feat(cli): resolve site URL per environment for canonical + og:image (5c4eea9)
• feat(theme-ui): og:image at deploy host, canonical at prod, noindex previews (44361f3)

Fixes

• fix(runtime): contain og logo reads to docs root, mirror openapi titles in cards (e44de2c)
• fix(cli): reject unknown —env values (ef324a4)

Highlights

• OpenAPI endpoint pages, closer to Mintlify. Endpoint pages now render an Authorizations section derived from the spec’s security scheme, a breadcrumb method/path header with an inline Try it button, left-aligned method badges in the sidebar, and request bodies that expand anyOf/oneOf/allOf schemas (with spurious GET/HEAD bodies suppressed).
• Theme polish. Cleaner code blocks: a single border with square top and rounded bottom corners, readable underline tabs, and a Copy button with a clipboard icon (a check on success). The sidebar keeps your place across navigations and gained bottom padding so the last item is not clipped under the announcement banner.

Changes

Features

• feat(theme-ui): bring OpenAPI endpoint pages to Mintlify parity (eba59d4)

Fixes

• fix(theme-ui): force white text on primary navbar button (4ad013a)
• fix(theme-ui): add sidebar bottom padding so the last nav item clears the fold (9d25f71)
• fix(theme-ui): tidy code block chrome (corners, borders, tabs, copy icon) (169ebe7)
• fix(theme-ui): keep sidebar scrolled to active page across navigations (aacd7ab)

Chore

• chore(tangly): drop unused exports flagged by knip (e3f49ea)

Highlights

• OpenAPI endpoint pages, Mintlify-grade. Split layout (docs left, sticky playground panel right), language-tabbed code samples (cURL, TypeScript, Python, Go) with auto-generated content plus x-codeSamples / <RequestExample> overrides, tabbed responses by status code, sectioned Path/Query/Header/Cookie params, method-color sidebar pills, and x-hidden / x-excluded support.
• TANGLY_OPENAPI_URL env override plus .env.local / .env loading in dev, build, and preview. Point docs at a dev or staging spec without editing docs.json; unset = prod fallback. Loaded files are logged on startup.
• Per-page Copy / View Markdown menu in every page header. LLM-friendly raw output is also emitted as a sibling .md at build time, alongside llms.txt and llms-full.txt.
• SEO + social out of the box from a new siteUrl field: canonical, og:url, og:image, full twitter:* set, sitemap, robots, redirects, security headers.
• Schema additions: api.codeSamples.{languages,autogenerate,prefill,defaults}, api.params.{expanded,post}, api.url: "full", api.playground.credentials, siteUrl. Mintlify aliases (api.examples.*) normalize at parse time so existing projects keep working.
• Repo hygiene: local CI gate via .githooks (bun run check pre-commit, bun run ci pre-push), unified Cloudflare Workers deploy, knip for dead-code / dep scans, vitest coverage with a public badge.

Changes

Features

• feat(cli): load .env.local + .env in dev/build/preview (c83c3f5)
• feat(openapi): TANGLY_OPENAPI_URL env override (3b584c1)
• feat(runtime): auto mode=api + thread responseFallback to OpenApiEndpoint (b5473cb)
• feat(theme-ui): mode=api PageShell + sidebar method pills (4c2ff5d)
• feat(theme-ui): split OpenApiEndpoint into openapi/* cluster with right-rail panel (9e63914)
• feat(manifest): parse x-codeSamples, x-hidden, x-excluded; thread methodColor (c20af78)
• feat(schema): codeSamples/params/url/credentials with mintlify aliases (d6ac2af)
• feat(website): SEO + a11y + security audit fixes (33cb953)
• feat(theme-ui): emit canonical, og:url, og:image, twitter:* from siteUrl (9687e86)
• feat(schema): add siteUrl field to docs.json (63924a4)
• feat(release): docs/changelog.mdx as GH release notes source (7374e7c)
• feat(website): add Fast dev server row to features section (b35049e)
• feat(theme-ui): per-page Copy/View Markdown menu (2717810)
• feat(plugin): synthesize sitemap/robots/llms.txt in dev (5825be4)

Fixes

• fix(cli): stage adjacent to deepest node_modules in workspace mode (8ffdce6)
• fix(website): add missing brand icon assets (35be6fb)
• fix(theme-ui): satisfy listbox/option ARIA contract in SearchModal (dca8937)
• fix(runtime): exclude node_modules + build dirs from content collection (d95c9ee)
• fix(plugin): MDX shims skip code spans + fences (78cadcf)
• fix(theme-ui): keep sticky sidebar pinned at page bottom (9220a6f)
• fix(theme-ui): style Mermaid with Tangly tokens, drop dark code-block bg (cb06d17)
• fix(manifest): strip /index suffix from page slugs (6954a65)
• fix(theme-ui): render empty FileTree directories as leaves (dca312a)
• fix(ci): align coverage gist filename to coverage.json (010048d)

Refactor

• refactor(skills): rename tanglify to tangly (fb271bd)

Docs

• docs(openapi): RequestExample, codeSamples, x-extensions (81ce02d)
• docs: drop the cheap mintlify jab from fast-dev-server pitch (cb38ffe)
• docs: demote body H1→H2 across corpus + rewrite broken links (042c5d5)
• docs: lead with fast dev server (Astro+Vite, HMR <250ms) (657767e)
• docs(template+demos): humanize starter scaffold + theme demos (4d35698)
• docs: humanize prose, drop em dashes, sync drift (5e6fc74)
• docs(contextual): document Copy page menu, enable on tangly.dev (7768c3e)
• docs(components): document mermaid + complete components hub (34948a2)
• docs(intro): sync ‘What you get’ with README features, no em dashes (c7d9ffa)
• docs(navbar): keep only the GitHub anchor (with icon), drop duplicates (066a50d)
• docs(deploying): nest FileTree, drop redundant H1 + self-loop redirect (2929f2a)
• docs(readme): wire coverage badge to gist nc9/e57cc6d6 (a496574)
• docs(readme): add npm, build, coverage, downloads, license badges (c6a6c19)

Build

• build(repo): make link/link-pkgs/link-consumer for cross-repo workspace dev (7b47927)
• build(repo): add local CI gate via .githooks (9d650d1)
• build(docs): siteUrl, redirects, security headers, drop-trailing-slash (01e8643)
• build(deploy): unified Cloudflare Workers deploy via GH Actions (8cb3085)
• build(website): wire Cloudflare Workers Static Assets deploy (b4ba0c8)
• build(test): add @vitest/coverage-v8 + test:coverage script (c032b7c)

CI

• ci(repo): weekly knip dep-report cron (b4db8d4)
• ci(coverage): emit coverage JSON and publish to gist on main (d9ca919)
• ci: re-run against tangly@0.0.12 (verify installer-smoke green) (768acb4)

Chore

• chore(repo): adopt knip for dep / dead-code scans (317ad98)
• chore(repo): add oxfmt config (0c95963)
• chore(repo): gitignore .envrc (48402aa)

Tests

• test(theme-ui): demo-tang openapi fixture for endpoint pages (d32de44)
• test(manifest): bump cold buildManifest test to 30s timeout (40f1e8e)

Style

• style(repo): apply oxfmt to 4 drifted files (8d5905b)