Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .github/workflows/build-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,30 @@ on:
required: false
type: string
default: '>_'
logo:
description: >-
Optional path (relative to the calling repo's root) to an image
(SVG, PNG, ...) shown in the header next to the title.
required: false
type: string
default: ''
logo-dark:
description: Optional dark-theme variant of `logo`.
required: false
type: string
default: ''
logo-replaces-title:
description: Hide the title text and show only the logo (keep it when the logo has no wordmark).
required: false
type: boolean
default: false
favicon:
description: >-
Optional path (relative to the calling repo's root) to a favicon
(.svg, .png or .ico). Replaces the one generated from favicon-glyph.
required: false
type: string
default: ''
extra-css:
description: >-
Optional path (relative to the calling repo's root) to a CSS file
Expand Down Expand Up @@ -124,6 +148,10 @@ jobs:
DOCS_DESCRIPTION: ${{ inputs.description }}
DOCS_ACCENT_HUE: ${{ inputs.accent-hue }}
DOCS_FAVICON_GLYPH: ${{ inputs.favicon-glyph }}
DOCS_FAVICON: ${{ inputs.favicon != '' && format('{0}/target/{1}', github.workspace, inputs.favicon) || '' }}
DOCS_LOGO: ${{ inputs.logo != '' && format('{0}/target/{1}', github.workspace, inputs.logo) || '' }}
DOCS_LOGO_DARK: ${{ inputs.logo-dark != '' && format('{0}/target/{1}', github.workspace, inputs.logo-dark) || '' }}
DOCS_LOGO_REPLACES_TITLE: ${{ inputs.logo-replaces-title }}
DOCS_EXTRA_CSS: ${{ inputs.extra-css != '' && format('{0}/target/{1}', github.workspace, inputs.extra-css) || '' }}
DOCS_LATEST_RELEASE_TAG: ${{ steps.latest-release.outputs.tag }}
DOCS_LATEST_RELEASE_URL: ${{ steps.latest-release.outputs.url }}
Expand Down
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ dist/
.astro/

# generated from DOCS_CONTENT_DIR's README.md/AGENTS.md/CHANGELOG.md by
# scripts/sync-docs.mjs, and from DOCS_ACCENT_HUE/DOCS_FAVICON_GLYPH by
# scripts/sync-docs.mjs, and from DOCS_ACCENT_HUE/DOCS_FAVICON_GLYPH/DOCS_FAVICON/DOCS_LOGO by
# astro.config.mjs
src/content/docs/*.md
src/generated/
public/favicon.svg
public/favicon.*

# dependencies
node_modules/
Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ instead of N copies drifting apart.
becomes an absolute link back to the source repo on GitHub.
- Generates a themed favicon and accent color per project from two inputs
(`accent-hue`, `favicon-glyph`) — no per-project asset to hand-craft.
A project with its own brand passes `logo` (header, optionally
`logo-dark`) and `favicon` files from its repo instead.
- Shows the target repo's latest GitHub release as a small pill next to the
site title, linking to its release page — fetched automatically, no input
to set, silently omitted if the repo has no releases yet. Placed in the
Expand Down Expand Up @@ -88,6 +90,10 @@ avoids by using Actions-based deployment from the start).
| `description` | no | `''` | Meta description |
| `accent-hue` | no | `234` (Starlight blue) | HSL hue, 0-360 |
| `favicon-glyph` | no | `>_` | Generated favicon text |
| `favicon` | no | `''` | Path (in the calling repo) to a `.svg`/`.png`/`.ico` favicon; replaces the generated one |
| `logo` | no | `''` | Path (in the calling repo) to an image shown in the header next to the title |
| `logo-dark` | no | `''` | Dark-theme variant of `logo` |
| `logo-replaces-title` | no | `false` | Show only the logo, no title text (for a logo that includes the name) |
| `extra-css` | no | `''` | Path (in the calling repo) to a CSS file applied after this kit's base styles — for art-direction beyond a hue |
| `extra-public-dir` | no | `''` | Path (in the calling repo) to a directory of static files (install scripts, an agent `PROMPT.md`, ...) copied verbatim into the deployed site's root |
| `docs-kit-ref` | no | `main` | Which ref of this repo to build with — **pin this to a released tag** once one exists, so a docs-kit change doesn't silently change every project's site on its next push |
Expand Down Expand Up @@ -119,6 +125,8 @@ these — see the comments at the top of each for the full contract:
- `DOCS_GITHUB_URL`, `DOCS_SITE_URL`, `DOCS_BASE_PATH`
- `DOCS_TITLE`, `DOCS_DESCRIPTION`
- `DOCS_ACCENT_HUE`, `DOCS_FAVICON_GLYPH`
- `DOCS_FAVICON`, `DOCS_LOGO`, `DOCS_LOGO_DARK` — absolute paths into the
target repo; `DOCS_LOGO_REPLACES_TITLE` — `true`/`false`
- `DOCS_EXTRA_CSS`
- `DOCS_LATEST_RELEASE_TAG`, `DOCS_LATEST_RELEASE_URL` — from `gh api
.../releases/latest`, run in `build-docs.yml` itself (needs a token, so
Expand Down
49 changes: 42 additions & 7 deletions astro.config.mjs
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
// @ts-check
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
Expand All @@ -13,18 +14,50 @@ const BASE_PATH = process.env.DOCS_BASE_PATH ?? '';
const ACCENT_HUE = Number(process.env.DOCS_ACCENT_HUE ?? 234); // 234 = Starlight's own default blue
const FAVICON_GLYPH = process.env.DOCS_FAVICON_GLYPH ?? '>_';
const EXTRA_CSS = process.env.DOCS_EXTRA_CSS; // optional absolute path, from the target repo
// Optional absolute paths, from the target repo: header logo (plus a dark-theme
// variant) and a favicon file that replaces the generated glyph one.
const LOGO = process.env.DOCS_LOGO;
const LOGO_DARK = process.env.DOCS_LOGO_DARK;
const LOGO_REPLACES_TITLE = process.env.DOCS_LOGO_REPLACES_TITLE === 'true';
const FAVICON = process.env.DOCS_FAVICON;
// Fetched by build-docs.yml via `gh api .../releases/latest` (needs a
// GitHub API call + token, so it belongs in the workflow, not here) and
// simply empty when the target repo has no release yet.
const RELEASE_TAG = process.env.DOCS_LATEST_RELEASE_TAG ?? '';
const RELEASE_URL = process.env.DOCS_LATEST_RELEASE_URL ?? '';

// Favicon is generated (not a static file) so every project gets a themed
// tab icon for free — same glyph shape as before, tinted to DOCS_ACCENT_HUE.
writeFileSync(
fileURLToPath(new URL('./public/favicon.svg', import.meta.url)),
`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="70" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-weight="700" fill="hsl(${ACCENT_HUE}, 70%, 45%)">${FAVICON_GLYPH}</text></svg>\n`
);
// Copies a target-repo file into this app as `<dir>/<name><ext>`; returns that
// path relative to the app root.
function bring(src, dir, name) {
if (!existsSync(src)) throw new Error(`docs-kit: ${src} does not exist`);
const rel = `${dir}/${name}${path.extname(src).toLowerCase()}`;
const dest = fileURLToPath(new URL(`./${rel}`, import.meta.url));
mkdirSync(path.dirname(dest), { recursive: true });
copyFileSync(src, dest);
return rel;
}

// A project's own favicon wins; otherwise one is generated so every project
// still gets a themed tab icon: the glyph, tinted to DOCS_ACCENT_HUE.
let favicon = '/favicon.svg';
if (FAVICON) {
favicon = '/' + path.basename(bring(FAVICON, 'public', 'favicon'));
} else {
writeFileSync(
fileURLToPath(new URL('./public/favicon.svg', import.meta.url)),
`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="70" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-weight="700" fill="hsl(${ACCENT_HUE}, 70%, 45%)">${FAVICON_GLYPH}</text></svg>\n`
);
}

// Starlight resolves logo paths through Vite, so they must live inside this app.
/** @type {import('@astrojs/starlight/types').StarlightUserConfig['logo']} */
let logo;
if (LOGO) {
const light = './' + bring(LOGO, 'src/generated/brand', 'logo');
logo = LOGO_DARK
? { light, dark: './' + bring(LOGO_DARK, 'src/generated/brand', 'logo-dark'), replacesTitle: LOGO_REPLACES_TITLE }
: { src: light, replacesTitle: LOGO_REPLACES_TITLE };
}

// Read by src/components/SiteTitle.astro (a Starlight component override,
// registered below) to render the header release badge. A generated file
Expand Down Expand Up @@ -83,6 +116,8 @@ export default defineConfig({
starlight({
title: TITLE,
description: DESCRIPTION,
favicon,
...(logo ? { logo } : {}),
social: GITHUB_URL ? [{ icon: 'github', label: 'GitHub', href: GITHUB_URL }] : [],
customCss: ['./src/styles/custom.css', ...(EXTRA_CSS ? [EXTRA_CSS] : [])],
components: { SiteTitle: './src/components/SiteTitle.astro' },
Expand Down
Loading