@beforesemicolon/builder 1.8.1 → 1.8.13

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

@@ -0,0 +1,770 @@
+# 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, a default `logo.svg`, and Before Semicolon brand assets.
+
+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
+    before-semicolon-logo.png
+    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` and a Before Semicolon credit asset at `/assets/before-semicolon-logo.png`.
+
+The current header and footer still include Before Semicolon and Markup-oriented links and copy. If a site needs fully different navigation, footer link groups, or legal copy, override `_header.js`, `_footer.js`, or the full page layouts from `docs/_template/layouts`.
+
+## 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 metadata helper is still Markup-specific.
+- It hardcodes the production site URL and some default titles/assets.
+- Override `_head-meta.js` in `docs/_template/layouts` for any non-Markup documentation site.
+
+## 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 `npm i @beforesemicolon/markup`.
+
+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 currently links to the Markup GitHub repository. Override `landing-hero.js` if that needs to be generic.
+
+## `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 a default asset set. Not all assets are generic; several exist because the template originally shipped with the Markup site.
+
+Generic or shared assets:
+
+- `logo.svg`: main site logo used by header and footer.
+- `before-semicolon-logo.png`: small footer credit mark.
+- `favicon/*`: default favicons.
+- social icons: `medium2.svg`, `facebook.svg`, `instagram.svg`, `reddit.svg`, `twitter.svg`, `youtube.svg`.
+
+Markup-specific assets still present:
+
+- `markup-banner.jpg`
+- `markup-essentials-training.jpg`
+- `markup-favicon.*`
+- `markup-logo*`
+- `client-server.svg`
+- `fast.svg`
+- `independent.svg`
+- `reactive.svg`
+- `simple.svg`
+- `small.svg`
+
+Override assets from a docs project by adding files at the same target path:
+
+```txt
+docs/_template/assets/logo.svg
+docs/_template/assets/favicon/favicon.ico
+docs/_template/assets/markup-banner.jpg
+```
+
+Because `docs/_template/assets` is copied into `publicDir/assets` after template assets, source assets can replace template assets.
+
+## 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:
+
+```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 theme variables for color and surface tuning.
+3. Add Markdown layout handlers for new page sections.
+4. Override existing Markdown layout handlers only when the section HTML needs to change.
+5. Override `_header.js`, `_footer.js`, or `_head-meta.js` when navigation, footer copy, metadata, or brand assumptions need to change.
+6. 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 {
+    markdownLayouts: {
+        'pricing-cards': pricingCards,
+    },
+    theme: {
+        light: {
+            '--primary': 'oklch(0.62 0.18 250)',
+        },
+        dark: {
+            '--primary': 'oklch(0.78 0.16 250)',
+        },
+    },
+}
+```
+
+## Known Template-Specific Assumptions
+
+Some template internals are still Markup or Before Semicolon oriented:
+
+- `_head-meta.js` has Markup-specific defaults and URLs.
+- `_header.js` has Markup-oriented GitHub and documentation links.
+- `_footer.js` has Before Semicolon social links, footer copy, and learning links.
+- `document.js` builds edit links against the Markup GitHub docs path.
+- Some landing layout handlers contain default labels or links aimed at Markup docs.
+- Several assets are Markup-specific.
+
+These are template defaults, not builder requirements. Override them from `docs/_template` for another documentation site.
+
+## 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.