Markdown Pages

A .md file is a page too. It is served where its .html twin would be, guide.md at /guide/, and goes through the same build as an HTML page: components, math, code blocks, includes, the table of contents and the Markdown copy for agents.

---
title: Getting started
description: Install and run it in a minute.
order: 1
---

# Getting started

Install it, then build the docs:

```sh title="Terminal"
npx gethtmlpress build docs
```

The Markdown is GitHub's: tables, task lists, strikethrough, footnotes and bare links. Raw HTML works as in any page, so an htmlpress-* component can be written as a tag, with Markdown inside it after a blank line.

Frontmatter

The YAML at the top of the file sets what an HTML page sets in its <head>, under the same names: title, description, order, label, icon, layout, sidebar, breadcrumbs, toc, date, author, keywords, image, language, path, source-url and source-action, as described in Frontmatter. author and keywords take a list, and head is raw HTML added to the page's <head>:

title: Release notes
author: [Ann, Bo]
keywords: [release, notes]
head: <link rel="alternate" type="application/rss+xml" href="/feed.xml">

Any other key fails the build, so a typo never passes for metadata.

Components

A directive is a component: :::name wraps a block, ::name stands on a line of its own and :name[label] sits inside text. Attributes go in braces. The directives are Livemark's, so a Livemark page reads the same here.

:::warning[Back up first]
The build wipes its output folder.
:::

:::card{title="Install" href="/install/" icon="rocket"}
One command.
:::

The API is :badge[beta]{variant="warning"}.

### Write a page [step]

:::note, tip, info, warning and danger are callouts, a label their title, and so is a GitHub alert, > [!NOTE]. :::card, :::column and :::tab in a row group into cards, columns and tabs; :::details, :::filetree, ::button, ::toc, ::video{type="youtube"}, ::audio{type="soundcloud"}, :badge, :icon and :abbr are the rest. A heading takes {#id}, [step], [!toc] (listed nowhere) and [toc] (listed only). Any other directive is the component of that name, the project's own too; a block one that names no component fails the build, and inside text something like note:important stays text.

Code blocks

A fence's language highlights it, and what follows the language takes the code block attributes without their data-: title, collapse, lines, line-numbers, add, remove, focus, error, warning and words.

```js title="build.js" lines="2" line-numbers
import { build } from "htmlpress"
await build("docs")
```

Math, emoji and links

$…$ and $$…$$ are math, and :rocket: shortcodes are emoji, as in an HTML page. Link to another page by its file, [Setup](setup.md), and the link takes the page's URL.

Which files are pages

Without an include, every .html and .md file in the project is a page, a README.md too. Exclude what is not a page in the configuration file. These files are never pages:

• an .md beside its .html page, which is that page's own Markdown copy for agents, published instead of the generated one;
• an .md that a page includes with <htmlpress-include>, a partial, whose directives and code blocks work as in a page;
• a changelog section's source, which its own pages show;
• the agent skills that skills names.