HTML Pages

Every .html file in a project is a page, a full document or a fragment; htmlpress reads both the same way. Its <title> and <meta name="…"> tags are its metadata, the keys Frontmatter lists, and the rest of its body is the content. A Markdown page is the same page, written in Markdown.

A page is plain HTML, and htmlpress does not restrict it: any element, attribute, inline SVG, <canvas>, <iframe>, custom element, style or script works as written. There is no templating language and no allow-list. Htmlpress wraps the page in the site's layout, so it gets the navigation, the theme and search, and leaves the rest to the browser.

That makes a page more than a document: a dashboard, a report, a slide deck or an interactive explorer is one .html file. See Examples for a dozen of them, each built on real public data.

A self-contained page

A page's own <style>, <script> and <link> are kept and added to the layout's head, after the theme. A fragment's are the ones before its first content; a full document's are its <head>.

<title>Counter</title>
<style>
  .counter button {
    border: 1px solid var(--htmlpress-border);
    background: var(--htmlpress-surface);
    color: var(--htmlpress-text);
  }
</style>
<script type="module">
  const button = document.querySelector(".counter button")
  let count = 0
  button.addEventListener("click", () => {
    button.textContent = `Clicked ${++count} times`
  })
</script>

<h1>Counter</h1>
<div class="counter">
  <button type="button">Click me</button>
</div>

Fitting the site

• Scope styles under one class. A page's CSS applies to the whole document, layout included, so prefix every rule with a class on the page's own root element, as .counter above.
• Use the theme tokens. Colors from --htmlpress-* tokens follow the light and dark theme and any override, with no media query of its own.
• Run scripts as modules. type="module" runs once the page is parsed and keeps its names out of the global scope.
• Prefer semantic elements. The theme already styles headings, tables, lists and forms; a page needs its own CSS only for what HTML has no element for.

What htmlpress changes

The content goes into the layout as written, except for these build-time passes:

• <h2> to <h6> without an id get one, and <h2> to <h4> fill the table of contents; see Headings.
• Links to a page's file become its URL, and relative URLs are resolved from the source file; see Links.
• <pre><code class="language-*"> is highlighted; see Code Blocks.
• In prose, bare URLs become links, :emoji: shortcodes emoji and $…$ math; see Advanced Syntax. Code, links, scripts, styles and any element with data-literal are left alone.
• htmlpress-* tags become components; see Rich Elements.

For a page that wants none of the site's chrome, such as a landing page, pick another layout with <meta name="layout">; see Frontmatter.