Pages and Layouts

Copy Markdown View Source

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.html
---

# About

Routes 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 local component syntax (<.name>) 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.astral

Astral 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/*path

Bracket 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 string-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 live in the configured layouts directory. EEx layouts use @content where the page HTML should be inserted:

<!doctype html>
<html lang="en">
  <head>
    <title><%= @page.title || "My Site" %></title>
  </head>
  <body>
    <main data-route="<%= @route %>">
      <%= @content %>
    </main>
  </body>
</html>

Common assigns:

  • @content — rendered page HTML.
  • @page — current %Astral.Content{}.
  • @metadata — decoded frontmatter map.
  • @route — route path such as /about/.
  • @params — string-keyed route params for dynamic file routes.
  • @site — discovered %Astral.Site{}.
  • @collections — content entries grouped by collection name.
  • @entry — current collection entry, otherwise nil.
  • @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 .astral layout:

<head>
  <.base_head
    title={@page.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>