DOCSEARCHbyAlgolia
Submit Docs

Starlight Documentation Framework

repository·main·Indexed 11 days ago

https://github.com/withastro/starlight

A documentation framework built for Astro designed to help developers quickly build and deploy content-rich documentation sites. It includes support for Markdoc via @astrojs/starlight-markdoc, Tailwind CSS integration via @astrojs/starlight-tailwind, and Algolia DocSearch via @astrojs/starlight-docsearch.

Tokens
71.6K
Snippets
260
Records
328
Agent score
92%

What's inside Starlight

  2. Understand the Starlight project structure

    main

    Starlight projects follow the standard Astro project structure. Key directories and files include:

    • astro.config.mjs: The main Astro configuration file where you include and configure the Starlight integration.
    • src/content.config.ts: The content collections configuration file. This is where you add Starlight's frontmatter schemas to your project to ensure type safety for your documentation.
    • src/content/docs/: The primary directory for your documentation. Starlight automatically converts every .md, .mdx, or .mdoc file found in this directory into a page on your website.
    • src/content/i18n/ (optional): Contains translation data used for internationalization (i18n) support.
    • src/: Contains your project's source code, such as custom Astro components, styles, and images.
    • public/: Stores static assets (like fonts, favicons, or PDFs) that should be served directly without being processed by Astro.
    - public/
  - favicon.svg
- src/
  - assets/
    - logo.svg
    - screenshot.jpg
  - components/
    - CustomButton.astro
    - InteractiveWidget.jsx
  - content/
    - docs/
      - guides/
        - 01-getting-started.md
        - 02-advanced.md
      - index.mdx
  - content.config.ts
- astro.config.mjs
- package.json
- tsconfig.json

  3. Extend Starlight with plugins and integrations

    main

    Starlight can be customized using plugins that modify its configuration, UI, and behavior. These extensions are categorized into official plugins maintained by the Starlight team and community plugins maintained by users.

    Official Plugins

    • Algolia DocSearch: Replaces the default Pagefind search provider with Algolia DocSearch.

    Community Plugins

    There is a wide variety of community-maintained plugins for tasks such as:

    • Content Generation: starlight-typedoc (TypeScript to Starlight), starlight-openapi (OpenAPI/Swagger to Starlight), starlight-obsidian (Obsidian vaults).
    • Site Features: starlight-blog (add a blog), starlight-versions (versioning), starlight-giscus (comments), starlight-announcement (banners).
    • UI Enhancements: starlight-image-zoom (image zoom), starlight-kbd (keyboard shortcuts), starlight-plugin-icons (sidebar/codeblock icons), starlight-scroll-to-top (scroll button).
    • Developer Tools: starlight-links-validator (broken link checking), starlight-llms-txt (llms.txt support), starlight-md-txt (raw Markdown URLs).

  4. Explore community tools and integrations for Starlight

    main

    You can extend Starlight's functionality using various community-maintained tools, plugins, and integrations. These range from VS Code extensions for better authoring to CLI tools for content conversion and specialized components for rendering diagrams or interactive code blocks.

    Categories of Community Tools

    • Content Conversion & Management: Tools like notion-to-astro (Notion to Starlight) and contentisland-cli (Headless CMS sync).
    • Diagramming & Rendering: Support for PlantUML, Mermaid, and D2 diagrams, as well as astro-live-code for interactive MDX blocks.
    • VS Code Extensions: Enhancements for translation (starlight-i18n) and link IntelliSense (starlight-links).
    • UI Components: Specialized components like starlight-showcases for showcase pages, starlight-contributor-list for project contributors, and starlight-save-file-component for download links.
    • Site Utilities: CLI tools like starlight-to-pdf for PDF generation and sidebar enhancements like starlight-sidebar-topics-dropdown.
    • Development Tools: Scaffolding tools like @hideoo/starlight-plugin and local-first editors like Axiom Studio for Starlight for managing Markdown/MDX and frontmatter.

  5. What is a Starlight theme?

    main

    A theme in Starlight is a plugin that modifies the visual appearance of your documentation site. Themes can achieve customization through several methods:

    • Custom CSS: Applying unique styles to elements.
    • Component Overrides: Replacing default Starlight components with custom ones.
    • New Features: Adding entirely new functional capabilities to the site.

    You can use community-built themes to quickly change the look and feel of your site without writing custom styles from scratch.

  6. Project structure for Starlight with Markdoc

    main

    A standard Starlight project using Markdoc follows this directory structure:

    • src/content/docs/: The primary location for documentation. Starlight automatically exposes .md, .mdx, or .mdoc files found here as routes based on their filenames.
    • src/assets/: Place images here to embed them in your Markdown files using relative links.
    • public/: For static assets that should be served as-is (e.g., favicons).
    • astro.config.mjs: The main Astro configuration file.
    • markdoc.config.mjs: The configuration file for Markdoc settings.
    .
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   └── content.config.ts
├── astro.config.mjs
├── markdoc.config.mjs
├── package.json
└── tsconfig.json

  7. Configure fallback content for untranslated pages

    main

    Starlight provides automatic fallback content. If a page has not been translated into a specific language, Starlight will display the content from the defaultLocale instead.

    For example, if your defaultLocale is en and a user visits /fr/about, but src/content/docs/fr/about.md does not exist, Starlight will show the content from src/content/docs/en/about.md along with a notice that the page has not yet been translated.

  8. Structure page content and headings

    main

    Starlight automatically uses your frontmatter title as the top-level <h1> and includes an "Overview" heading in the table of contents.

    Best Practice: Start pages with regular paragraph text and use headings from <h2> (##) and below for on-page structure.

    • <h2> and <h3> headings automatically appear in the page's table of contents.
    • Headings automatically generate anchor links for direct linking (e.g., [My Section](#my-section)).
    ---
title: Markdown Guide
---

This page describes how to use Markdown in Starlight.

## Inline Styles

## Headings

  11. How Starlight hooks work

    main

    Hooks are functions that Starlight calls at specific lifecycle stages to allow plugins to execute code. To ensure type safety when writing hooks, use the HookParameters utility type from @astrojs/starlight/types and pass the name of the hook as a key.

    Example of typing hook arguments:

    import type { HookParameters } from '@astrojs/starlight/types';

function configSetup(options: HookParameters['config:setup']) {
  options.useTranslations('en');
}
    import type { HookParameters } from '@astrojs/starlight/types';

function configSetup(options: HookParameters['config:setup']) {
  options.useTranslations('en');
}

  12. How cascade layers work in Starlight

    main

    Starlight uses CSS cascade layers internally to manage style precedence. Any unlayered CSS you provide will override Starlight's default styles by default.

    If you want to use cascade layers in your custom CSS to control precedence relative to Starlight, use the @layer directive. You can define a custom order where layers are applied before, after, or between Starlight's internal layers.

    /* src/styles/custom.css */
/* my-reset runs before starlight, my-overrides runs after */
@layer my-reset, starlight, my-overrides;