Astral discovers pages from the configured pages/ directory and renders them into static HTML routes.
Markdown pages
Markdown pages use MDEx and YAML frontmatter:
---
title: About
layout: default
---
# AboutRoutes are derived from file paths:
pages/index.md -> /
pages/about.md -> /about/
pages/blog/post.md -> /blog/post/Set permalink to override the route:
---
title: About
permalink: /about-us/
---Set layout: false to render a page without a layout.
Components in Markdown
Markdown pages and collection entries can use local .astral components through MDEx's HEEx integration:
# Project
<.callout>
This block is rendered by `components/callout.astral`.
</.callout>Components are discovered from the configured components/ directory, the same as .astral pages and layouts. Use HEEx component syntax (<.name>, or <Article.figure> for components/article/figure.astral) rather than MDX imports.
Assigns are available in Markdown with HEEx expression syntax. @entry is present for collection entry pages, and @entry.data contains schema-declared fields:
<p>{@metadata["title"]}</p>
<p>{@entry.data.title}</p>Prefer static Markdown heading text. Heading ids are generated by the Markdown parser before HEEx expressions are evaluated. See the Markdown, content, and data guide for the current boundary around MDX, Markdown imports, and remote Markdown.
HTML pages
Plain .html files in pages/ are supported for pages that do not need Markdown processing.
Custom 404 page
Create a root 404 page to customize the page that static hosts use for missing routes:
pages/404.md
pages/404.html
pages/404.astralAstral writes root 404 pages to dist/404.html, even though the route still matches /404/ like any other page. This mirrors the static-host convention used by Astro and common deployment providers.
In development, visiting /404 or /404/ renders the custom page with HTTP status 404.
Nested 404 pages are ordinary pages for now; only the root pages/404.* file gets the 404.html output convention.
Dynamic file routes
Use bracket segments for collection-backed dynamic pages:
pages/blog/[slug].astral -> /blog/:slug
pages/docs/[...path].md -> /docs/*pathBracket filenames are portable file-route sugar. Astral converts them to Elixir/Phoenix-style route patterns internally.
Dynamic page templates render once for each collection entry whose route matches the file route pattern. Route params are exposed as atom-keyed @params assigns. Use a collection schema for fields read from @entry.data:
<h1>{@entry.data.title}</h1>
<p>Slug: {@params.slug}</p><p>Path: {@params.path}</p>A dynamic file route overrides the default collection entry page for the same route, letting the page template own the final HTML.
Layouts
Layouts are .astral components in the configured layouts directory. A layout renders the page with render_slot(@inner_block):
<!-- layouts/default.astral -->
<!doctype html>
<html lang="en">
<head>
<title>{@title || "My Site"}</title>
</head>
<body>
<main data-route={@route}>
{render_slot(@inner_block)}
</main>
</body>
</html>Markdown and HTML pages are wrapped in a layout. They use the layout named by their frontmatter layout, then their collection's layout, then the site default from astral.config.exs. Names are paths in the layouts directory without the extension, such as default or blog/post. layout: false renders without one. A named layout that doesn't exist is an error; a missing site default renders the page without a layout.
.astral pages wrap themselves instead, as <Layouts.default {assigns}>...</Layouts.default>. See Astral templates.
Layouts receive these assigns from Markdown and HTML pages, and from .astral pages that pass {assigns}:
@title— the frontmatter title, or a title the page assigned, otherwisenil.@page— current%Astral.Content{}.@metadata— decoded frontmatter map.@route— route path such as/about/.@params— atom-keyed route params for dynamic file routes.@site— discovered%Astral.Site{}.@collections— content entries grouped by collection name.@entry— current collection entry, otherwisenil.@routes— generated routes.
Head metadata
Astral does not provide a built-in SEO metadata component. Use ordinary HTML in layouts, or create a local .astral component for shared head tags. The base_head name mirrors Astro's common BaseHead.astro pattern while avoiding a confusing <head><.head /></head> shape:
---
title = assigns[:title] || "My Site"
description = assigns[:description] || "Site description"
canonical = "#{String.trim_trailing(assigns[:site_url], "/")}#{assigns[:route]}"
assigns =
assigns
|> assign(:title, title)
|> assign(:description, description)
|> assign(:canonical, canonical)
---
<link rel="canonical" href={@canonical} />
<title>{@title}</title>
<meta name="description" content={@description} />
<meta property="og:title" content={@title} />
<meta property="og:description" content={@description} />Then call it from a layout:
<head>
<.base_head
title={@title || "My Site"}
description={@metadata["description"]}
route={@route}
site_url="https://example.com"
/>
</head>This keeps metadata as regular HTML instead of introducing a framework-level metadata API.
Heading anchors
Markdown headings get stable id attributes. Heading metadata is available as @page.headings for table-of-contents layouts:
<nav>
<%= for heading <- @page.headings do %>
<a href="#<%= heading.id %>"><%= heading.text %></a>
<% end %>
</nav>