basic-ssg

Build static sites with Roc.

Discover content, render Markdown or AsciiDoc, compose typed HTML, and write the finished site — with one small platform.

Get started API docs

A complete site generator — renders every Markdown file in a content directory:

app [main!] { pf: platform "<basic-ssg release URL>" }

import pf.Path
import pf.OsStr exposing [OsStr]
import pf.SSG

main! : List(OsStr) => Try({}, [Exit(I32), PagesError(Str), ParseError(Str), WriteError(Str), ..])
main! = |args|
	match args.drop_first(1) {
		[input_dir_arg, output_dir_arg] => {
			input_dir = Path.from_os_str(input_dir_arg)
			output_dir = Path.from_os_str(output_dir_arg)

			pages = SSG.markdown_pages!(input_dir)?
			render_pages!(pages, output_dir)
		}

		_ => Err(Exit(1))
	}

render_pages! : List(SSG.Page), Path.Path => Try({}, [ParseError(Str), WriteError(Str), ..])
render_pages! = |pages, output_dir|
	match pages {
		[] => Ok({})
		[page, .. as rest] => {
			markdown_html = SSG.parse_markdown!(page.source_path)?
			page_html = "<!doctype html><html><body>${markdown_html}</body></html>"

			SSG.write_file!({
				output_dir,
				output_path: page.output_path,
				content: page_html,
			})?

			render_pages!(rest, output_dir)
		}
	}

Build it and point it at your content:

roc build site.roc --output=site
./site content/ www/

Get started

  1. Point at a release

    Copy the platform URL from the latest release into your app header. Releases ship native hosts for macOS, Linux, and Windows.

  2. Discover and render pages

    Use SSG.markdown_pages! for Markdown, SSG.asciidoc_pages! for AsciiDoc, or SSG.pages_with! for any other extension.

  3. Write typed HTML

    Build a document with Html, insert rendered fragments where you need them, and write it out with SSG.write_file!.

The quickest start is to copy the Orchard Guide example and replace its content with your own.

Examples

Orchard Guide

A complete site: nested Markdown and AsciiDoc pages, navigation, styling, and source inclusion.

View source →

Travel Journal

JSON and Markdown frontmatter in one build, with decoders and metadata types you define.

View source →

Article Inspector

A small command-line program that reads Markdown and reports the first article heading.

View source →

Reference