Getting started
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..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.
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. 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 page.
head.htm— injected into<head>. Use it for meta tags, stylesheets, and scripts.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.
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
Exempt pages
Not every page belongs in the post list. Pages like "About" should exist on
the site but not show up alongside dated posts. Add their filenames to
_SITE_EXT_EXEMPT_EXTRA in the Makefile:
_SITE_EXT_EXEMPT_EXTRA ?= "about.htm"Exempt pages are built normally but excluded from the index listing and the Atom feed. They also don't display dates.
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.
Link posts
Not every post needs its own page. Adding a link header field
turns a post into a link post—it appears in the index list but points
to an external URL instead of a local page:
title: Some interesting article
link: https://example.com/article
<p>A comment about the article.</p>
In the post list, link posts get a
data-page-kind="link" attribute on their
<li> element, so you can visually distinguish them from
regular posts using CSS. In the Atom feed, link posts appear as entries with
the external URL but no inline content.
Atom feed
Webscite generates an Atom feed at /feed.atom automatically. It
includes every non-exempt post on your site. 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.