Skip to content

configuration.md

Latest commit

 

History

History
166 lines (130 loc) · 7.04 KB

configuration.md

File metadata and controls

166 lines (130 loc) · 7.04 KB

Configuration Reference

Use this document to map YAML keys to the templates and behaviours produced by RadioStatic. The examples below mirror the bundled demo (smoke-test.yaml).

Top-Level Keys

Key Purpose
title Default site title. Rendered in the <title> tag alongside the page title.
description Plain-text description used in meta tags.
assets Folder containing CSS, JS, images, and metadata files. Copied verbatim to the output.
templates Directory of EJS templates. Defaults to static-sitegen/templates/.
styles Array of CSS paths (relative to the generated HTML). assets/modern.css is auto-added.
extraCopies Array of {from, to} entries for copying additional directories into the output.
theme Object with mode, primary_color, secondary_color. Consumed by templates as CSS variables.
logo Path to the logo image displayed in the header.
favicon Optional favicon path. Falls back to the logo when omitted.
meta description and keywords fields override the default meta tags per page.
social_preview_image Path to an image used for social sharing metadata.
analytics_id Placeholder for analytics tooling. Included in templates for future extensions.

Terminal Console Options

To enable the terminal-style hero on a page, set the following keys either at the site level or per page/section:

Key Description
useCmHead Includes partials/cm-head.ejs. Loads fonts, console CSS, and terminal-console.js.
useCmConsole Injects the console markup (partials/cm-console.ejs).
cmTitle Heading displayed above the console.
cmTagline Subheading displayed under the heading.
cmImage Optional illustration rendered above the console (e.g., assets/static/img/site-logo.svg).
cmFooterText Footer text rendered by partials/cm-footer.ejs.

These keys retain the historical cm prefix for compatibility. The next iteration will introduce terminal* aliases.

index Block

Defines the home page when present.

index:
  title: Home
  useCmConsole: true
  hideTitle: true
  contentFont: modern-mono
  terminalStyle: true
  tagline: "Spin up the demo, then swap in your own assets."
  content: |
    Markdown or HTML rendered within the page body.
  cta:
    label: Visit the Blog
    href: blog.html

content supports Markdown and inline HTML. cta is optional and renders a single button.

sections

Each section becomes a standalone page under sections/{id}.html and can be linked from navigation or internal CTAs.

sections:
  - id: features
    heading: Features
    useCmHead: true
    cmImage: assets/static/img/hero-cards.svg
    content: |
      ## What Ships in the Demo
      ...
    columnLayout:
      enabled: true
      ratio: "15/85"
      leftContent: |
        ### Quick Links
        - [Blog](../blog.html)
      rightContent: |
        ## Customize Anything
        ...

columnLayout is optional. When enabled, the template renders the leftContent and rightContent blocks side by side.

pages

Additional standalone pages (other than the index and sections) can be defined under pages. The structure mirrors the index block, supporting title, slug, content, images, cta, and console flags.

Header & Footer

header:
  links:
    - label: Home
      href: index.html
    - label: Blog
      href: blog.html
    - label: Stagit Demo
      href: stagit/index.html

footer:
  text: "© 2025 RadioStatic Demo."
  links:
    - label: GitHub
      href: https://github.com/example

Links are rendered in order. Relative URLs are rewritten automatically for section pages.

Blog Configuration

blog:
  enabled: true
  title: "RadioStatic Blog"
  postsDir: content/blog
  outputDir: blog
  fragmentDir: blog/fragments
  indexTemplate: blog/index.ejs
  postTemplate: blog/post.ejs
  fragmentTemplate: blog/fragment.ejs
  index:
    heroTitle: "RadioStatic Blog"
    heroTagline: "Stories from the sample authors"
    defaultPostPath: content/blog/default-post.md
  authors:
    - id: alex-lee
      name: "Alex Lee"
      avatar: assets/static/img/avatar-alex.svg
      bio: "Designs interfaces for docs and guides."

Important details:

  • postsDir points to Markdown files with YAML front matter. Each post supports fields such as title, slug, author, summary, heroImage, publishedAt, updatedAt, readingMinutes, tags, and seoDescription.
  • defaultPostPath populates the initial feature post on the blog landing page.
  • authors defines reusable metadata for each author referenced in front matter.
  • Generated HTML pages land under outputDir with fragments stored in fragmentDir.

Sitemap

Use the sitemap key to control the generated sitemap page (not the XML sitemap). Common flags mirror the section configuration (useCmHead, hideTitle, etc.).

Copying Additional Directories

Use extraCopies when you want to mirror folders that are not referenced through the normal asset pipeline. Each entry expects a from (source directory relative to the repo) and to (target directory inside the output):

extraCopies:
  - from: examples/demo-site/stagit/html
    to: stagit

During the build the generator copies examples/demo-site/stagit/html to site-output/stagit/. This is how the demo ships a placeholder stagit mirror alongside the core site.

Environment Variables

  • RADIOSTATIC_CONFIG / SITEGEN_CONFIG, RADIOSTATIC_OUTPUT / SITEGEN_OUTPUT, RADIOSTATIC_VERBOSE / SITEGEN_VERBOSE – consumed by build-site.sh and make build-local.
  • ENABLE_DOOM_BUILD – optionally runs scripts/build-doom.sh before generating the site.

Tips

  • Asset paths in YAML are relative to the project root at build time. When you deploy, they become relative to the generated HTML.
  • Use ../ prefixes inside Markdown when referencing assets from section pages (the generator resolves them automatically for blog posts).
  • Keep filenames kebab-cased to match template expectations and avoid surprises on case-sensitive filesystems.

Have a configuration question that is not covered here? Add an example to this document as you extend the generator.