Pages

Each Markdown file in a version's content directory is a page:

---
title: Installation
description: Install the project and run your first example.
id: install
aliases: [/getting-started/]
---
# Installation

[Code blocks](04.code-blocks.md)

<link rel="component" href="@/app/components/counter.html">

<demo-counter></demo-counter>

URLs and order

01.guide/02.install.md becomes /guide/install/ in the current documentation. Numeric prefixes order MarkupKit navigation and disappear from URLs. Historical versions use paths such as /v/1.2.3/guide/install/ (see Versions). Changing 02. to 10. changes ordering without changing the path. Duplicate paths or document IDs fail with both source filenames.

Number prefixes order pages, and order front matter takes the place of a file's prefix: order: 2 on install.md orders it as 02.install.md would. Pages with the same number sort by name.

Raw HTML and components

Markdown text and code examples are literal, including braces and component syntax. Native HTML can contain Markdown under Expressmark's standard rules.

Import components from external .html files and consume them with ordinary tags and attributes (see Components). The imported file owns its definition and bindings.

@/ names the project root: <link rel="component" href="@/app/components/counter.html"> imports that file from any page, however deep. Other resource links resolve relative to the Markdown file.

Explicit <title>, <meta> and non-component <link> elements become head declarations in the page component's <defs>; an explicit <title> takes the place of the generated one. A <link rel="stylesheet"> becomes an @import in the page component's <style>, so it styles that page as the page's own CSS. Any other <link> that is not a head declaration, such as rel="pingback", fails with HTML Next's HC025.

Headings

Every heading has an anchor, derived by Expressmark: the text is normalized to NFC and lowercased, letters, numbers and combining marks in any script stay, and every other run of characters becomes one hyphen. "Über uns" is über-uns, "設定 と 使い方" is 設定-と-使い方, and a duplicate takes the first free suffix (installation-1). ## Setup {#install} sets the ID to install and removes the marker from the heading. A custom ID is reserved for its heading, so a generated ID skips it.

Links and assets

• A relative .md link resolves to the corresponding document in the same version, keeping its fragment and query. A link to a missing .md document fails when its page compiles, in dev as in build, naming the Markdown file.
• A relative link with no extension is a page path from the Markdown file's folder, as its URL reads: ./install and ./install/ name install.md or 02.install.md, ../reference/ names that folder's index page, and number prefixes may be left out. A path naming no page fails the same way.
• A link starting with / is a page path in the page's version, as in the footer and the nav option, so [Tokens](/tokens/) opens /tokens/ for the current docs or /v/<id>/tokens/ for a historical version, under the deployment base. With markdown() alone it is a path under the base.
• A root-relative link naming a file, such as /report.pdf, is a file in the public directory, as an image path starting with / is.
• Relative assets are copied into the build. Remote links stay as written.

build checks every link it writes; see Configuration.