xyd

Open-source documentation framework, honestly reviewed. No marketing fluff, just what you get when you adopt a beta-stage tool made by an analytics company for its own needs.

TL;DR

• What it is: An MIT-licensed, CLI-driven documentation framework with first-class OpenAPI/GraphQL support, built-in themes, and a plugin architecture — positioned against Mintlify, GitBook, and Docusaurus [README][website].
• Who it’s for: Developer-facing product teams, specifically API-first SaaS companies that need docs covering REST/GraphQL specs and generated SDKs without paying $150–500/mo for Mintlify or GitBook [README].
• Cost savings: GitBook teams start at $6.70/user/mo; Mintlify Startup is $150/mo; ReadMe starts at $99/mo. xyd is MIT-licensed and self-hosted — your only cost is a static hosting bill (Netlify/Vercel free tiers work) [README][website].
• Key strength: Native OpenAPI + GraphQL + SDK generation from specs, six polished themes, and an unusually wide integration surface (search, analytics, A/B testing, live chat) baked in from day one [README].
• Key weakness: 105 GitHub stars as of this writing, v0.1.0-beta status, requires Node 22.12+, and zero independent reviews exist yet. This is early-stage software built by a single company for its own needs, not a community-validated tool [README][website].

---

What is xyd

xyd is a documentation framework built and open-sourced by LiveSession, a session replay and analytics company. The pitch is “docs framework for future dev” — a static site generator specifically designed around the documentation needs of developer-facing products: API references, SDK guides, interactive code examples, and theme customization [website][README].

You install it globally via bun add -g xyd-js, run xyd to spin up a dev server, and xyd build to generate static files. It handles MDX content, generates API documentation directly from OpenAPI and GraphQL specs, and ships with six pre-built themes — Solar, Gusto, Poetry, Picasso, Opener, and Cosmo — each with a public demo [README].

The project started because LiveSession needed a documentation platform that could handle its own complex API surface and decided to build and open-source it rather than pay ongoing SaaS fees. The GitHub description is plainly accurate: “ambitious docs framework for everyone” [README]. Whether it has fulfilled that ambition yet is a different question.

What makes the pitch interesting: xyd ships integrations that docs frameworks usually leave to the user to wire up themselves. Analytics (with LiveSession native support), full-text search (Orama and Algolia), A/B testing (GrowthBook and LaunchDarkly), and live chat (Intercom, LiveChat, Chatwoot) are all listed as built-in plugin integrations rather than DIY additions [README][docs]. For a team that wants documentation that behaves more like a product surface than a static wiki, that bundled approach saves meaningful configuration time.

---

Why people choose it

No independent third-party reviews of xyd exist at this time — all sourced review sites were inaccessible during research. What follows is based entirely on the project’s own README and website, the documentation at xyd.dev, and what can be inferred from the competitive landscape.

That honesty matters here. With 105 GitHub stars and beta status, xyd hasn’t been adopted at scale and hasn’t been stress-tested by reviewers outside its own team. This is a tool you’d choose based on its technical design decisions, not community validation.

The case against paying for docs SaaS. The tools xyd competes with are expensive once you have a team or serious traffic. Mintlify is $150/mo on the Startup plan and $500/mo on Growth. GitBook charges per user once you’re past public docs. ReadMe.io starts at $99/mo. These aren’t egregious prices for what they deliver, but for a company that’s willing to self-host, paying $150/mo forever for docs tooling is a hard pitch to defend when MIT-licensed alternatives exist [README].

The API-docs angle. Docusaurus is the most-used open-source alternative, but it requires manual work to wire up OpenAPI rendering (via community plugins like docusaurus-plugin-openapi-docs) and has no GraphQL spec generation. xyd ships OpenAPI and GraphQL generation as first-class features alongside SDK generation capabilities — a meaningful difference for API-first products [README][docs].

The theme story. Docusaurus’s default theme is functional but bland, and customizing it deeply is non-trivial. Nextra has two themes. xyd ships six distinct, live-demo’d themes on day one, built on a design system available at components.xyd.dev. For teams that want good-looking docs without hiring a designer, that’s a real advantage [README].

---

Features

Based on the README and documentation:

Core framework:

• CLI with instant dev server, hot module reload, zero config to start [README]
• MDX content authoring (Markdown + React components) [docs]
• Built-in SEO tags, dark mode, code syntax highlighting [website][docs]
• TypeScript support throughout [docs]
• Static output deployable to Netlify, Vercel, or any static host [README]

Themes (six, all live-demoed):

• Solar, Gusto, Poetry, Picasso, Opener, Cosmo — each has a public URL you can preview before choosing [README]

API documentation:

