Starlight, Universalized

Starlight builds great docs sites, but it only works with Astro. This project breaks that coupling.

All of Starlight's UI components are rebuilt with Mitosis so they compile natively to Qwik, React, Solid, Vue, Angular, and others. The "point a folder of Markdown at a framework and get a docs site" workflow is preserved, with one addition: you can mount multiple content directories at different URL prefixes.

content: merge(
  withPrefix('sdk', collection({ directory: 'content/sdk' })),
  withPrefix('api', collection({ directory: 'content/api' })),
)

Helpful when you have several products sharing one site.

Examples

• examples/basics -- minimal setup
• examples/kitchen-sink -- full demo

Getting Started

Qwik-docs plugs into an existing Qwik City app. If you don't have one yet, scaffold one — pick the empty starter:

npm create qwik@latest empty my-docs && cd my-docs && npm install

The @qwik-docs packages live on the Comrades registry, so point npm at it from your project's .npmrc:

@qwik-docs:registry=https://peoplesgrocers.com/code/api/packages/comrades/npm/

Then install:

npm install @qwik-docs/framework@0.0.1 @qwik-docs/components@0.0.1

Register the Vite plugin:

// vite.config.ts
import { qwikDocs } from '@qwik-docs/framework';
// ...add to plugins, after qwikCity() and qwikVite():
qwikDocs({ configPath: './qwik-docs.config.ts' })

Create qwik-docs.config.ts at the project root — this is the one config file the plugin reads:

import { defineConfig, collection, withPrefix, merge } from '@qwik-docs/framework';

export default defineConfig({
  title: 'My Docs',
  // Public URL of the deployed site. Optional, but required for the
  // "Chat in Claude.ai" action below (used to build the absolute .md link).
  site: 'https://docs.example.com',
  // Turns on the "Copy page" split button beside each page title. It copies
  // the page's raw Markdown to the clipboard, offers "Open Markdown" (the
  // page's .md source, served by the plugin), and — when `site` is set —
  // a "Chat in Claude.ai" action seeded with that page. Off by default;
  // override per page with `features: { copy-page: false }` in frontmatter.
  features: {
    copyPage: true,
  },
  content: merge(
    withPrefix('docs/guides',    collection({ directory: 'content/guides' })),
    withPrefix('docs/reference', collection({ directory: 'content/reference' })),
  ),
  social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/you/repo' }],
  sidebar: [
    { label: 'Guides',    items: [{ label: 'Example', link: '/docs/guides/example/' }] },
    { label: 'Reference', autogenerate: { directory: 'docs/reference' } },
  ],
});

Add two routes — a landing page at src/routes/index.tsx and a catch-all at src/routes/docs/[...slug]/index.tsx. Both wrap content in DocsProvider + Page from @qwik-docs/framework/components. The catch-all uses loadPage, getSidebar, and generateToc from @qwik-docs/framework and renders MDX via entries[slug].load(). Copy examples/basics/src/routes for working versions.

Declare the plugin's virtual modules in src/virtual.d.ts:

declare module 'virtual:qwik-docs/content' {
  import type { ContentEntryMap } from '@qwik-docs/framework';
  export const entries: ContentEntryMap;
  export const slugs: string[];
}
declare module 'virtual:qwik-docs/config' {
  import type { QwikDocsConfig } from '@qwik-docs/framework';
  const config: Omit<QwikDocsConfig, 'content'>;
  export default config;
}

Drop .mdx files into the directories named in content: (each needs a title and description frontmatter), then npm run dev. For a fuller starting point, copy examples/basics.

License

AGPL-3.0 -- or $10/year for a permissive license. Based on Starlight by the Astro team.