Skip to content

demo-guide.md

Latest commit

 

History

History
102 lines (65 loc) · 4.16 KB

demo-guide.md

File metadata and controls

102 lines (65 loc) · 4.16 KB

RadioStatic Demo Guide

This guide walks through the retro RadioStatic demo that ships with the repository. Follow it to generate the sample site locally, explore the output, and adapt the structure for your own projects.

Prerequisites

  • Node.js 18 or newer (the demo runs entirely on the command line—no extra services required)
  • npm for installing dependencies
  • Optional: make for the convenience targets

1. Install Dependencies

npm install

Installation is only required the first time you clone the repository (or after updating dependencies).

2. Build the Demo

./build-site.sh

The script wraps the generator CLI (static-sitegen/bin/radiostatic.js) and defaults to smoke-test.yaml. It validates the resulting files and prints a short listing from the output directory.

Custom Configuration Names

You can pass a different configuration file or choose a custom output directory:

./build-site.sh config/your-site.yaml public-site

The script also respects environment variables (new names listed first, legacy aliases still work):

  • RADIOSTATIC_CONFIG / SITEGEN_CONFIG – default config path (overridden by positional argument)
  • RADIOSTATIC_OUTPUT / SITEGEN_OUTPUT – default output directory
  • RADIOSTATIC_VERBOSE / SITEGEN_VERBOSE – set to 0 to suppress verbose logging

make build-local supports the same options:

make build-local CONFIG=config/your-site.yaml OUTPUT=public-site

3. Serve the Output

make serve-local

This runs python3 -m http.server 8080 inside the site-output/ directory so you can browse the generated pages at http://localhost:8080.

Stop the server with Ctrl+C when finished.

Demo Components

  • Configuration – smoke-test.yaml demonstrates every supported feature (home page hero, sections, blog, sitemap).
  • Blog content – content/blog/ contains Markdown posts for two sample authors (alex-lee and jamie-hart) plus a default article used by the blog landing page.
  • Assets – examples/demo-site/assets/ holds the CSS, JavaScript, SVG artwork, site.webmanifest, and robots.txt referenced by the demo configuration.
  • Stagit sample – examples/demo-site/stagit/ packages a small bare git repository and static HTML so you can illustrate a repository mirror alongside the site. Step-by-step integration lives in the Stagit section below.

Updating Assets

To experiment with the assets that ship inside static-sitegen/assets/, run:

./prepare-demo-assets.sh

The script mirrors examples/demo-site/assets/ into static-sitegen/assets/ (useful when tweaking the default theme). Pass a different source directory if you maintain your own asset pack:

./prepare-demo-assets.sh path/to/your-assets

Editing Content

  1. Duplicate a post in content/blog/ or create a new Markdown file.
  2. Update the front matter (title, slug, author, publishedAt, heroImage, etc.).
  3. Re-run ./build-site.sh (or make build-local) to regenerate the site.

Authors are configured in the YAML file under blog.authors. Add new entries to expose additional avatars, bios, and social links.

Stagit Demo

The demo includes:

  • examples/demo-site/stagit/repos/hello-world.git – a tiny bare repository with two commits.
  • examples/demo-site/stagit/html/ – placeholder HTML styled to resemble a stagit export.

smoke-test.yaml declares an extraCopies entry so the build automatically mirrors the HTML folder into site-output/stagit/. Replace these artifacts with real stagit output when you connect your own repositories or point the from path at your own build pipeline.

Next Steps

  • Read docs/configuration.md for a tour of the YAML keys and how they map to templates.
  • Update the navigation links, sections, and call-to-action blocks in your configuration file to match your project.
  • Swap the SVG artwork under examples/demo-site/assets/static/img/ and rerun the build.
  • Commit the resulting site-output/ directory to the platform of your choice or upload it to static hosting.

That’s it—you now have a working RadioStatic build and a clear path for customising it.