Getting started

Mar 03, 2026

Webscite needs two things to build a site: a content/ directory tracked by Git, and at least one file inside it called index.htm which will serve as the entry point for our website.The .htm extension is deliberate. Historically, it denoted HTML files on MS-DOS and still has good editor support today. We use the three-letter form to signal that these are not yet complete HTML documents. Footnotes or a table of contents like the one shown above can be generated using simple web components. So, contrary to the phrase proudly displayed on similar minimalist-looking blogs: This website proudly serves JavaScript.

Any file with a .htm extension inside content/ will be processed into a full HTML page. Everything else—CSS, JavaScript, images—is copied through as-is.

A minimal valid example page looks like this:

  title: My First Post

  <p>Hello from webscite.</p>

Each .htm file starts with a couple of newline delimited header lines. The title field is required; the remaining fields are described further below. After the headers and a blank line, the rest of the file is plain HTML that forms the body of your post.

To build your site, run:

make build

The generated files end up in docs/ by default. Open docs/index.html in a browser and you should see your index page along with a list of posts.

Important: Webscite derives all post metadata from Git. A .htm file that has not been committed will still be built into an HTML page, but it will be labeled "DRAFT" and have no date. To publish a post properly you must git commit it. The creation date is taken from the file's first commit, and the modification date from its most recent.

Building blocks

Files inside content/blocks/ act as shared templates that get included in every generated page. Three blocks are supported:

head.htm — injected into <head>. Use it for meta tags, stylesheets, and scripts. This is the only one of the three that is required; a build without it fails.
header.htm — placed at the top of <body>. Good for a navigation bar using the <site-menu> custom element.
footer.htm — placed at the bottom. Useful for links to your RSS feed or other site-wide content.

Unlike head.htm, the header and footer are not included everywhere. Which pages get them is decided per page through the fields described next.

Page headers

Apart from title, the header accepts five boolean fields. Each takes yes/y or no/n, case-insensitive. An unknown key or an unrecognized value aborts the build.

Field	Default	Effect
`is_post`	`yes`	Wrap the content in an `<article>` tag and list the page in the Atom feed.
`include_title`	`yes`	Render the title as an `<h1>` above the content.
`include_date`	`yes`	Render the creation date, followed by the modification date if the file has been changed since.
`include_header`	`no`	Include `blocks/header.htm`.
`include_footer`	`no`	Include `blocks/footer.htm`.

Every page is a post by default, so a file that declares nothing but a title gets an <h1>, a date and a feed entry, and no site header or footer. Writing is_post: no flips all four include_ defaults at once: title and date off, header and footer on:

  title: Home
  is_post: no

  <p>Hello from webscite.</p>

The fields are applied in the order they appear, so an include_ line only sticks if it comes after is_post. The posts here follow their title with include_footer: yes to keep the site-wide navigation without pulling in a second <h1> from the header block.

Configuration

The build is driven by a Makefile with overridable variables for things like source and output directories, site title, author name, and domain. See the Makefile itself for the full list of options and their defaults.

Special Pages

Drafts

Any .htm files placed in content/drafts/ are ignored during the build. Use this directory to keep work-in-progress posts out of your published site.

Atom feed

Webscite generates an Atom feed at /feed.atom automatically. It includes every page that is a post, which is every page that does not carry an is_post: no header. Feed metadata like title, author, and domain are configured through the Makefile. The feed also requires a unique UUID that stays the same even if your domain changes. Webscite combines it with your host and a site creation date into a TAG URI for the feed's <id> element, which is how feed readers tell your feed apart from every other feed on the web.