• OpenAPI spec → full reference docs generation [README][docs]
• GraphQL schema → reference docs generation [README][docs]
• SDK generation from API specs (TypeScript, Python, Go mentioned) [docs]
• Live API docs demo at apidocs-demo.xyd.dev [README]

Plugins and integrations:

• Full-text search: Orama (local, free) and Algolia (external, has a free tier) [docs]
• Analytics: LiveSession (native), custom event support [docs]
• A/B testing: GrowthBook and LaunchDarkly [docs]
• Live chat: Intercom, LiveChat, Chatwoot [docs]
• GitHub Stars widget, Supademo embed, edit links [docs]

Content tools:

• React component embedding in MDX [docs]
• Storybook of built-in components at components.xyd.dev [README]
• Compose Content tooling [docs]
• LLM-friendly llms.txt generation for AI contexts [docs]
• Customization at component, icon, font, and custom script level [docs]

What’s notable by its absence: No mention of versioned docs, no multi-language/i18n docs coverage in the README (though SEO and localization-adjacent features appear), no pricing tier for cloud hosting — xyd is self-hosted or deployed to your own static host only.

---

Pricing: SaaS vs self-hosted math

xyd has no SaaS tier. It’s MIT-licensed software you run yourself [README][website].

What you pay:

• xyd itself: $0
• Hosting: $0–5/mo (Netlify free tier covers most docs sites; Vercel free tier also works; one-click deploy buttons exist for both) [README]
• Your own time to set up

What the alternatives charge:

Tool	Free tier	Paid starts at
GitBook	Public docs only	~$6.70/user/mo
Mintlify	Limited	$150/mo (Startup)
ReadMe	Limited	$99/mo
Docusaurus	MIT, free	—
VitePress	MIT, free	—
Starlight	MIT, free	—

For a team already paying $150/mo for Mintlify, switching to xyd self-hosted is straightforward math: you save $1,800/year for as long as you maintain the migration. The question is whether xyd’s stability and maturity justify that migration given its beta status.

One honest caveat: Mintlify and GitBook include hosting, CDN, automatic HTTPS, and managed search. With xyd, you assemble those pieces yourself (Netlify handles most of it, but you’re still managing the pipeline).

---

Deployment reality check

The install path is intentionally simple: bun add -g xyd-js, then xyd in your docs directory [README]. One-click deploy buttons exist for both Netlify and Vercel [README]. There’s also a CodeSandbox playground for zero-install experimentation.

Requirements:

• Node 22.12 or higher (this is above the LTS version many teams are running — Node 20 LTS won’t work) [README]
• Bun as the primary package manager (though npm/yarn may work — the README only shows bun commands)
• A repository for CI/CD deployments

What can go sideways:

The Node 22.12+ requirement will catch teams running older LTS environments. Node 22 only entered LTS in October 2024; many CI pipelines are pinned to Node 18 or 20. You’ll need to update your pipeline or manage version switching before this is a drop-in.

The project is at v0.1.0-beta [docs]. Beta software from a 105-star project means the API surface will change, migration guides may not exist for breaking changes, and community troubleshooting resources (Stack Overflow answers, blog posts, YouTube tutorials) are essentially nonexistent. If you hit a bug, you’re filing a GitHub issue or reading source code.

There are no public uptime reports, no SLA, and no commercial support offering mentioned anywhere. LiveSession is a real company (they built this for their own product), which is better than a solo maintainer vanity project, but it’s not the same as a project with a dedicated documentation team behind it.

Realistic setup time for a technical user following the starter template: 15–30 minutes to a deployed static site. The template and deploy samples exist and the Netlify/Vercel one-click buttons work. For a non-technical team with no developer available: not applicable — this is a developer tool, and there’s no managed path.

---

Pros and Cons

Pros

• MIT license, actually free. No usage limits, no per-seat pricing, no operations-based billing. Fork it, embed it, resell it — the license allows all of it [README].
• First-class OpenAPI + GraphQL generation. Not a plugin bolted on after the fact. API reference generation from specs is a core feature, which is rare among open-source doc frameworks [README][docs].
• SDK generation. Generates client SDKs (TypeScript, Python, Go) from API specs — something you’d normally pay for via dedicated tools [docs].
• Six polished themes with live demos. You can preview each theme before committing, and the design system is documented at components.xyd.dev [README].
• Wide integration surface. A/B testing, analytics, chat, search — baked in rather than left to the user to figure out [README][docs].
• llms.txt generation. Useful for teams building AI-readable documentation surfaces [docs].
• Zero config to start. bun add -g xyd-js + xyd is genuinely the entire quickstart [README].
• Built by a real company for their own production use. LiveSession dogfoods this; it’s not abandonware [website].

Cons

