Astro Starlight

Overview Create an Astro Starlight documentation website and publish it on Github.

About Jamstack websites

The website you are viewing is a 1) JAMstack site, 2) generated using 3) Astro 4) Starlight.

1. JAMstack sites are static websites (HTML/CSS/JS) generated from dynamic content. When you publish a markdown file to Github and it transforms it into a webpage you are making a JAMstack site. JAM stands for Javascript + APIs + markup used to create the static website.
2. A Static Site Generator (SSG) is a tool that creates a static site using plain text files (usually Markdown .md or .mdx) and a collection of templates.
3. Astro is a Javascript framework capable of generating static (or dynamic) websites. You add content using markdown and Astro manages all the organization, building (creating HTML from MD files using templates), and publishing.
4. Starlight is a documentation theme for Astro, adding templates, and components for navigation, search, and other features.

JAMstack benefits

1. The frontend is static, so it displays information without latency.
2. With no backend, the site runs faster, has better security, and hosting is cheap (even free).
3. The site can scale easily and traffic static content can be offloaded to a CDN.

Use Astro.js on its own!

Astro is popular and flexible as you can see in their showcase. Explore Astro on its own through their docs or this tutorial What Is Astro? An Introduction to the Popular Static Site Generator.

Example Astro Starlight websites

• The Starlight documentation website https://starlight.astro.build/
• The Starlight site showcase https://starlight.astro.build/resources/showcase/
• Critical Web Design Wiki https://github.com/criticalwebdesign/wiki
• The Pokémon Database https://pokemon-siace.netlify.app/
• Pydocs https://www.pydocs.site/en
• Font Awesome Docs https://docs.fontawesome.com/

Watch an introduction to Astro

Astro - The Ultimate Web Framework

Tutorial

Overview Read on to install, configure, and publish an Astro website.

Instructions for creating a Starlight site from scratch

Caution

These instructions show how to create a Starlight site from scratch. DIG 345 students are advised to use a fork of the DevLog instead.

Create an Astro Starlight site

Follow these steps from Starlight’s Getting Started tutorial

1. Create new folder named astro-test inside ~/Documents/Github/
2. Drag the folder into VS Code in the dock (Mac) to open the project.
3. Run the following in a VS Code Terminal to start the installation

npm create astro@latest -- --template starlight

4. Where should we create your new project? ./
5. Install dependencies? Yes
6. Initialize a new git repository? Yes
7. Once finished, run the development server then find your new site at: http://localhost:4321

npm run dev

Update project structure

1. Make a new folder called schedule in /src/content/docs/
2. Add a new file called devlog-1-3.mdx inside /src/content/docs/schedule/
3. To the top add a “frontmatter” section:

---
title: DevLog 1-2
description: DevLog page
---

4. Below the frontmatter in devlog-1-3.mdx add this outline:

## Outcomes

1. Paste the code from the list ...
1. ... of outcomes from the course schedule ...
1. ... and update content where noted.



## Context

What ideas resonated with you?

- Citation: Author, Article (year)
- Summary:
- Quote:
- Comment:
- Question:



## Tech

What tech did you learn?

- Summary:
- Alternatives: "An alternative to this method is ______"
- Link(s) to outcomes:
- Comments:
- Questions:

5. In VS Code, open astro.config.mjs
6. Set title to DevLog
7. Add { label: 'Schedule', autogenerate: { directory: 'schedule' }, }, into the sidebar property

export default defineConfig({
  integrations: [
    starlight({
      title: 'DevLog',
      ...
      sidebar: [
        { label: 'Schedule', autogenerate: { directory: 'schedule' }, },
      ],
    }),
  ],
})

8. Add a .gitignore file to the main directory with the following

# build output
dist/
# generated types
.astro/

# dependencies
node_modules/

# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*


# environment variables
.env
.env.production

# macOS-specific files
.DS_Store

Fork an Astro Starlight site

1. Fork this repo into your own account https://github.com/omundy/dig345-devlog
2. Clone the new repo to your computer. (i.e. Green button > Open in Github Desktop)
3. Open the project in VS Code.
4. In the terminal, install dependencies using npm install
5. Run the development server with npm run dev and find your new site at: http://localhost:4321

Review Project structure

Inside your intial Astro + Starlight project, you’ll see the following folders and files:

• .gitignore
• Directorypublic/ Static files

  • …
• Directorysrc/ All files in here will be processed by Astro

  • Directoryassets/ Static files processed by Astro

    • …
  • Directorycontent/ In a regular Astro site these become routes

    • Directorydocs/

      • Directorycontents/ Folders/Files here become sections/pages in your site

        • …
    • index.mdx Site home page
• astro.config.mjs Astro Starlight config file
• package.json Meta information and project dependencies

