@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
  styles: 'full',             // how much of the library the stylesheet compiles
  extraStyles: [],            // library sheets compiled after the library
  libraryMajor: undefined,    // override the detected library major
})

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.

styles

How much of the documented library the engine's stylesheet compiles.

• full (the default) compiles all of it. The docs then have every rule up front, which is what a site whose examples are plain markup needs.
• chrome compiles only what the docs chrome itself is built from, plus the utilities and helpers both the chrome and the example markup write. Every other component's CSS has to arrive with the component — from the per-component stylesheets a library ships and its framework bindings import.

coreuiDocs({ styles: 'chrome' })

Under chrome the engine also resolves the library stylesheets it has already compiled (base.css, components/buttons.css, components/nav.css, …) to an empty module, so none of those rules reaches the page twice — a second copy lands wherever the bundler puts it, and inside a cascade layer the later copy wins.

The mode needs a library that ships the layered per-component SCSS; asking for it anywhere else fails the build with a message saying so.

extraStyles

Library stylesheets to compile after the library and before the docs chrome, as paths relative to the library source. Empty by default.

coreuiDocs({ extraStyles: ['scss/legacy'] })

This is the slot for a sheet that has to win over the library's own rules — CoreUI 6's opt-in compatibility classes, say. libraryConfig cannot do it: that file is loaded as configuration, so a sheet forwarded from it lands before the library and loses every tie at equal specificity. The option works the same in both styles modes, and a path the library does not carry fails the build.

libraryMajor

The documented library's major. It decides the button spelling the chrome writes: CoreUI 6 replaced .btn.btn-primary / .btn.btn-outline-primary with .btn-solid.theme-primary / .btn-outline.theme-primary and moved the old names into an opt-in legacy stylesheet, so chrome written in one spelling renders unstyled on the other major.

The engine reads it from the library's package.json, and treats a library that ships the per-component SCSS split as 6 regardless — the next major is developed on a branch that still carries the previous version number. Set the option to override both.

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

Publishing a version

A docs site lives at seo.url (https://coreui.io/react/docs). An archived version lives one segment below it, and version is that segment:

# src/data/config.yml
version: "6.0"
seo:
  url: https://coreui.io/react/docs

builds for https://coreui.io/react/docs/6.0/ — base, the root redirect, the canonical of every page, the sitemap and llms.txt all follow. Leave version out for the current docs. COREUI_DOCS_VERSION in the environment overrides the config value, so one checkout builds both without an edit:

COREUI_DOCS_VERSION=6.0 npm run build

Every page carries <meta name="docsearch:version"> — the version, or latest for the current docs — so one Algolia index can hold several versions side by side. Once the crawler extracts that meta into a version attribute and the index declares it in attributesForFaceting, set search.filterByVersion: true and the search on each site returns only its own version. Off by default: with the facet missing from the index, the filter would return nothing.

MDX components

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

<UtilityDocs name="float" /> documents one entry of a library's utilities.json as it is written in the file. table adds the classes it generates — class, declarations, and a line naming the responsive and print variants instead of repeating every breakpoint; it is off by default because the utilities pages already open with that table. The classes come from the library's own generator (its ./utilities entry point), so $refs, $scale, $tokens, $theme, $merge and $opacity show what the stylesheet writes (var(--cui-spacer-3), color-mix(…)) rather than a second reading of the same rules. json={false} renders the table alone.

The generator arrived in CoreUI 6; on an older library the component fails the build with a message pointing at <ScssDocs file="scss/_utilities.scss" capture="…" />, which is how utilities are documented there.

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