@beforesemicolon/builder 1.8.24 → 2.0.0

package/dist/cjs/docs/templates/fading-citrus/README.md

@@ -1,822 +0,0 @@
-# fading-citrus Template
-
-`fading-citrus` is a complete documentation-site template for `buildDocs({ template: 'fading-citrus' })`.
-
-This README only documents the template-specific surface area: layouts, Markdown layout parts, assets, scripts, theme variables, and the expected override points. General builder behavior is documented in the repository root README.
-
-## What This Template Provides
-
-The template ships:
-
-- A landing page shell.
-- A documentation page shell.
-- Landing page section handlers for Markdown layout syntax.
-- A code snippet renderer with copy behavior.
-- Header, footer, metadata, and shared layout helpers.
-- CSS for landing and documentation pages.
-- A dark-first theme with light and dark variable maps.
-- Default assets, including social icons, favicons, and default logo files.
-
-Use it when you want a polished documentation site where most page content stays in Markdown and the template owns the HTML structure.
-
-## Directory Surface
-
-```txt
-fading-citrus/
-  README.md
-  template.config.js
-  assets/
-    logo.svg
-    favicon/
-    ...
-  layouts/
-    landing.js
-    document.js
-    _header.js
-    _footer.js
-    _head-meta.js
-    _code-snippet.js
-    _layout-utils.js
-    landing-hero.js
-    landing-ecosystem.js
-    landing-features.js
-    landing-showcase.js
-    landing-install.js
-    landing-cta.js
-  stylesheets/
-    common.css
-    documentation.css
-    fonts.css
-    landing.css
-    normalize.css
-    *.hightlighter.css
-```
-
-Files prefixed with `_` are private template helpers. A docs project can override them by providing a same-named file in `docs/_template/layouts`, but they are not intended to be Markdown layout names.
-
-## Page Layouts
-
-### `landing`
-
-Used by pages with:
-
-```md
----
-layout: landing
----
-```
-
-This layout renders:
-
-- metadata from `_head-meta.js`
-- `/stylesheets/landing.css`
-- optional generated `theme.css`
-- shared header
-- rendered Markdown content
-- shared footer
-- page scripts collected by the template config
-
-The landing layout intentionally does not hardcode landing content. It expects the page body to be composed with Markdown layout blocks such as `landing-hero`, `landing-features`, and `landing-install`.
-
-### `document`
-
-Used by documentation pages with:
-
-```md
----
-layout: document
----
-```
-
-This layout renders:
-
-- metadata from `_head-meta.js`
-- `/stylesheets/documentation.css`
-- optional generated `theme.css`
-- shared header
-- documentation navigation from the generated site map
-- page article content
-- previous/next documentation links
-- edit-on-GitHub link
-- table of contents from Markdown headings
-- shared footer
-- page scripts collected by the template config
-
-The `document` layout currently expects documentation pages to live under `/documentation`. The generated left navigation is read from `props.siteMap.get('documentation')`.
-
-## Header And Footer
-
-The header and footer are provided by:
-
-- `layouts/_header.js`
-- `layouts/_footer.js`
-
-They use `/assets/logo.svg` for the site logo. This is intentionally asset-based so a docs project can override the logo without replacing layout code.
-
-Override the logo by adding:
-
-```txt
-docs/_template/assets/logo.svg
-```
-
-The footer also uses social icons from `/assets/*.svg`.
-
-Header and footer links are driven by `site` config. Override `_header.js`, `_footer.js`, or the full page layouts only when the HTML structure itself needs to change.
-
-## Metadata
-
-Metadata is generated by:
-
-```txt
-layouts/_head-meta.js
-```
-
-It emits:
-
-- title and meta description
-- canonical URL
-- Open Graph tags
-- Twitter card tags
-- keywords
-- robots metadata
-- favicon links
-- structured JSON-LD for web site, software application, breadcrumbs, and docs pages
-
-Important current behavior:
-
-- The helper reads defaults from `template.config.js` `meta`.
-- `meta.siteUrl` overrides the `buildDocs({ siteUrl })` value when needed.
-- `meta.siteName`, `meta.title`, and `meta.description` customize the fallback site identity.
-- `meta.image` customizes the default Open Graph and Twitter card image.
-- `meta.image` can be absolute, such as `https://example.com/card.jpg`, or site-relative, such as `/assets/site-image.jpg`.
-- If no image is configured, the fallback is `/assets/site-image.jpg`.
-
-For project-specific social images, add the file under `docs/_template/assets` and point `meta.image` at it:
-
-```js
-// docs/_template/template.config.js
-export default {
-    meta: {
-        siteName: 'Example',
-        title: 'Example by Before Semicolon',
-        description: 'Documentation for Example.',
-        image: '/assets/site-image.jpg',
-    },
-}
-```
-
-Override `_head-meta.js` in `docs/_template/layouts` only when the generated metadata shape itself needs to change.
-
-## Site Identity And Links
-
-The template is generic. Product-specific labels, repository links, footer links, and edit links should live in `docs/_template/template.config.js` under `site`.
-
-```js
-// docs/_template/template.config.js
-export default {
-    site: {
-        name: 'Example',
-        packageName: '@example/project',
-        repositoryUrl: 'https://github.com/example/project',
-        repositoryLabel: 'Example GitHub repository',
-        docsEditUrl: 'https://github.com/example/project/tree/main/docs',
-        navLinks: [
-            { label: 'Features', href: '/#features' },
-            { label: 'Code', href: '/#code' },
-            { label: 'Install', href: '/#install' },
-        ],
-        actionLinks: [
-            {
-                label: 'Documentation',
-                href: '/documentation',
-                className: 'btn-primary',
-            },
-        ],
-        footerDescription: 'Documentation for Example.',
-        footerGroups: [
-            {
-                title: 'Learning Resources',
-                links: [{ label: 'Documentation', href: '/documentation' }],
-            },
-        ],
-        socialLinks: [
-            {
-                name: 'GitHub',
-                href: 'https://github.com/example',
-                icon: '/assets/github.svg',
-            },
-        ],
-        copyright: `Copyright © ${new Date().getFullYear()} Example.`,
-    },
-}
-```
-
-Relevant fields:
-
-- `repositoryUrl` powers the header GitHub links and the docs version badge.
-- `docsEditUrl` powers the “edit this doc” link. If omitted, that link is hidden.
-- `packageName` powers the default landing hero install command.
-- `navLinks`, `actionLinks`, `footerGroups`, and `socialLinks` replace the template defaults.
-
-## Markdown Layout Handlers
-
-`template.config.js` registers these Markdown layout handlers:
-
-```js
-markdownLayouts: {
-    'landing-hero': landingHero,
-    'landing-ecosystem': landingEcosystem,
-    'landing-features': landingFeatures,
-    'landing-showcase': landingShowcase,
-    'landing-install': landingInstall,
-    'landing-cta': landingCta,
-}
-```
-
-Each handler receives parsed Markdown parts. Each part has already been rendered to HTML, so handlers inject `part.html`.
-
-## `landing-hero`
-
-Purpose: first-screen landing section with headline, copy, stats, CTA buttons, and optional code panel.
-
-Syntax:
-
-````md
-::: layout landing-hero version=v1.0.0 title="Reactive DOM." title2="Zero build." primaryLabel="Get Started" secondaryLabel="npm i package-name"
-
-=== copy
-
-A short landing intro.
-
-=== stat
-
-## 7.6KB
-
-CDN gzip
-
-=== stat
-
-## 0
-
-third-party deps
-
-=== code filename=counter.js lang=javascript
-
-```text
-console.log('hello')
-```
-````
-
-:::
-
-````
-
-Supported layout options:
-
-- `version`: optional version badge text.
-- `title`: first headline line.
-- `title2`: second headline line.
-- `primaryHref`: primary CTA URL. Defaults to `/documentation/get-started`.
-- `primaryLabel`: primary CTA label. Defaults to `Get Started`.
-- `secondaryLabel`: secondary CTA label. Defaults to `site.landingHeroSecondaryLabel`, then `npm i ${site.packageName}`, then `Install`.
-- `versionHref`: version badge URL. Defaults to `site.landingHeroVersionHref`, then `site.repositoryUrl`.
-
-Supported parts:
-
-- `copy`: rendered as hero subtitle.
-- `stat`: can be repeated. Expects an `h2` value and paragraph label.
-- `code`: optional code block. Supports `filename` and `lang` options.
-
-Notes:
-
-- The secondary CTA currently points to `#install`.
-- The version badge links to `versionHref`, `site.landingHeroVersionHref`, or `site.repositoryUrl`.
-
-## `landing-ecosystem`
-
-Purpose: product/ecosystem cards.
-
-Syntax:
-
-```md
-::: layout landing-ecosystem
-
-=== header
-
-`// ecosystem`
-
-## Built on top of the core.
-
-Short section description.
-
-=== product title="Web Components" package=@scope/web-component color=orange icon=webComponents href=/documentation/web-component
-
-Product description.
-
-=== product title=Router package=@scope/router color=cyan icon=router href=/documentation/router
-
-Product description.
-
-:::
-````
-
-Supported parts:
-
-- `header`: section eyebrow, heading, and intro copy.
-- `product`: repeated cards.
-
-Product options:
-
-- `title`: card title.
-- `package`: package label.
-- `color`: card color modifier. Existing CSS supports the orange/cyan style used by the template.
-- `icon`: icon name from `_layout-utils.js`.
-- `href`: link target.
-
-## `landing-features`
-
-Purpose: grid of feature cards.
-
-Syntax:
-
-```md
-::: layout landing-features
-
-=== header
-
-`// why this`
-
-## The platform is the framework.
-
-Short intro.
-
-=== feature icon=reactive
-
-### Reactive
-
-Feature copy.
-
-=== feature icon=tiny
-
-### Tiny
-
-Feature copy.
-
-:::
-```
-
-Supported parts:
-
-- `header`: section eyebrow, heading, and intro copy.
-- `feature`: repeated feature cards.
-
-Feature options:
-
-- `icon`: icon name from `_layout-utils.js`.
-
-Available icon names include:
-
-- `reactive`
-- `tiny`
-- `standards`
-- `plug`
-- `webComponents`
-- `surgical`
-- `router`
-- `terminal`
-- `book`
-- `arrowRight`
-- `arrowUpRight`
-- `sparkles`
-
-Unknown icon names fall back to `reactive`.
-
-## `landing-showcase`
-
-Purpose: interactive code example carousel.
-
-Syntax:
-
-````md
-::: layout landing-showcase
-
-=== header
-
-`// see it in action`
-
-## Looks like HTML.
-
-Short intro.
-
-=== example label="Todos + localStorage" color=orange filename=todos.js lang=javascript
-
-```javascript
-console.log('todo example')
-```
-````
-
-=== example label="Router" color=cyan filename=app.html lang=html
-
-```html
-<main></main>
-```
-
-:::
-
-````
-
-Supported parts:
-
-- `header`: carousel heading and intro.
-- `example`: repeated slides.
-
-Example options:
-
-- `label`: slide label.
-- `color`: label color modifier. The template uses orange/cyan.
-- `filename`: code snippet filename label.
-- `lang`: syntax label passed to the code snippet renderer.
-
-Scripts:
-
-- This layout emits markup with `data-fading-citrus-showcase`.
-- `template.config.js` includes the `showcase` script only on pages containing that marker.
-- The script handles previous/next buttons, dots, clones for looping, transition reset, and resize alignment.
-
-## `landing-install`
-
-Purpose: install command tab set with copy buttons.
-
-Syntax:
-
-```md
-::: layout landing-install
-
-=== header
-
-`// install`
-
-## Start in seconds.
-
-Choose your package manager.
-
-=== tab key=npm label=npm command="npm install package-name"
-
-npm install package-name
-
-=== tab key=yarn label=yarn command="yarn add package-name"
-
-yarn add package-name
-
-:::
-````
-
-Supported parts:
-
-- `header`: section heading and intro.
-- `tab`: repeated package manager tabs.
-
-Tab options:
-
-- `key`: tab id.
-- `label`: tab button label.
-- `command`: command copied to clipboard.
-
-Scripts:
-
-- This layout emits markup with `data-fading-citrus-install`.
-- `template.config.js` includes the `install` script only on pages containing that marker.
-- The script handles tab switching and command copy feedback.
-
-Current behavior:
-
-- The second tab is active by default.
-- Override `landing-install.js` if that default should be configurable.
-
-## `landing-cta`
-
-Purpose: final landing call-to-action section.
-
-Syntax:
-
-```md
-::: layout landing-cta title="Build with the platform." title2="Ship less JavaScript."
-
-=== copy
-
-Final CTA copy.
-
-:::
-```
-
-Supported layout options:
-
-- `title`: first heading segment.
-- `title2`: second heading segment.
-
-Supported parts:
-
-- `copy`: CTA body copy.
-
-Current behavior:
-
-- The CTA buttons link to `/documentation/get-started` and `/documentation/index.html?v=20260621exact`.
-- Override `landing-cta.js` if those links need to be configurable.
-
-## Code Snippets
-
-Code snippets are handled by:
-
-```txt
-layouts/_code-snippet.js
-```
-
-The template config overrides the default Markdown code renderer:
-
-```js
-markedOptions: {
-    renderer: {
-        code({ lang, raw }) {
-            return renderCodeBlock('', rawCode, lang)
-        },
-    },
-}
-```
-
-This means fenced code blocks render with:
-
-- a framed code panel
-- mac-style dots
-- filename area
-- language label
-- line numbers
-- syntax token styling
-- copy button
-
-Scripts:
-
-- Code snippets emit `code-copy-btn`.
-- `template.config.js` includes the `code-copy` script only on pages containing that marker.
-- The script uses the nearest `.code-snippet` container and copies the `data-code` value.
-
-## Theme Variables
-
-The template defines light and dark CSS variable maps in `template.config.js`.
-
-Primary variables:
-
-- `--background`
-- `--foreground`
-- `--card`
-- `--primary`
-- `--primary-glow`
-- `--primary-foreground`
-- `--secondary`
-- `--muted`
-- `--muted-foreground`
-- `--accent`
-- `--border`
-- `--ring`
-- `--code-bg`
-
-Syntax variables:
-
-- `--syntax-comment`
-- `--syntax-keyword`
-- `--syntax-string`
-- `--syntax-tag`
-- `--syntax-attr`
-
-Effect variables:
-
-- `--gradient-hero`
-- `--gradient-primary`
-- `--gradient-text`
-- `--gradient-border`
-- `--shadow-glow`
-- `--shadow-card`
-
-Override only values from a docs project:
-
-```js
-export default {
-    theme: {
-        light: {
-            '--primary': 'oklch(0.62 0.18 250)',
-        },
-        dark: {
-            '--primary': 'oklch(0.78 0.16 250)',
-        },
-    },
-}
-```
-
-Disable a mode by setting it to `false`:
-
-```js
-export default {
-    theme: {
-        light: false,
-    },
-}
-```
-
-With `light: false`, the dark variables become the default `:root` theme for this template and light-mode selectors are not emitted. This is useful for docs sites that should stay dark-only.
-
-Place that in:
-
-```txt
-docs/_template/template.config.js
-```
-
-## Assets
-
-The template includes only generic/shared assets. Product-specific logos, banners, screenshots, and icons should live in the docs source under `docs/_template/assets`.
-
-- `logo.svg`: compatibility fallback for the main site logo.
-- `logo.light.svg`: preferred logo on light backgrounds.
-- `logo.dark.svg`: preferred logo on dark backgrounds.
-- `favicon/*`: default favicons.
-- social icons: `medium2.svg`, `facebook.svg`, `instagram.svg`, `reddit.svg`, `twitter.svg`, `youtube.svg`.
-
-Override assets from a docs project by adding files at the same target path:
-
-```txt
-docs/_template/assets/logo.svg
-docs/_template/assets/logo.light.svg
-docs/_template/assets/logo.dark.svg
-docs/_template/assets/favicon/favicon.ico
-docs/_template/assets/site-image.jpg
-```
-
-Because `docs/_template/assets` is copied into `publicDir/assets` after template assets, source assets can replace template assets. If only `logo.svg` is present, builder copies it to missing `logo.light.svg` and `logo.dark.svg` files in the generated site so the header and footer do not request missing assets. Projects that need correct contrast should provide explicit light and dark variants.
-
-## Stylesheets
-
-Stylesheets shipped by the template:
-
-- `normalize.css`: baseline reset.
-- `fonts.css`: bundled font-face declarations.
-- `common.css`: shared header, footer, buttons, variables, and document primitives.
-- `landing.css`: landing page sections and responsive behavior.
-- `documentation.css`: documentation layout, article content, side nav, and table of contents.
-- `github-dark.hightlighter.css`
-- `github-light.hightlighter.css`
-- `hybrid.hightlighter.css`
-
-The page layouts currently include:
-
-- `landing.css` for `layout: landing`
-- `documentation.css` for `layout: document`
-- `theme.css` when theme variables are configured
-
-The landing and documentation stylesheets import or rely on the shared styles as authored in this template. If you override styles, preserve required class names or override the corresponding layout handlers.
-
-## Scripts
-
-Template scripts are registered by marker. The template renders `headScripts` inside `<head>` and `scripts` before `</body>`.
-
-```js
-scripts: {
-    'code-copy': {
-        match: 'code-copy-btn',
-        render: renderCodeCopyScript,
-    },
-    showcase: {
-        match: 'data-fading-citrus-showcase',
-        render: renderShowcaseScript,
-    },
-    install: {
-        match: 'data-fading-citrus-install',
-        render: renderInstallScript,
-    },
-}
-```
-
-This keeps pages from receiving scripts for layout parts they do not use.
-
-Disable a script from a docs project:
-
-```js
-export default {
-    scripts: {
-        showcase: false,
-    },
-}
-```
-
-Override a script:
-
-```js
-export default {
-    scripts: {
-        showcase: {
-            match: 'data-fading-citrus-showcase',
-            render: () =>
-                `<script type="application/javascript">/* custom */</script>`,
-        },
-    },
-}
-```
-
-## Extension Strategy
-
-Use the smallest override that solves the problem:
-
-1. Override assets for logos, favicons, images, and icons.
-2. Override `meta` fields for site identity and social card defaults.
-3. Override theme variables for color and surface tuning.
-4. Add Markdown layout handlers for new page sections.
-5. Override existing Markdown layout handlers only when the section HTML needs to change.
-6. Override `_header.js`, `_footer.js`, or `_head-meta.js` when navigation, footer copy, metadata shape, or brand assumptions need to change.
-7. Override `landing.js` or `document.js` only when the full page shell changes.
-
-Example docs extension:
-
-```txt
-docs/
-  index.md
-  _template/
-    template.config.js
-    assets/
-      logo.svg
-    layouts/
-      pricing-cards.js
-```
-
-```js
-// docs/_template/template.config.js
-import pricingCards from './layouts/pricing-cards.js'
-
-export default {
-    meta: {
-        siteName: 'Example',
-        title: 'Example by Before Semicolon',
-        description: 'Documentation for Example.',
-        image: '/assets/site-image.jpg',
-    },
-    markdownLayouts: {
-        'pricing-cards': pricingCards,
-    },
-    theme: {
-        light: {
-            '--primary': 'oklch(0.62 0.18 250)',
-        },
-        dark: {
-            '--primary': 'oklch(0.78 0.16 250)',
-        },
-    },
-}
-```
-
-## Minimal Landing Page
-
-````md
----
-title: Example
-description: Example documentation.
-layout: landing
----
-
-::: layout landing-hero title="Example Docs." title2="Built fast." primaryLabel="Read Docs" secondaryLabel="npm i example"
-
-=== copy
-
-Useful docs for a focused package.
-
-=== stat
-
-## Small
-
-runtime
-
-=== code filename=example.js lang=javascript
-
-```javascript
-import { example } from 'example'
-
-example()
-```
-````
-
-:::
-
-````
-
-## Minimal Documentation Page
-
-```md
----
-name: Get Started
-title: Get Started
-description: Install and use the package.
-layout: document
-order: 1
----
-
-# Get Started
-
-Install the package and render your first example.
-````
-
-For the default `document` layout, place documentation pages under `docs/documentation` so the side navigation can be generated from the `documentation` site map group.