Plugin API

Import

import lucode from 'lucode-starlight';

Use the default export inside Starlight’s plugins array:

starlight({
  plugins: [lucode()],
});

LucodeStarlightUserConfig

type LucodeStarlightUserConfig = {
  navLinks?: Link[];
  footerText?: string | Record<string, string>;
};

navLinks

Header navigation links rendered by the theme.

type Link = {
  link: string;
  badge?: string;
  translations?: Record<string, string>;
  label: string | Record<string, string>;
  attrs?: Record<string, string | number | boolean | undefined>;
};

lucode({
  navLinks: [
    {
      label: 'Docs',
      link: '/guides/getting-started/',
      translations: {
        es: 'Documentación',
      },
    },
    {
      link: '/reference/plugin-api/',
      label: {
        en: 'API',
        es: 'API',
      },
    },
    {
      label: 'GitHub',
      attrs: { target: '_blank', rel: 'noreferrer' },
      link: 'https://github.com/lucas-labs/lucode-starlight-theme',
    },
  ],
});

Prefer Starlight sidebar style (label string + translations) or a locale map on label. Keys may be BCP-47 tags (en, es) or locale paths; Lucode tries both.

footerText

Markdown rendered in the footer text slot. Accepts a string or a locale map (same shape as Starlight’s title).

lucode({
  footerText: {
    es: 'Hecho con [Lucode Starlight](https://github.com/lucas-labs/lucode-starlight-theme).',
    en: 'Built with [Lucode Starlight](https://github.com/lucas-labs/lucode-starlight-theme).',
  },
});

If omitted, the theme uses its built-in credit line. When using the object form, include a key for your default language.

Frontmatter Extension

Import ExtendDocsSchema from lucode-starlight/schema and pass it to Starlight’s docsSchema().

import { ExtendDocsSchema } from 'lucode-starlight/schema';

schema: docsSchema({ extend: ExtendDocsSchema });

The extension adds:

type LucodeDocsFrontmatter = {
  links?: {
    doc?: string;
    api?: string;
  };
  hero?: {
    layout?: 'centered' | 'centered-top' | 'split-left' | 'split-right' | 'banner';
    announcement?: {
      text: string;
      link: string;
    };
  };
};

hero.layout defaults to centered.

Package Exports

import lucode from 'lucode-starlight';
import { ExtendDocsSchema } from 'lucode-starlight/schema';
import { ContainerSection, LinkButton } from 'lucode-starlight/components';

The package also exports the internal Starlight override components and CSS files for advanced composition:

• lucode-starlight/styles/layers
• lucode-starlight/styles/theme
• lucode-starlight/styles/base
• lucode-starlight/components/overrides/Header.astro
• lucode-starlight/components/overrides/Hero.astro
• lucode-starlight/components/overrides/Footer.astro

Prefer the plugin for normal sites. Reach for direct exports only when you are building a custom integration or intentionally composing with one of the theme overrides.