Building SEGUL Documentation

SEGUL documentation is built using Astro and Starlight, and deployed to Cloudflare Workers. The documentation is written in Markdown and MDX. We use Bun to manage dependencies and run scripts.

Prerequisites

• Bun
• Git
• GH CLI (recommended)

Clone the repository

gh repo clone hhandika/segui

Using git:

git clone https://github.com/hhandika/segui.git

Install dependencies

Install Bun:

curl -fsSL https://bun.sh/install | bash

On Windows, use PowerShell:

powershell -c "irm bun.sh/install.ps1 | iex"

Change directory to the website folder:

cd segui/website

Install the website dependencies:

bun install

Run the website

To run the website locally with hot reload, use the following command:

bun run dev

The website will be available at http://localhost:4321/.

Build the website

Check types and build the static site into dist/:

bun run check
bun run build

Preview the production build locally:

bun run preview

Project structure

• src/content/docs/docs/: documentation pages. The folder structure maps to the URL, for example src/content/docs/docs/cli-usage/align-concat.mdoc is served at /docs/cli-usage/align-concat/.
• src/pages/: the landing (index.astro), get started, and about pages, styled with Tailwind. src/layouts/Layout.astro and src/components/Navbar.astro frame them.
• src/data/site.ts: shared content for those pages, such as the tool list and citation.
• src/components/: Astro components used by pages.
• src/assets/ and public/: images and static files.
• astro.config.mjs: site configuration, including the sidebar and redirects.

Each page needs a title in its frontmatter. Use sidebar.order to order pages within a sidebar group, and use Starlight asides for callouts. In Markdoc (.mdoc) pages, write them as {% aside type="note" %} … {% /aside %} with type set to note, tip, caution, or danger and an optional title. Plain Markdown (.md) pages use :::note … :::.