@coreui/astro-docs

Shared Astro docs engine that powers the documentation sites for the CoreUI component libraries — free and Pro, across every framework (vanilla JS, React, Vue, Angular). It ships the layout, navigation, search, MDX shortcodes (Example, Callout, Api, …) and the build-time integration that renders runnable examples straight from your library source.

Installation

npm install @coreui/astro-docs

Requires Astro ^6.4 (declared as a peer dependency). The consumer project also needs the matching base library, which the engine reads the SCSS source from:

• free editions → @coreui/coreui
• Pro editions → @coreui/coreui-pro

Usage

Add the integration to astro.config.mjs. Place coreuiDocs() before @astrojs/mdx, and spread it (it returns an array of integrations):

import { defineConfig } from 'astro/config'
import mdx from '@astrojs/mdx'
import { coreuiDocs } from '@coreui/astro-docs/integration'

export default defineConfig({
  integrations: [...coreuiDocs(), mdx()],
})

For React or Vue docs, add that framework's renderer too (@astrojs/react / @astrojs/vue) so example islands hydrate.

coreuiDocs() also handles the Vite side of the docs chrome for you (it pre-bundles the sandbox client's lz-string / @stackblitz/sdk deps in dev), so wiring it directly — as every CoreUI docs project does — is the supported path.

Edition detection

The engine auto-detects the edition from the consumer's dependencies: if @coreui/coreui-pro is present it builds the Pro docs, otherwise the free ones. The base SCSS is resolved from node_modules/@coreui/<edition> (or a sibling <edition>/ source directory in a monorepo).

Options

coreuiDocs({
  data: 'src/data',           // sidebar.yml, config.yml, logo.svg
  sandbox: 'src/sandbox.ts',  // per-framework StackBlitz `buildProject`
  config: undefined,          // path to the library config.yml ([[config:…]])
  libraryConfig: undefined,   // Sass partial configuring the documented library
})

libraryConfig

The docs build compiles the library from source, so it has to configure it — deprecation messages off, the CSS Grid on, and whatever else a page needs to demonstrate. That configuration is the library's business, not the engine's, and it moves between majors: a flag that has to be switched on in one is dead weight in the next, and @use ... with () is a hard Sass error on a variable the module no longer declares. Pinning it in the engine would mean no library major can ever drop a flag the engine names.

The default is styles/_library-config.scss. Point libraryConfig at a partial of your own to replace it — a path relative to the docs project root:

// src/styles/_library-config.scss
@forward '@coreui-docs-source/scss/variables' with (
  $enable-deprecation-messages: false
);

coreuiDocs({ libraryConfig: 'src/styles/_library-config.scss' })

It must forward the library's variables entry, and it is loaded before anything else touches it — a @forward ... with () only configures a module the first time it is loaded.

The publish URL is config-driven: coreuiDocs() reads seo.url from <data>/config.yml and derives Astro's site + base from it.

MDX components

These are auto-imported into every .mdx page (no import needed): Example, Code, Callout, AddedIn, DeprecatedIn, ScssDocs, JSXDocs, Api.

Injected routes & AI artefacts

coreuiDocs() prerenders a set of routes on every docs site, for readers and for LLM / AI agents:

• llms.txt — an llmstxt.org index of every page.
• llms-full.txt — the whole documentation as a single Markdown file.
• <slug>.md — a clean Markdown view of each page (linked from the page chrome).
• api.json — every component's generated API (props / events / slots), keyed by component name, from src/api/*.api.json (see @coreui/astro-docs-api-generator).
• a 404 page, sitemap.xml and robots.txt.

A build-time broken-link check runs over the internal links and fails the build on any broken link.

License

MIT © CoreUI