• 105 GitHub stars and beta status. This is the number one risk. You’re adopting a tool that hasn’t been validated beyond its creator. Breaking changes, incomplete features, and missing documentation are expected at this stage [README].
• Node 22.12+ required. A real friction point for teams on Node 18/20 LTS [README].
• Bun-first toolchain. The quickstart assumes bun. Teams on npm/yarn may encounter friction not documented in the README.
• No independent reviews, no community knowledge base. If you hit an edge case, your options are the GitHub issues tracker and reading source code. No blog posts, no Stack Overflow threads, no tutorials exist yet.
• No versioned documentation support mentioned. Mintlify and Docusaurus both handle versioned docs (v1, v2, v3 in the same site). This isn’t mentioned anywhere in xyd’s README or docs navigation.
• No i18n documentation. Internationalization is absent from the feature list and docs navigation, which rules out xyd for globally-facing products needing localized docs.
• Self-hosted only. There’s no managed cloud option. Every team is responsible for their own deployment pipeline, CDN, and uptime.
• Vendor adjacency risk. LiveSession owns the project. Their primary product is analytics. There’s no governance structure, foundation, or community ownership — if LiveSession pivots or shuts down, the project is at risk.

---

Who should use this / who shouldn’t

Use xyd if:

• You’re building developer-facing documentation for an API-first product and need OpenAPI/GraphQL rendering without patching together Docusaurus plugins.
• You want MIT-licensed docs tooling on Netlify/Vercel at zero cost and you have a developer to set it up.
• You’re evaluating early-stage tools and are prepared to accept some instability in exchange for modern features.
• You want a batteries-included integration story (search, analytics, A/B testing, chat) without wiring it up manually.

Skip it (use Docusaurus instead) if:

• You need a stable, community-backed, battle-tested open-source framework. Docusaurus has millions of deploys, years of production use, and Meta behind it.
• You need versioned docs or internationalization.
• Your team isn’t comfortable adopting beta software that could break between minor versions.

Skip it (use Starlight instead) if:

• You want a modern open-source docs framework with strong Astro/Vite performance, active development, and a growing community. Starlight is younger than Docusaurus but far ahead of xyd in adoption.

Skip it (use Mintlify or GitBook instead) if:

• You don’t have a developer to manage deployment and configuration.
• You need SLA guarantees, managed hosting, or enterprise support.
• Your team values polish and support over cost savings.

---

Alternatives worth considering

• Docusaurus — Meta-backed, MIT licensed, the default open-source choice. Most plugins, most community knowledge, most production deployments. Requires plugin work for OpenAPI. Use this unless xyd’s API-first features are specifically what you need.
• Starlight — Astro-based, MIT licensed, growing fast. Clean defaults, good performance, TypeScript-native. No OpenAPI generation out of the box but the ecosystem is active.
• VitePress — Vue-based, MIT licensed, excellent for libraries and SDKs. Simpler scope than xyd but more stable.
• Mintlify — The best SaaS option for API docs if you’re not willing to self-host. Excellent OpenAPI support, managed hosting, good UI. Starts at $150/mo.
• GitBook — Strong for internal/external technical docs, good collaboration features, per-user pricing.
• Nextra — Next.js-based, MIT licensed, good theming. Less API-focused than xyd.
• ReadMe — Established SaaS for API docs, starts at $99/mo, handles OpenAPI well.

For a non-technical founder looking to escape SaaS docs bills: Docusaurus or Starlight are safer choices today. xyd may earn that recommendation in a year if the community grows and beta status resolves.

---

Bottom line

xyd is a technically ambitious MIT-licensed docs framework with a genuinely useful feature set for API-first products: native OpenAPI and GraphQL rendering, SDK generation, six themes with live demos, and a plugin ecosystem that covers search, analytics, A/B testing, and chat in ways that open-source competitors leave to the user. The cost math is obvious — $0/mo versus $150/mo for Mintlify — and the architecture is sound.

The honest caveat is that 105 GitHub stars and v0.1.0-beta aren’t marketing qualifiers; they’re real signals about where this tool sits in its lifecycle. If you’re comfortable being an early adopter, have a developer who can absorb the occasional breaking change, and specifically need the API docs generation features, xyd is worth a serious evaluation. If you need stability and community support today, Docusaurus and Starlight are the safer bets — and both are free.

If you want xyd’s feature set without managing the deployment yourself, upready.dev handles documentation infrastructure setup as a one-time service.

---

Sources

1. xyd GitHub Repository — README, features, quickstart, license. https://github.com/livesession/xyd
2. xyd Official Website — Homepage, feature descriptions, deployment options. https://xyd.dev
3. xyd Documentation — Introduction — Five principles, feature overview, plugin/integration list. https://xyd.dev/docs/guides/introduction
4. xyd API Docs Demo — Live example of OpenAPI documentation output. https://apidocs-demo.xyd.dev/
5. xyd Component Storybook — Built-in component design system reference. https://components.xyd.dev