Site Factory

Build single-page websites from markdown content. Works out of the box with a neutral default brand, or optionally use a docs-factory brand kit for custom styling.

Workflow

Step 0: Choose Brand Slug

Ask the user for a brand slug (subdomain) and site name (URL path).

Suggest options based on context — e.g. bluewaves, mycompany, or something relevant to the content
Validate slug format: must match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, 1–63 characters
Validate site name format: lowercase letters, numbers, and hyphens only
Check availability:
```
python3 scripts/site_api.py info {brand} {site-name}
```
A 404 response means the name is available. Any other response means it's taken.
Confirm the chosen slug and site name with the user before proceeding

Step 1: Resolve Brand Kit (Optional)

By default, use the built-in neutral brand — skip directly to Step 3. The default brand uses a gray palette, system fonts, and the Bluewaves logo. See references/default-brand.md for details.

If the user explicitly requests a docs-factory brand kit, read its assets/manifest.json:

cat plugins/docs-factory/skills/brand-{BRAND}/assets/manifest.json

Available brand kits:

brand-bluewaves — Merriweather typography, brown sand primary (#B78A66)
brand-wave-artisans — Nunito Sans typography, gray minimalist palette
brand-decathlon — Inter typography, blue/purple primary (#3643BA)

Step 2: Map Design Tokens to CSS (Brand Kit Only)

Skip this step when using the default brand — values are already baked into skeleton.html.

When using a docs-factory brand kit, use references/tokens-to-css.md to map manifest.json tokens to CSS custom properties. Key mappings:

Token path	CSS property	Example
`tokens.colors.text-heading`	`--color-heading`	`#B78A66`
`tokens.colors.background-page`	`--bg-page`	`#FFFFFF`
`tokens.colors.highlight`	`--color-highlight`	`#FF375F`
`tokens.type_scale.h1.size_pt`	`--font-size-h1`	`43px` (32pt x 1.333)
`fonts.heading.bold`	`@font-face Brand-Heading`	`fonts/heading-bold.ttf`

Step 3: Generate HTML

Using references/skeleton.html as the template:

Default brand:

The :root block already contains hardcoded default values — no CSS overrides needed
Just fill the content placeholders: {{TITLE}}, {{BRAND_NAME}}, {{TOC_ITEMS}}, {{CONTENT}}, {{ATTACHMENT_ITEMS}}, {{DATE}} — {{TITLE}} is right-aligned in the header
Copy assets/default-logo.svg to build/assets/images/logo.svg

Brand kit override:

Replace the entire :root block with brand-specific CSS custom property values
Add @font-face blocks for the brand's custom fonts (heading, body, mono)
Update font-family declarations to reference "Brand-Heading", "Brand-Body", "Brand-Mono" with system font fallbacks
Copy the brand logo SVG to build/assets/images/logo.svg

Content structure (same for both paths):

Header: Logo (left) + document title (right)
Navigation: Auto-generated TOC from H2/H3 headings in the markdown
Main content: Convert markdown to HTML — use semantic tags (<h2>, <p>, <ul>, <table>, <pre><code>, <blockquote>)
Attachments sidebar: Download links for any attached files (PDFs, images, data files)
Footer: Small logo + brand name + current date

Step 4: Build Output Directory

Create a build/ directory with this structure:

Default brand:

build/
├── index.html          # Generated HTML with inline CSS
├── assets/
│   └── images/         # Content images + default-logo.svg as logo.svg
└── files/              # Downloadable attachments (PDFs, data files)

No fonts/ directory is needed — the default brand uses system fonts.

Brand kit:

build/
├── index.html          # Generated HTML with brand CSS overrides
├── assets/
│   ├── images/         # Content images + brand logo as logo.svg
│   └── fonts/          # Brand fonts (.ttf files from manifest)
└── files/              # Downloadable attachments (PDFs, data files)

Copy assets:

Logo: Default → assets/default-logo.svg; Brand kit → brand logo SVG from manifest
Fonts (brand kit only): Copy from brand kit assets/fonts/ to build/assets/fonts/
Images: Copy content images to build/assets/images/
Attachments: Copy any attached files to build/files/

Step 5: Verify

Check the build directory:

index.html exists and is valid HTML5
All referenced images and files are present
Default brand: No @font-face blocks, system fonts used, no build/assets/fonts/ directory
Brand kit: CSS custom properties populated with brand values, all referenced fonts present
TOC links match heading IDs
Responsive layout works (check @media queries in CSS)

Report the build directory contents and total size.

Output

The build/ directory is ready for publishing with site-publisher:

# Default brand (no --brand-kit flag)
python3 scripts/site_api.py publish ./build {brand} {site-name} --title "Document Title"

# With brand kit (optional)
python3 scripts/site_api.py publish ./build {brand} {site-name} --title "Document Title" --brand-kit path/to/manifest.json

Notes

The default brand requires zero external dependencies — works in standalone ZIP mode
When using a brand kit, all font files must be copied locally (no CDN references) for offline support
Images should be optimized before inclusion (reasonable file sizes)
The HTML is a single page with anchor-based navigation via TOC
CSS custom properties enable the login page to share brand colors

site-factory