@master/internal-site

First-party Astro and Svelte 5 website framework for Master websites. This package is public for installation; it is an internal platform, not a supported general-purpose product. Consumers pin an exact version and upgrade deliberately.

Ownership

Master maintains document layouts, navigation, search, localization, MDX components, site composition, UI-backed controls, artwork and demonstration orchestration here. Master CSS maintains its homepage composition, guide/reference content and adapters that read its product data. The organization blog and brand pages live in the Master website, outside this package. Drafts are never packaged.

The package imports Master CSS rather than duplicating its compiler or maintaining a parallel CSS implementation. Install the matching Astro, Svelte, Vite and Master CSS toolchain versions declared by your site's lockfile. During RC development, use the exact source-pinned site snapshot and its dependency closure; never depend on a moving Git branch.

This initial release targets the CSS-first site snapshots, starting with df48b35846c1. Older npm RC releases do not provide that contract. The 0.0.0 peer alternative allows the product's unversioned development workspaces; published consumers must pin a validated snapshot of the complete toolchain.

Configure a consumer

// astro.config.ts
import { defineConfig } from 'astro/config'
import masterSite from '@master/internal-site/astro'
import site from './site.config'

export default defineConfig({ integrations: [masterSite(site)] })

site.config.ts exports defineSite(...) from @master/internal-site/config. It declares the site's origin, content directory, app module, locale policy and section module URLs. Optional document layouts, category sources, styles and a server-only highlighter are also URLs. Keep route content lazy: do not import a complete page or specimen catalog into the configuration.

Optional header.communityNavs selects the links shown beside search without removing community links from the compact menu or footer. Set header.searchOnHome to show search in the desktop homepage header. When available, the language switch follows the community links and a divider.

The app module exports its logo component, navigation, version links and source/feedback URLs using the SiteApp contract. Consumers retain their own content and homepage composition. Ordinary documents use content/<section>/<slug>/content.mdx and metadata.ts; a local page.astro can override the generated entry. Dynamic routes enumerate params from lightweight params.ts files. The integration owns generated routes, page asset collection and the Astro/Svelte renderer setup.

Blog articles with a cover declare cover: { src, alt, width, height } in their metadata. The shared article layout renders it below the byline and uses it for Open Graph and Twitter images. An optional socialImage points to a PNG/JPEG version of the same artwork; a cover takes precedence over separate social-card images. Articles without a cover retain their existing layout and social cards.

/* styles/globals.css */
@import '@master/css';
@reference '@master/internal-site/styles/foundation.css';
@import '@master/internal-site/styles/foundation.css';

The reference supplies definitions to headless tooling; the import delivers native styles. Import this stylesheet from the module configured as styles.site. Use the package's document/interface boundaries where the corresponding layouts need them. Do not combine every gallery stylesheet into a site-wide bundle.

The route loader delivers that foundation once for every page, including bare iframe examples. A bare section must not import a second global entry; it only opts out of the interface and document boundaries.

---
import Callout from '@master/internal-site/components/Callout.astro'
---
<Callout tone="info">Content remains in the product repository.</Callout>

Import individual component subpaths, including .astro and .svelte extensions. Interactive Svelte islands use the consumer's Astro hydration directive. Shared theme/context data remains scoped to the rendered request. Components are distributed as source for the consumer's Astro and Svelte compilers; astro and config entrypoints are built Node ESM and include declarations.

Subpaths

| Subpath | Purpose | | --- | --- | | astro, config | Integration and typed configuration | | components/*, layouts/*, contexts/* | Document shell and reusable interface components | | styles/* | Foundation, document, interface and component styles | | assets/* | Shared fonts, icons and brand artwork | | home/*, blog/* | Reusable homepage and article presentation | | demo/*, benchmarks/*, examples/* | Presentation primitives and isolated example pages | | css/* | Server-only Master CSS compiler/highlighter adapters and preset demonstrations | | env | Virtual module declarations for a consumer's env.d.ts |

The CSS-specific subpaths require the matching optional compiler, tooling, schema, preset and language-service peers. Keep them out of browser-only imports. Shared public assets are served in development and copied into build output; consumer public files take precedence. No install hook writes consumer source files.

Local MDX translations

English uses the root URL. The shared locale definitions map ja, tw, ko and cn to matching URL prefixes and the HTML language tags ja, zh-TW, ko and zh-CN. Keep complete sibling editions in content.<locale>.mdx; metadata.ts retains English identity, dates, authors and ordering. Translated frontmatter supplies titles, summaries, image descriptions and article-specific demonstration copy. Keep explicit heading IDs identical across editions.

build/localization.ts supplies filesystem discovery, localized document reads, dependency fingerprints, explicit review operations and completeness checks. Configure i18n.validation with the consumer's resource-loader and review-index URLs. The integration validates them on every production build, including direct astro build calls. Source fingerprints include metadata and imported local or shared source files. A missing edition or changed source/translation fails the gate until independently reviewed. Builds never refresh review records.

The resource loader also exposes local and shared UI dictionaries to the same gate. Common controls use common/translations.js; product copy belongs to each consumer. Both sites follow common/terminology.json. Use sharedInterfaceKeys() to include newly introduced literal interface requests in the UI inventory.

The route registry imports each selected MDX edition through Astro's propagated asset boundary. Nested MDX imports inherit their parent's language through Vite; missing prose editions and draft includes throw. Prose-free fenced companion examples stay shared. Do not import every edition eagerly or reimplement the resolver in a consumer. Per-request documentCopyOf(Astro) and demoCopy let shared demonstrations read localized prose while retaining one executable model.

Consumers derive navigation, search, Markdown, feeds and llms exports from their public inventory and the selected local edition. Use extractSearchNodesFromMdx for authored MDX and extractSearchNodesFromMarkdown for portable output; the latter retains explicit anchor targets and GFM tables. transformMarkdownLinks edits reader links without changing inline or fenced examples. Withdraw stale owned exports when a source becomes a draft or is removed. Required Reference inputs reject draft status instead of publishing a partial catalog.

Development and releases

From the Master repository, run bun run build:packages, bun run --cwd packages/internal-site type-check and bun run --cwd packages/internal-site test. Astro checks .astro implementations and Svelte checks interactive components separately. The root build builds the Node entrypoints before the site.

Before publishing, inspect the tarball, install it in the Master CSS consumer and validate both sites, including local CSS imports, themes, mobile navigation and lazy page styles. Publish an immutable version, update exact consumer pins and lockfiles, then deploy preview builds. Roll back by restoring the previous dependency version and deployment; do not unpublish a release in use.

Publishing

Master's publish.yml workflow validates the site and packages, retains the packed archives, then publishes those exact bytes through npm Trusted Publishing. The trusted publisher is GitHub repository master-co/master, workflow publish.yml, with no GitHub environment. Versions are committed before dispatch; consumers upgrade exact pins after registry integrity verification. No npm token is stored in GitHub. Master remains private, so these releases use OIDC without public provenance attestations.