Starlight

Starlight is a full-featured documentation theme built on top of the Astro framework.

Installation

In the root of the project create new project with wizard via command below:

npm create astro@latest -- --template starlight

Project name should be docs, install dependecies Yes, use TypeScript Yes, mode strict and init Git No.

Writing documentation

For writing documentation you have multiple options: md, mdx, mdoc and components. For most use cases Markdown is all you will ever need. The only new thing for some of you will be the use of Frontmatter that is used to define metadata such as a title, sidebar order and label.

Adding new docs

Documentation lives inside src/content/docs/. There you can add folders and files. Starlight turns each .md, .mdx or .mdoc file in this directory into a page automatically. For additional info check official Starlight docs.

Sidebar

Sidebar is defined inside astro.config.mjs. You can customize it or leave it on default - this will automatically generate all pages (and subpages) based on directory structure. For more info check official Starlight docs.

How to deploy to Gitlab pages

This process is nicely documented on Astro’s website. In short there are 3 steps:

1. Rename public/ to static.
2. Update astro.config.mjs file with site, base, outDir, publicDir params. You can find an example in source code of dev docs repo.
3. Add .gitlab-ci.yml in the root of your project with:

pages:
  # The Docker image that will be used to build your app
  image: node:lts
  before_script:
    - cd docs
    - npm ci

  script:
    # Specify the steps involved to build your app here
    - npm run build

  artifacts:
    paths:
      # The folder that contains the built files to be published.
      # This must be called "public".
      - public

  only:
    # Trigger a new build and deploy only when there is a push to the
    # branch(es) below
    - main

Customization

Following the Starlight docs you can add logo, update social links in navbar and much more.

Styling

You can also update documentation theme.

Landing page

You can also update landing page. After you create new Starlight project you will have src/content/docs/index.mdx with default landing page. You may change it as needed.