• Starlight publishes .md and .mdx files in /src/content/docs/ to the web using directory/filename (e.g. guides/example)
• /src/assets/- Place images here then embed them in Markdown with a relative link.
• public/ - This directory is for static assets, like favicons.
• astro.config.mjs - The Astro config file
• package.json - This file contains your project dependencies as well as a list of commands for installing dependencies, starting, building, and testing Astro.

Publish Astro Starlight using Github Actions

1. In Github Desktop, commit your work and push it to a new repository on Github. Leave it public.
2. Open the repo web page Github Desktop > Repository > View on Github. Click Settings > Pages. Choose GitHub Actions as the Source of your site.
3. In VS Code, open astro.config.mjs
   1. Set site to the github.io URL for your username. For example my username is omundy
   2. Set base to the name of your repo. For example my repo is dig345-devlog

export default defineConfig({
  site: 'https://omundy.github.io',
  base: '/dig345-devlog',
  integrations: [
    starlight({
      title: 'DevLog',
      sidebar: [
        { label: 'Schedule', autogenerate: { directory: 'schedule' }, },
      ],
    }),
  ],
})

4. Create (or edit) a deploy file: .github/workflows/deploy.yml. Note the period in front of .github.
5. Paste the YAML code from this page into deploy.yml
6. Go to your published site at https://USERNAME.github.io/dig345-devlog to verify the site is live.

Caution

If you don’t see your site:

• Ensure GitHub Pages has been enabled!
• Go to your repo on Github.com, click the Actions tab, and check for issues.
• On the Actions page, you might need to re-deploy by clicking “Run workflow”.

Add custom CSS to your theme

From Astro documentation

1. Add a folder called styles to your /src/ directory.
2. Add a file called custom.css to /src/styles/ directory.
3. Paste in the following code. This will set a wider default column width and improve page titles:

/* set a wider default column width */
:root {
  --sl-content-width: 50rem;
}

/* improve headings */
main h1 { font-size: 2rem;}
main h2 { font-size: 1.8rem;}
main h3 { font-size: 1.6rem;}
main h4 { font-size: 1.4rem;}
main h5 { font-size: 1.2rem;}
main h6 { font-size: 1rem;}

4. Add the path to your CSS file to Starlight’s customCss array in astro.config.mjs:

export default defineConfig({
  integrations: [
    starlight({
      title: 'DevLog',
      ...
      customCss: [
        './src/styles/custom.css', // relative path to custom CSS file
      ],
    }),
  ],
})

Add an aside

Use Starlight’s custom Markdown syntax to add an aside component.

:::caution[Github Actions]
If you don't see your site check https://github.com/USERNAME/REPO/actions for issues.
:::

Import and use a Starlight component

Use Starlight’s built-in <Icon> component.

1. Open an .mdx file and paste this content below the frontmatter.

import { Icon } from '@astrojs/starlight/components';

<Icon name="open-book" />  Learn more about [icons](https://starlight.astro.build/reference/icons/#all-icons)

2. Add this rule to custom.css

.sl-markdown-content .inline-icon {
  display: inline;
}

3. You should see this component rendered like so:

Learn more about icons

4. Update the icon

Caution

If you change the dependencies in your package.json file by hand you will need to

1. Delete the package-lock.json
2. Delete the node_modules/
3. Run npm install to regenerate package-lock.json and node_modules/.

References

• Starlight Docs, Astro Docs
• Starlight Discord
• Starlight uses the Diátaxis approach to technical documentation authoring
• Build and deploy an Astro Starlight Documentation site to GitHub Pages
• Check out Starlight’s docs, read the Astro documentation
• A Complete Guide to Build a Documentation Site with Astro Starlight (2024)

Other static site generators

• Vitepress is a Vite & Vue Powered Static Site Generator
• Comparing docs site builders: VuePress vs Starlight
• Coding the Perfect Documentation: Deciding Between 🚀 Vitepress and ✨ Astro Starlight

Astro Starlight Topics

Not-Content

The not-content CSS class disables Starlight’s default, automatic styling (e.g., margins, spacing) for the content inside it, preventing conflicts when you’re adding custom components or complex layouts that need precise control over spacing. Essentially, it tells Starlight, “Don’t touch these elements with your standard styles; let my component handle it”.

<div class="not-content">
  <p>This paragraph won't have default Starlight margins.</p>
  <button>A custom button</button>
</div>

Override a Starlight component

The most up to date instructions can be found here.

1. Add a folder in /src/components/
2. Create a new file called EmailLink.astro in /src/components/ and add the following:

---
const email = 'houston@example.com';
---

<a href=`mailto:${email}`>E-mail Me</a>

1. Tell Starlight to use your custom component in the components configuration option in astro.config.mjs:

export default defineConfig({
  integrations: [
    starlight({
      title: 'DevLog',
      ...
      components: {
        // Override the default `SocialIcons` component.
        SocialIcons: './src/components/EmailLink.astro',
      },
    }),
  ],
});

More Astro Notes

See tutorials/astro