Skip to content
Kushajveer Singh Sooch

Starlight

Markdown frontmatter

Doc link.

1
title: top of page, browser tab, page metadata
2
description: page metadata, social media previews
3


4
slug: my-custom-slug/some/thing # use this in sidebar config as well
5
draft: false # not included in production build and autogenerated link groups
6


7
# Specify all <head> tags here
8
head:
9
  - tag: title
10
    content: Custom about title
11


12
sidebar:
13
  label: Taken from "title"
14
  order: Lower numbers displayed higher
15
  hidden: false # do not include the page in autogenerated sidebar
16
  badge:
17
    text: Experimental
18
    variant: caution
19
  attrs: # HTML attributes to add to page link i.e. <a> tag
20
    target: _blank # to open in new tab
21


22
editUrl: false  # to disable "Edit page" link
23
tableOfContents: false # Disable table of contents
24
tableOfContents:
25
  minHeadingLevel: 2
26
  maxHeadingLevel: 3
27
template: doc | splash # "splash" uses no sidebar and table of contents
28
lastUpdated: false # or provide date lke "2022-08-09"
29
prev: false
30
next: false

Markdown

  • **bold**- bold
  • _italic* - italic
  • ~~strikethrough~~ - strikethrough
  • [link to home page](../../) - link to homepage
  • ![image-alt-text](../../assets/profile.jpeg) - image-alt-text
  • [link to markdown headings](#markdown) - link to markdown headings

Table

1
| Syntax    | Description |
2
| --------- | ----------- |
3
| Header    | Title       |
4
| Paragraph | Text        |
SyntaxDescription
HeaderTitle
ParagraphText

Blockquote

Blockquote used when quoting other people.

Use ’>’ at the start of line.

Footnote

Here’s a sentence with a footnote. 1

Definition List

1
<dl>
2
  <dt>Second Term</dt>
3
  <dd>This is one definition of the second term. </dd>
4
  <dd>This is another definition of the second term.</dd>
5
</dl>
First Term
This is one definition of the second term.
This is another definition of the second term.

Task list

  • Write the press release
  • Update the website
  • Contact the media

Starlight Components

Asides/Admonitions/Callouts

Details/Accordion

Use to hide content that is not immediately relevant. Users can click > to see the details.

1
<details>
2
  <summary>Use standard HTML detail, summary tag.</summary>
3
  Here is more detailed information about this.
4
</details>
Use standard HTML detail, summary tag. Here is more detailed information about this.

Code Blocks

Expressive Code rehype plugin used for this.

Shiki

Shiki used for syntax highlighting.

List of all supported languages.

title/frame

  • Terminal window - Provide title with file name to create terminal like window.

    1
    ```js title="test.js"
    2
    console.log('Create a terminal window for the codeblock');
    3
    ```
    test.js
    1
    console.log('Create a terminal window for the codeblock');

  • Code editor window - For title without a file name, the code editor window would be created.

    1
    ```powershell title="PowerShell terminal example"
    2
    Write-Output "This one has a title!"
    3
    ```
    PowerShell terminal example
    1
    Write-Output "This one has a title!"

  • Control the frame type by providing frame argument (code, terminal, none, auto).

    1
    ```sh title="Something" frame="none"
    2
    echo "How are you doing?"
    3
    ```
    1
    echo "How are you doing?"

Text and Line markers

  • Mark lines for highlighting

    • {4} - single line
    • {4, 8, 10} - three lines
    • {4-8} - range of lines
    1
    ```js {1, 4, 7-8}
    2
    // Line 1 - targeted by line number
    3
    // Line 2
    4
    // Line 3
    5
    // Line 4 - targeted by line number
    6
    // Line 5
    7
    // Line 6
    8
    // Line 7 - targeted by range "7-8"
    9
    // Line 8 - targeted by range "7-8"
    10
    ```
    1
    // Line 1 - targeted by line number
    2
    // Line 2
    3
    // Line 3
    4
    // Line 4 - targeted by line number
    5
    // Line 5
    6
    // Line 6
    7
    // Line 7 - targeted by range "7-8"
    8
    // Line 8 - targeted by range "7-8"

  • Type of markers

    • mark - default
    • ins
    • del
    1
    ```js title="Line markers" del={2} ins={3-4} {6}
    2
    // Line 1 - targeted by line number
    3
    // Line 2
    4
    // Line 3
    5
    // Line 4 - targeted by line number
    6
    // Line 5
    7
    // Line 6
    8
    // Line 7 - targeted by range "7-8"
    9
    // Line 8 - targeted by range "7-8"
    10
    ```
    Line markers
    1
    // Line 1 - targeted by line number
    2
    // Line 2
    3
    // Line 3
    4
    // Line 4 - targeted by line number
    5
    // Line 5
    6
    // Line 6
    7
    // Line 7 - targeted by range "7-8"
    8
    // Line 8 - targeted by range "7-8"

  • Add single character labels to side of line markers to help with referencing specific parts of code.

    labeled-line-markers.jsx
    1
    ```jsx {"1":5} del={"2":7-8} ins={"3":10-12}
    2
    <button
    3
        role='button'
    4
        {...props}
    5
        value={value}
    6
        className={buttonClassName}
    7
        disabled={disabled}
    8
        active={active}
    9
    >
    10
        {children &&
    11
            !active &&
    12
            (typeof children === 'string' ? <span>{children}</span> : children)}
    13
    </button>
    14
    ```
    labeled-line-markers.jsx
    1
    <button
    2
        role='button'
    3
        {...props}
    4
        value={value}
    5
        className={buttonClassName}
    6
        disabled={disabled}
    7
        active={active}
    8
    >
    9
        {children &&
    10
            !active &&
    11
            (typeof children === 'string' ? <span>{children}</span> : children)}
    12
    </button>

  • Add long labels on separate lines. For this, leave an empty line above the marked line range.

    labeled-line-markers.jsx
    1
    <!-- prettier-ignore -->
    2
    ```jsx {"1. Provide the value prop here:":5-6} del={"2. Remove the disabled and active states:":8-10} ins={"3. Add this to render the children inside the button:":12-15}
    3
    <button
    4
        role='button'
    5
        {...props}
    6
    

    7
        value={value}
    8
        className={buttonClassName}
    9
    

    10
        disabled={disabled}
    11
        active={active}
    12
    >
    13
    

    14
        {children &&
    15
            !active &&
    16
            (typeof children === 'string' ? <span>{children}</span> : children)}
    17
    </button>
    18
    ```
    labeled-line-markers.jsx
    1
    <button
    2
        role='button'
    3
        {...props}
    4
    

    5
        value={value}
    6
        className={buttonClassName}
    7
    

    8
        disabled={disabled}
    9
        active={active}
    10
    >
    11
    

    12
        {children &&
    13
            !active &&
    14
            (typeof children === 'string' ? <span>{children}</span> : children)}
    15
    </button>

  • Use GitHub diff syntax. Add +, - to mark lines that are inserted and deleted.

    For syntax highlighting, provide the language using lang="js".

    1
    ```diff lang="js"
    2
    function thisIsJavaScript() {
    3
        // This entire block gets highlighted as JavaScript,
    4
        // and we can still add diff markers to it!
    5
    -   console.log('Old code to be removed')
    6
    +   console.log('New and shiny code!')
    7
    }
    8
    ```
    1
    function thisIsJavaScript() {
    2
        // This entire block gets highlighted as JavaScript,
    3
        // and we can still add diff markers to it!
    4
       console.log('Old code to be removed')
    5
       console.log('New and shiny code!')
    6
    }

  • Mark text or regular expression in the code block.

    1
    ```js "return /true|false/;" ins="inserted" del="deleted"
    2
    function demo() {
    3
    console.log('These are inserted and deleted marker types');
    4
    // The return statement uses the default marker type
    5
    return true;
    6
    return false;
    7
    }
    8
    ```
    1
    function demo() {
    2
        console.log('These are inserted and deleted marker types');
    3
        // The return statement uses the default marker type
    4
        return true;
    5
        return false;
    6
    }

Wrap lines

Add wrap or wrap=true to wrap code block and prevent horizontal scrolling.

By default, the wrapped line will start at the same indentation as the original line.

To wrap lines to the start i.e. column 1, add preserveIndent=false. This is useful to reproduce terminal output.

1
```js wrap
2
// Example with wrap
3
function getLongString() {
4
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
5
}
1
// Example with wrap
2
function getLongString() {
3
    return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide';
4
}

Example, with wrapped line starting from column 1

1
```js wrap preserveIndent=false
2
// Example with preserveIndent=false
3
function getLongString() {
4
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
5
}
6
```
1
// Example with preserveIndent=false
2
function getLongString() {
3
    return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide';
4
}

Collapsible sections

Collapse the provided line number ranges. This helps reduce long code examples to relevant parts.

1
```js collapse={1-5, 12-14}
2
// All this boilerplate setup code will be collapsed
3
import { someBoilerplateEngine } from '@example/some-boilerplate'
4
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
5


6
const engine = someBoilerplateEngine(evenMoreBoilerplate())
7


8
// This part of the code will be visible by default
9
engine.doSomething(1, 2, 3, calcFn)
10


11
function calcFn() {
12
  // You can have multiple collapsed sections
13
  const a = 1
14
  const b = 2
15
  return a + b
16
}
17
```
5 collapsed lines
1
// All this boilerplate setup code will be collapsed
2
import { someBoilerplateEngine } from '@example/some-boilerplate';
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate';
4


5
const engine = someBoilerplateEngine(evenMoreBoilerplate());
6


7
// This part of the code will be visible by default
8
engine.doSomething(1, 2, 3, calcFn);
9


10
function calcFn() {
11
    // You can have multiple collapsed sections
3 collapsed lines
12
    const a = 1;
13
    const b = 2;
14
    return a + b;
15
}

Line numbers

  • showLineNumbers=false - to hide
  • startLineNumbers=5
1
```js startLineNumber=5
2
console.log('Greetings from line 5!');
3
console.log('I am on line 6');
4
```
5
console.log('Greetings from line 5!');
6
console.log('I am on line 6');

Custom theme

Instruction to create personal theme.

PageFind is used.

Add pagefind: false in markdown frontmatter to exclude page from search index.

Exclude parts of the page using

1
<div data-pagefind-ignore>
2
This text will be hidden from search.
3
</div>

Docs link.

Internal links to pages need to be relative to src/content/docs with slug property.

1
starlight({
2
  sidebar: [
3
    { slug: 'constellations/andromeda' },
4
    { slug: 'constellations/orion' },
5
  ],
6
});

Or the shorthand without slug

1
starlight({
2
    sidebar: ['constellations/andromeda', 'constellations/orion'],
3
});

For internal links, it is better to provide label info from the frontmatter.

1
starlight({
2
  sidebar: [
3
  // A link to a non-docs page on this site.
4
  { label: 'Meteor Store', link: '/shop/' },
5
  // An external link to the NASA website.
6
  { label: 'NASA', link: 'https://www.nasa.gov/' },
7
],
8
});

Groups

Collapse by providing collapsed: true.

1
starlight({
2
  sidebar: [
3
    // A group of links labelled "Constellations".
4
    {
5
      label: 'Constellations',
6
      items: [
7
        'constellations/carina',
8
        // A nested group of links for seasonal constellations.
9
        {
10
          label: 'Seasonal',
11
          items: [
12
            'constellations/andromeda',
13
          ],
14
        },
15
      ],
16
    },
17
  ],
18
});

Autogenerate groups

The collapsed value of parent is used, if none is provided.

1
starlight({
2
  sidebar: [
3
    {
4
      label: 'Constellations',
5
      // Autogenerate a group of links for the 'constellations' directory.
6
      autogenerate: { directory: 'constellations' },
7
    },
8
  ],
9
});

Badges

Display a small badge next to sidebar label. This can convey information like “New”, “Outdated”.

Use the following variants note, tip, danger, caution, success.

1
sidebar:
2
  label: Custom sidebar label
3
  order: 2
4
  badge:
5
    text: New
6
    variant: tip

Footnotes

  1. This is the footnote. ↩