diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 5756ea3..69a69c6 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -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 @@ -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 }} diff --git a/.gitignore b/.gitignore index 2027410..dc5773c 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/README.md b/README.md index 2df96b6..5b26abd 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 | @@ -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 diff --git a/astro.config.mjs b/astro.config.mjs index 255540b..4c06926 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -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'; @@ -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)), - `${FAVICON_GLYPH}\n` -); +// Copies a target-repo file into this app as `/`; 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)), + `${FAVICON_GLYPH}\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 @@ -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' },