Skip to content

Latest commit

 

History

History
139 lines (86 loc) · 6.76 KB

CONTRIBUTING.md

File metadata and controls

139 lines (86 loc) · 6.76 KB
Raw

Contributor Manual

We welcome contributions of any size and contributors of any skill level. As an open source project, we believe in giving back to our contributors. We are happy to help with guidance on PRs, technical writing, and turning any feature idea into a reality.

Tip for new contributors: Take a look at GitHub's Docs for helpful information on working with GitHub.

This document is an active work in progress — like Starlight itself! Feel free to join us in the Astro Discord server to join the discussion. Look for the #starlight channel and say “Hi!” when you arrive.

Types of contributions

There are lots of ways to contribute to Starlight.

Maintaining Starlight requires writing Astro code, as well as addressing accessibility, styling, and UX concerns. This repository also contains the code for the Starlight docs website. Help writing docs, catching typos and errors, as well as translating docs into other languages is always welcome.

You can also get involved by leaving feedback on issues or reviewing pull requests by other contributors.

We encourage you to:

About this repo

This repo is a “monorepo,” meaning it contains several projects in one. It contains the Starlight docs site in docs/ and the packages that make up Starlight in packages/.

Setting up a development environment

Developing locally

Prerequisites: Developing Starlight requires Node.js and pnpm. Make sure you have these installed before following these steps.

  1. Fork Starlight to your personal GitHub account by clicking Fork on the main Starlight repo page.

  2. Clone your fork of Starlight to your computer. Replace YOUR-USERNAME in the command below with your GitHub username to clone in a Terminal:

    git clone https://github.com/YOUR-USERNAME/starlight.git

  3. Change directory to the cloned repo:

    cd starlight

  4. Install dependencies with pnpm:

    pnpm i

Developing using Gitpod

Instead of working locally on your machine, you can also contribute using an online coding development environment like Gitpod.

Prerequisites: Developing Starlight using Gitpod requires a free Gitpod account.

  1. Open the Gitpod URL https://gitpod.io/#https://github.com/withastro/starlight. You can alternatively install a Gitpod browser extension which will add a "Gitpod" button when viewing Starlight's repo on GitHub.

  2. Install dependencies with pnpm:

    pnpm i

Testing changes while you work

Run the Astro dev server on the docs site to see how changes you make impact a project using Starlight.

To do this, move into the docs/ directory from the root of the repo and then run pnpm dev:

cd docs
pnpm dev

You should then be able to open http://localhost:3000 and see your changes.

Translations

Translations help make Starlight accessible to more people.

Translating Starlight’s UI

Starlight’s UI comes with some built-in text elements. For example, the table of contents on a Starlight page has a heading of “On this page” and the theme picker shows “Light”, “Dark”, and “Auto” labels. Starlight aims to provide these in as many languages as possible.

Help out by adding or updating translation files in packages/starlight/translations. Each language’s JSON file follows the translation structure described in Starlight’s docs.

Translating Starlight’s docs

Starlight’s documentation is also translated into multiple languages. You can find the source code for the site in the docs/ directory of this repository.

Help out by:

Visit https://i18n.starlight.astro.build to track translation progress for the currently supported languages.

Understanding Starlight

  • Starlight is built as an Astro integration. Read the Astro Integration API docs to learn more about how integrations work.

    The Starlight integration is exported from packages/starlight/index.ts. It sets up Starlight’s routing logic, parses user config, and adds configuration to a Starlight user’s Astro project.

  • Most pages in a Starlight project are built using a single packages/starlight/index.astro route. If you’ve worked on an Astro site before, much of this should look familiar: it’s an Astro component and uses a number of other components to build a page based on user content.

  • Starlight consumes a user’s content from the 'docs' content collection. This allows us to specify the permissible frontmatter via a Starlight-specific schema and get predictable data while providing clear error messages if a user sets invalid frontmatter in a page.

  • Components that require JavaScript for their functionality are all written without a UI framework, most often as custom elements. This helps keep Starlight lightweight and makes it easier for a user to choose to add components from a framework of their choice to their project.