Skip to content

Latest commit

 

History

History
46 lines (27 loc) · 3.28 KB

README.md

File metadata and controls

46 lines (27 loc) · 3.28 KB
Raw

BlueBuild website

This repository contains the website and documentation for BlueBuild. The site itself, https://blue-build.org/ is built using Astro, Starlight and Tailwind CSS.

Documentation

All documentation and the front page is written src/content/docs/ as either Markdown or MDX. The directory is rendered into docs by Starlight, and can be added into the docs sidebar in astro.config.mjs. Markdown frontmatter is used to set metadata for each, including the title, so there is no need for a Markdown top-level title.

The documentation strives to broadly follow the Diátaxis framework. /learn/ is mostly explanation, /how-to/ is how-to guides, and /reference/ is obviously reference.

To add images to documentation pages, the standard Markdown syntax should be used (![alt](src)). The source should be somewhere in src/content/docs/ or src/assets/. These images will be optimized automatically. Including meaningful alt-text is required.

Components

Custom components are used to implement custom designs and new features. The code for the is stored in src/components/. For static use cases, Astro components should be used. If more reactivity is needed, using Svelte components is preferred (none used yet).

Icons can be used anywhere on this site with the Icon component from astro-icon. Use Icones to search for icons. New icon sets need to be added with pnpm add @iconify-json/<collectionName>.

Local development

This project requires node and npm or pnpm for local development.

  • A Mise configuration is provided and works out-of-the-box in a Mise-activated shell.
  • A Devbox configuration is provided and can be activated by running devbox shell in the project directory (if Devbox is installed).

To get started with local development install the dependencies:

pnpm install # pnpm is recommended for faster speeds, use whatever you want

Then to start the dev server to preview your changes:

pnpm dev
# or
npm run dev

The dev script among others can take in a GH_TOKEN environment variable, which takes in a GitHub token with read access to all public, which will be used to bypass GitHub rate-limits. Without it, the module reference pages may fail to load.

Linting & formatting

This project uses linting with ESLint and formatting with Prettier. To format all files locally, run pnpm run fmt (or npm run fmt). If you're using VSCode, some recommended plugins and default settings are supplied with this project, and formatting should work directly in the editor.

Unfortunately, linting for .astro and .mdx files with ESLint isn't currently stable enough to be included.