# HTML Pages

> An .html page: a full document or a fragment, its head as metadata, and any element, style or script inside the site's layout.

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](/authoring/frontmatter/) lists, and the rest of its body is the content. A [Markdown page](/authoring/markdown-pages/) 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](/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>`.

```html
<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](/authoring/rich-elements/#theme-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](/authoring/headings/).
- Links to a page's file become its URL, and relative URLs are resolved from the source file; see [Links](/authoring/links/).
- `<pre><code class="language-*">` is highlighted; see [Code Blocks](/authoring/code-blocks/).
- In prose, bare URLs become links, `:emoji:` shortcodes emoji and `$…$` math; see [Advanced Syntax](/authoring/advanced-syntax/). Code, links, scripts, styles and any element with `data-literal` are left alone.
- `htmlpress-*` tags become components; see [Rich Elements](/authoring/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](/authoring/frontmatter/).