Repository navigation
Releases
astro-project-site v0.1.0-beta.6
Added
externalDocsentries can mount a folder of another repository:git: { repo, ref, path }instead ofdir.
The build downloads only that folder atref(a shallow, sparse fetch with thegitcommand) into Astro's cache
folder, then mounts it like a local one. A tag or commit is downloaded once and reused offline; a branch is
fetched on every start, with a warning, falling back to the last copy. Links to files of that repository that
are not mounted go to it atref, and "Edit page" to its default branch.GITHUB_TOKEN(when set) reaches
private github.com repositories; a repo URL with credentials in it is refused, and symlinks in the downloaded
repository are checked out as plain files.
astro-project-site v0.1.0-beta.5
Changed
initno longer writes the GitHub workflow unless asked:--ciadds.github/workflows/site.yml(checks, a
preview per pull request, production on tags). Without it a site deploys from your machine with
npm run deploy, andinit's next steps say how to add CI later. The deploying guide covers both.
astro-project-site v0.1.0-beta.4
Fixes
- The header and the phone menu mark one nav link as current, the most specific: with Docs (
/docs/) and Guide
(/docs/guide/) in the nav, a guide page highlighted both. New helperactiveHref(hrefs, pathname). - Text taken from a README (
project-site init's tagline and step titles) decodes HTML entities once:<
is now the text<, not<. - Mirror paths and globs trim slashes in linear time, and the blog's reading-time count strips tags in linear time
(both regexes could take seconds on pathological input). Found by CodeQL, now enabled on this repository.
astro-project-site v0.1.0-beta.3
Options
docsOrder: the order of the top-level docs sections (mount routes and folders ofsrc/content/docs/docs/) in
the sidebar and in the docs cards on the docs index and the landing page. Listed sections come first; the rest
keep the default order (mounts as configured, then local folders by name). An unknown name fails the build.
astro-project-site v0.1.0-beta.2
(0.1.0-beta.1 was never published: its tag was retired when the release moved to staged publishing.)
Languages
- The template's own words (85 of them: buttons, screen-reader names, empty states, alert titles, the theme
switch, reading time, dates, the default nav and section headings) follow the site's language, from Starlight's
root locale. Built in: English, French, German, Spanish; any other language gets English until set. - New option
labels: set any of those words by name, in any language, with plural forms where something is
counted ({ one: '{n} page', other: '{n} pages' }). Unknown names are a build error. - Multilingual docs: a docs page in a second locale gets that locale's built-in words.
- Authors are joined the way the language does it ("Ada et Grace"), with
Intl.ListFormat. - Right to left: shell commands stay left to right; the theme switch, live-example buttons and link arrows
mirror. Styles use logical properties only (a test keeps it that way).
Options
landing.docs: the heading and intro of the landing page's docs sections, orfalseto hide them. The
heading was fixed to "Documentation".gallery.route: the gallery's URL path (defaultgallery); the nav, the landing page's link and the links
validator follow it.footer.copyright: the copyright line ({year},{name}filled in), orfalsefor none. Default unchanged.landing.featuresno longer adds a default intro ("The short version, for people deciding whether to read
on."): a default should not put words on a page the site never wrote.- The footer's repository link is named after its host (GitHub, GitLab, Codeberg), like the header's, instead of
"Source". One list of hosts now serves the header, the footer and Starlight.
Accessibility
- Code blocks' copy buttons have an accessible name (they only had a tooltip) and
type="button". - Docs pages with a sidebar render one small-screen menu, not two, so the site nav's landmarks have unique names.
<Live>previews are a named<section>instead of<div role="region">.SiteHeaderhas amenuprop andSiteFooteranavLabelprop.- A
theme.accentthat would make links, buttons, the current nav item or focus rings fall below WCAG 2.2 AA
contrast is reported at build time, with the pair and the ratio. - The repository now checks every built page with html-validate's accessibility rules, and the theme's colours
against WCAG 2.2 AA in both themes.
Fixes
-
Section cards outside the docs (the landing page) list
externalDocsmounts in the order they are configured,
not alphabetically. -
externalDocs[].description: one sentence for the section's card on /docs/ and the landing page, and the meta
description of its README page. Without it the card still guesses from the README's first paragraph, which can be
a footer line when the README is mostly a table. -
Phones: the hero's install command fills the width, reads from the left and no longer runs under its Copy
button; an unfilled heroliveslot no longer leaves an empty band; hero and section spacing is tighter below 50rem. -
Docs: Starlight's mobile menu button matches the site header's (a plain icon in the bar, centred) instead of a
floating white disc. -
InstallCommand: a word longer than the line (a URL or agithub:spec) wraps inside itself instead of making
the page scroll sideways on phones; shorter words still move to the next line whole. -
Peer dependency
astroraised to^7.4.7(fixes GHSA-mh32-jxcr-mh9f and GHSA-r3h5-4585-7x3w in earlier 7.x), which
needs Node.js 22.23.4 or newer (or Node 24);engines.nodesays so.
astro-project-site v0.1.0-beta.0
The first published release: on npm under the beta tag (npx astro-project-site@beta init website), and as a
tarball with its SHA-256 on the GitHub release. Everything below, from the package's first layout to the blog,
the repository-reading init and GitHub-flavoured markdown.
Blog
- New option
blog(trueor{ route, title, description, authors, postsPerPage, rss, landing }), off unless set.
Posts aresrc/content/blog/**/*.{md,mdx}(newblogcollection inprojectSiteCollections(), silent when the
folder is missing); frontmattertitle,description,date(required),updated,authors,tags,draft,
image,imageAlt,canonical. A missing field fails the build naming the file. - Pages:
/blog/(paginated/blog/2/),/blog/<path>/,/blog/tags/,/blog/tags/<tag>/,/blog/rss.xml(summary
feed,<link rel="alternate">on every page, docs included). Posts go into/llms.txt,/llms-full.txtand the
sitemap; drafts are built in dev only, with a badge. A "Blog" nav item is added to the defaultnav. - New component slots
BlogIndex,BlogPost,BlogCard; new componentsLatestPosts(also on the built-in landing,
blog.landing),BlogTags,PostMeta,TagList; long-form stylescomponents/blog/prose.css(--blog-*tokens). - New
MarginNotecomponent (astro-project-site/componentsorastro-project-site/margin-note): side notes in the
margin of posts, beside the paragraph in docs, inline asides on narrow screens;kindnote / field / warning,
optional numbering. BaseLayout/SiteHead: newtype(website|article) andcanonicalprops.- Option errors: a union option (
blog: { routee }) names the unknown key instead of "Invalid input". - New dependency
@astrojs/rss(MIT).
init reads the repository
-
Working-note folders inside
docs/(plans/,research/,internal/,drafts/,notes/,wip/,private/,
scratch/) are left out of the generated mount withexclude; delete the line to publish them. -
A mount root is titled by its
label("Reference", "Project") on overview and landing cards, not by its README's
heading. -
A README code block with no sentence before it is titled from its code ("Run npx tool a, b and c", "Add it
to your page") instead of "Step N". -
The blog's empty page says when drafts are waiting (they are left out of production builds) instead of "No posts
yet".
project-site initbuilds the site from the repository it is for: -
Reads the manifest (
package.json,Cargo.toml,pyproject.toml,go.mod,composer.json,*.gemspec), the
gitoriginand default branch, the README (title, intro, features, install/usage code),docs/,CHANGELOG.md,
CONTRIBUTING.md,LICENSEand demo folders with HTML pages. Writes a commentedastro.config.mjs(landing page,
docs mounts, mirrors, blog, footer; placeholders markedTODO), one gallery entry per demo page, a draft first
blog post from the README,/docs/index page,package.json,wrangler.jsoncnamed after the project and the
pinned CI workflow (working-directoryset when the site is a subfolder). -
Prints a "Found" summary and the files it will write, then asks;
--yesskips the question (required without a
terminal, unless--dry-run),--dry-runwrites nothing,--from <dir>reads another folder. Never writes
outside the target folder, never overwrites without--force. -
Repository text is data, never code: every comment in generated files is one line (line terminators, U+2028/
U+2029 become spaces), strings are escaped JS literals or quoted YAML, versions/licences/URLs that do not look
like one are dropped, the Worker name is a slug, and only plainly named*.gemspecfiles are read. -
An empty folder still gets the starter's placeholders and example docs/apps;
--blankalways copies the plain
starter (the previous behaviour). -
externalDocs[].include: globs picking the files of a mount, so a repo-root mount
({ dir: '..', route: 'project', label: 'Project', include: ['README.md', 'CHANGELOG.md'] }) mounts just those.
The site's own folder is never mounted (also withoutinclude). A file belongs to the deepest mount whose globs
accept it, for link rewriting, the content loader and llms.txt.
Markdown: GitHub parity
-
mermaidis an optional peer dependency (about 127 MB installed):npm i mermaidin the site to draw
```mermaiddiagrams. Without it they show their source with a note, and the build warns once with the
first file.project-site initadds it when the repository's markdown has a diagram.
Markdown renders at least as well as on GitHub everywhere it appears (docs,externalDocsfolders, blog posts,
a project's own.mdpages): the plugins are registered on Astro's global markdown processor (Sätteri). -
GitHub alerts (
> [!NOTE],[!TIP],[!IMPORTANT],[!WARNING],[!CAUTION]), emoji shortcodes, visible
"Footnotes" label, named task-list checkboxes, tables that scroll in their own box,<details>/<kbd>styles. -
Math (
$…$,$$…$$,```math) typeset with KaTeX at build time; KaTeX's CSS and fonts are served from
/_project-site/katex-<version>/and linked only from pages with math.$5 and $6stays text (GitHub's rule). -
```mermaiddiagrams rendered in the browser: Mermaid is loaded only on pages with diagrams, when one
scrolls near; themed from the site tokens and redrawn on theme switch; wide diagrams scroll; source kept as the
text alternative and shown when a diagram cannot be drawn. -
Code blocks: line numbers (
showLineNumbers) and collapsible sections (collapse={…}) plugins, shell prompts
that are neither selectable nor copied (output lines left out of the copy), a "Wrap lines" toggle on blocks that
overflow, and aliases forshell-session,terminal,env, … Also applied to<Code>/<Live>. -
Heading anchor links on markdown pages outside the docs;
--is no longer turned into an en dash. -
New
markdownoption:{ alerts, emoji, math, mermaid, headingLinks, codeWrapToggle }, alltrueby default. -
New dependencies (all MIT unless noted):
mermaid,katex,gemoji,github-slugger(ISC),
hast-util-from-html,@expressive-code/core,@expressive-code/plugin-line-numbers,
@expressive-code/plugin-collapsible-sections.
Responsive design and accessibility
Responsive design and accessibility pass, checked in Chromium, Firefox and WebKit from 320px phones to 2560px
screens, at 200%/400% zoom and with a large default font.
InstallCommandwraps between words on narrow screens instead of cutting the command off in a scroll box.- Landing and gallery pages no longer load Starlight's base stylesheet (~64 KB):
<Live>imports Expressive
Code's<Code>directly (new internal virtual modulevirtual:astro-project-site/code). - Small-screen site menu: closes when focus leaves it, announces
aria-expandedimmediately, and scrolls inside
itself on short screens (phones in landscape) instead of running off the bottom. - Touch screens (
pointer: coarse): header links, menu buttons (Starlight's included), theme select, copy and
Reset buttons, gallery filters and footer links are at least 44×44; the<Live>caption anchor is always visible
where there is no hover. - Wide tables and code blocks that scroll sideways get a keyboard tab stop with a focus ring (Safari has none).
- Forced colours (Windows high contrast): pressed gallery filters and the current nav item stay distinguishable.
prefers-contrast: moremoves--site-mutedtoward the text colour.- Print: docs pages print without the site nav and footer links; editable
<Live>examples print their code. - Header and menu nav landmarks are labelled "Site" (Starlight's sidebar is "Main"), so docs pages no longer have
two landmarks with the same name. - Landing "how it works" code uses
github-light-default/github-dark-default(comments meet AA contrast). test/ux/ux-check.mjs: a re-runnable responsive/UX check (README, Development).base.cssno longer restyles docs pages: an MDX page importingastro-project-site/componentspulled it in, and
its unlayereda { color }beat Starlight (e.g. the sidebar's current-page link became unreadable). Its element
rules are now scoped to BaseLayout's<html data-site-page>at element specificity.- Component overrides are bundled only into pages that render them: the package imports each slot from its own
virtual module (virtual:astro-project-site/components/<Slot>); docs pages no longer carry acomponents.Landing
override and its CSS. The aggregatevirtual:astro-project-site/componentsstill exists. <Live>in iframe mode withbase: no more failed module load and 404 in Firefox (its preloader ignores<base>
in srcdoc documents; script and link URLs are resolved againstbaseup front).- Header: when the bar is too narrow for the nav (long project name, many items, search), the nav moves into the
menu instead of squeezing the project name; when even that is too tight (a phone with a large default font) the
version badge is hidden (the footer shows the version). - Landing and gallery components carry their own shared classes (
styles/components.css), soHero,Section,
CallToAction, the gallery andInstallCommandare styled inside docs pages too. - The shared header on docs pages takes Search and ThemeSelect from Starlight's resolved components, so a search
plugin that replaces Starlight's search is used (previously onlystarlight.components.Searchwas). - Pages outside the docs take
lang/dirfrom Starlight's root/default locale instead of alwaysen. externalDocs[].excludeand docs-genfilesglobs support{a,b}and[…]: one glob implementation
(src/glob.mjs) for them and mirrors.starlight.title,descriptionandfaviconlog a warning (they change the docs only).- Landing: no l...