Pages reference

Overview

A page is a directory containing an index file in Markdown (index.md), YAML (index.yaml), or JSON (index.json) format.

Directory structure

In the HyperTexting CMS, every page is a directory. Each page directory must contain an index file in markdown, YAML, or JSON format. Any file in a page directory that is not the index file is a page asset.

 1my-website/         # website directory
 2  site.yaml         # website configuration file
 3  content/          # website content directory
 4    index.md        # Page:  /
 5    about/          # 
 6      index.md      # Page:  /about/
 7      me.png        # Asset: /about/me.png
 8    blog/           # 
 9      index.yaml    # Page:  /blog/
10      hello-world/  # 
11        index.md    # Page:  /blog/hello-world/
12        cover.png   # Asset: /blog/hello-world/cover.png

Example

An example page content file in Markdown format.

content/blog/introducing-hypertemplates/index.md 
 1---
 2created_at: 2025-02-04T12:00:00-08:00
 3updated_at: 2025-02-04T12:00:00-08:00
 4layout: post
 5title: Introducing HyperTemplates
 6description: The pure-HTML templating system for the modern web.
 7tags:
 8    - blog
 9---
10
11## Introducing HyperTemplates
12
13Two things happen very early on in a persons journey to learn HTML – they create their first web page (!), and eventually they create a second.
14The moment that second page exists, the seemingly simple journey becomes a _lifelong quest_ to find the best templating system to keep some portion of two or more web pages in sync.
15
16If you have discovered templating solutions you actually enjoy using, this post might not interest you, and that is OK!
17For everyone else, welcome.

The page content file provides a standardized set of core properties for layout and theme developers.

NOTE: the contents of a page content file are available as template data properties with the page. prefix.

Properties

All properties are string data types unless otherwise noted.

page.created_at
The page creation date in RFC3339 format.

Example

1created_at: "2025-05-19T22:00:00Z"
page.updated_at
The page modified date in RFC3339 format.

Example

1updated_at: "2025-05-19T22:00:00-07:00"
page.layout
The page layout.

Page layouts may be defined with or without the .html extension.

Example

content/index.md 
1---
2created_at: "2025-05-19T22:00:00-07:00"
3layout: home.html
4title: HyperTemplates
5description: the pure-HTML templating system for the modern web.
6---

In this example, the value layout: home.html is equivalent to the value of layout: home.

BUY WHY?! Because HyperTemplates layouts are always HTML files, so we HyperTemplates will always assume the .html file extension.
page.path
The page URL path.

The page.path property is effectively equivalent to the Javascript URL.pathname property.

Example

1path: "/blog/introducing-hypertemplates/"

NOTE: page.path is a computed property. It is generated by HyperTemplates and made available for templating purposes only. If this value is present in a page index file, it will be overwritten.
page.author
The page author.

The page.author property is a key-value object with the following properties: username, name, href, favicon, and email.

Sample

content/blog/introducing-hypertemplates 
 1---
 2created_at: 2025-04-14T12:00:00-08:00
 3updated_at: 2025-04-14T12:00:00-08:00
 4layout: post
 5title: Introducing HyperTemplates
 6description: The pure-HTML templating system for the modern web.
 7author:
 8    username: "@calebhailey.com"
 9    name: "Caleb Hailey"
10    href: "https://calebhailey.com"
11    favicon: "https://calebhailey.com/favicon.ico"
12---
13
14## Introducing HyperTemplates
15
16...

The site.author template data property should be used by layout and theme developers as the default value for the <meta name='author'> element.

Example

1<meta name='author' ht-attrs='content:page.author.name,site.author.name'>
page.title
The page title.

The page.title template data property should be used by layout and theme developers as a value for the <title> element.

Example

1<title ht-content='page.title,site.title'></title>
page.description
The page description.

The page.description template data property should be used by layout and theme developers as the default value for the <meta name='description'> element.

Example

1<meta name='description' ht-attrs='content:page.description,site.description'>
page.content
The page content.

The page.content property should be used by layout and theme developers as the default value for the primary content element of a given page.

Sample

content/blog/hello-world/index.md 
1---
2created_at: "2025-05-19T22:00:00-07:00"
3layout: post.html
4title: Hello, world
5---
6
7## Hello, world
8
9My name is [Caleb](/about/). :wave:

In this sample, the page index file is in Markdown format (i.e. index.md). The page.content property of pages with Markdown index files will contain the rendered HTML of the Markdown file body (i.e. the contents of the file sans frontmatter).

1{
2  page: {
3      created_at: "2025-05-19T22:00:00-07:00"
4      layout: "post.html",
5      title: "Hello, world",
6      content: "<h2>Hello, world</h2>\n<p>My name is <a href='/about/'>Caleb</a>. 👋"
7  }
8}

See the HyperTemplates Markdown reference for more information.

page.summary
The page summary.

The page.summary property should be used by layout and theme developers as page previews (e.g. in feed layouts and/or page metadata).

The <!--more--> comment and page.summary

The HyperTemplate markdown processor will automatically generate a page.summary property for Markdown files that contain a <!--more--> HTML comment. HyperTemplates uses the content before the <!--more--> comment as the page.summary property.

NOTE: setting page.summary in a page index file overwites automatically generated <!--more--> summaries.
page.more
The remainder of the page content following a <!--more--> comment.

The page.more property is a computed property for layouts that want to separate content "above the fold" from content "below the fold".

The <!--more--> comment and page.more

The HyperTemplate markdown processor will automatically generate a page.more property for Markdown files that contain a <!--more--> HTML comment. HyperTemplates will use the content after the <!--more--> comment as the page.more property.
page.metadata
A list of page metadata properties.

Sample

content/about/index.md 
 1---
 2title: About Herd Works
 3description: Learn more about Herd Works, the makers of HyperTemplates.
 4...: ...
 5metadata:
 6  - property: og:url
 7    content: https://herd.works/about/
 8  - property: og:title
 9    content: About Herd Works
10  - property: og:description
11    content: Learn more about Herd Works, the makers of HyperTemplates.
12  - name: twitter:card
13    content: summary
14  - name: twitter:title
15    content: About Herd Works
16  - name: twitter:description
17    content: Learn more about Herd Works, the makers of HyperTemplates.
18  - name: twitter:site
19    content: @herdworks
20  - name: twitter:creator
21    content: @herdworks
22---
23
24## About Herd Works

The page.metadata template data property should be used by theme developers as a default source for <meta> elements.

Example

1<meta ht-template='meta:page.metadata' ht-attrs='name:meta.name; property:meta.property; content:meta.content'>

See the HTML <meta> attributes reference documentation for more information on the supported properties of a page.metadata value.
page.links
A list of page links, or [relationships], to other resources.

Sample

content/about/index.md 
 1---
 2title: About Herd Works
 3description: Learn more about Herd Works, the makers of HyperTemplates.
 4...: ...
 5links:
 6  - rel: me
 7    href: https://github.com/herdworks
 8  - rel: me
 9    content: https://mastodon.social/@herdworks
10---
11
12## About Herd Works

The page.links template data property should be used by theme developers as a source for <link> elements.

1<link ht-template='link:page.links' ht-attrs='rel:link.rel; href:link.href; type:link.type; sizes:link.sizes'>

See the HTML <link> attributes reference documentation for more information on the supported properties of a page.links value.
page.tags
The page tags.

The page.tags property should be configured as an array of strings. Page tags are primarily used for aggregating pages into one or more feeds. To learn more about feed pages, please visit the feeds reference documentation.

Sample

content/blog/hello-world/index.md 
 1---
 2created_at: "2025-05-19T22:00:00-07:00"
 3title: Hello, world
 4tags:
 5  - blog
 6  - announcement
 7  - example
 8---
 9
10## Hello, world
11
12...
page.redirect
The page.redirect property is used to indicate that a page should redirect to another URL.

Samples

content/jobs/index.md 
1---
2created_at: "2025-05-19T22:00:00-07:00"
3title: Jobs
4redirect: /careers/
5---
content/livestream/index.md 
1---
2created_at: "2025-05-19T22:00:00-07:00"
3title: Livestream
4redirect: https://youtube.com/xxxxxxxxxx
5---

The page.redirect property is used by HyperTemplates to generate the page.refresh computed property (see below).

page.refresh
The page.refresh property is a computed property used for configuring redirects.

The page.refresh property should be used by layout and theme developers as the default value for HTML redirects.

Example

redirect.html 
1<meta http-equiv="refresh" content="0; url=/" ht-attrs='content:page.refresh' />
page.assets
A list of asset file names.

Sample

1{
2  page: {
3    assets: [ "cover.jpg", "page.js" ]
4  }
5}

The page.assets property should be used by layout and theme developers for conditional layout features that may be triggered by the presence of a page asset (e.g. showing a cover image).

Example

1<header>
2  <img ht-template='asset:page.assets' ht-if='asset==cover.png,cover.jpg,cover.jpeg' src='asset' alt='Cover image' />
3  <h1 ht-content='page.title'></h1>
4</header>

In this example, a header cover image is only displayed if an asset named cover.png, cover.jpg, or cover.jpeg is displayed.

1<script ht-template='asset:page.assets' ht-if='asset==page.js' src='asset' defer></script>

In this example, a <script> tag is only added if an asset named page.js is present. We're big fans of tossing this snippet in our <footer> layouts to dynamically load one-off scripts for individual marketing pages or blog posts. 🤌

page.attachments
A list of page attachments.

The page.attachments property is an array of template data objects, each containing at minimum three fields: href, kind, and metadata. The attachment metadata is itself a template data object containing key:value properties describing the attachment.

Sample

 1{
 2  page: {
 3    attachments: [
 4      {
 5        href: "/video/introducing-hypertemplates.mp4",
 6        kind: "video",
 7        metadata: {}
 8      }
 9    ]
10  }
11}

To learn more about attachments, see the attachments reference.

The page.attachments property should be used by layout and theme developers to display featured attachments (video embeds, link previews, etc).

Example

1<attachment-gallery ht-template='attachment:page.attachments'>
2  <link-attachment ht-if='attachment.kind==link'></link-attachment>
3  <video-attachment ht-if='attachment.kind==video'></video-attachment>
4  <image-attachment ht-if='attachment.kind==image'></image-attachment>
5  <audio-attachment ht-if='attachment.kind==audio'></audio-attachment>
6  <file-attachment ht-if='attachment.kind==file'></file-attachment>
7</attachment-gallery>
page.draft
The page.draft boolean property is used to determine whether a page is generated during a build.

Set draft: true to disable publishing.

Sample

content/blog/hello-world/index.md 
1---
2created_at: "2025-05-19T22:00:00-07:00"
3title: Hello, world
4draft: true
5---
6
7## Hello, world
8
9...

NEW: the page.draft property is available in hyperctl version 0.17.2 and later.
page.unlisted
The page.unlisted boolean property is used to determine whether a page is included in a feed.

Set unlisted: true to exclude a page from all feeds.

Sample

content/newsletter/2025-community-event/index.md 
 1---
 2created_at: "2025-05-19T22:00:00-07:00"
 3title: 2025 community event
 4unlisted: true
 5tags:
 6  - newsletter
 7  - announcement
 8---
 9
10## 2025 community event
11
12...
page.feed
The page feed configuration.

Sample

 1{
 2  page: {
 3    feed: {
 4      title: "The HyperTemplates Blog",
 5      description: "Stay up-to-date with the latest HyperTemplates news.",
 6      author: {},
 7      tags: [],
 8      paths: [],
 9      pages: []
10    }
11  }
12}

The page.feed property is a template data object containing the following properties:

  • page.feed.title (default: "" - no title)

    If left blank, the value for page.title will be used.

  • page.feed.description (default: "" - no description)

    If left blank, the value for page.description will be used.

  • page.feed.author (default: {} - no author)

    If left blank, the value for page.author will be used.

  • page.feed.tags (default: [])

    Configure page.feed.tags with an array of string tag values to include pages with one or more matching tags.

  • page.feed.paths (default: [])

    Configure page.feed.paths with an array of regular expression strings to include pages with a matching path.

  • page.feed.pages (a computed property)

    See the page.feed.pages reference, below.

Examples

content/blog/index.md 
1---
2created_at: 2025-05-20T14:00:00-07:00
3title: The HyperTemplates Blog
4feed:
5  paths:
6    - /blog/*
7---

In this example, a feed page has been configured to include pages with a path that matches the /blog/* regular expression.

NOTE: this example was abbreviated to /blog/* for simplicity, but it is effectively equivalent to */blog/* which might yield unexpected results. To restrict this feed to pages with paths that begin with /blog/* the ^/blog/* pattern is recommended, as the carat (^) symbol matches on the beginning of a text or line.

See the Google RE2 syntax reference for more information.

 content/releases/index.md 
1---
2created_at: 2025-05-20T14:00:00-07:00
3title: HyperTemplates CLI Release Notes
4feed:
5  tags:
6    - release
7    - releases
8    - release-notes
9---

In this example, a feed page has been configured to include pages with the release, releases, or release-notes tag.

page.feed.pages
A list of pages matching one or more feed filters (page.feed.tags or page.feed.paths).

The page.feed.pages property should be used by layout and theme developers for generating feed pages.

Example

theme/partials/feed.html 
 1<section id='feed'>
 2    <feed-entry ht-template='entry:page.feed.pages'>
 3        <post-metadata>
 4            <h4 ht-content='entry.title' ht-if='entry.title'></h4>
 5            <time ht-attrs='datetime:entry.updated_at,entry.created_at' ht-content='entry.updated_at,entry.created_at'></time>
 6        </post-metadata>
 7        <post-summary ht-content='markdown:entry.summary,entry.content'></post-summary>
 8        <learn-more ht-block ht-attrs='href:entry.path' label='Continue reading'></learn-more>
 9    </feed-entry>
10</section>

In this example layout partial we've configured a feed page that will display the title, date, summary, and a "continue reading" link that links to the matching page. Pretty simple!

Custom properties
All properties defined in page index files are available as template data properties with the page. prefix.

Example

content/about/index.md 
 1---
 2created_at: 2025-05-20T15:00:00-07:00
 3title: About Herd Works
 4description: Learn more about Herd Works, the makers of HyperTemplates
 5...: ...
 6social:
 7  youtube: https://youtube.com/herdworks
 8  instagram: https://instagram.com/herdworks
 9  twitter: https://twitter.com/herdworks
10---
11
12### About Herd Works

In this example, the social properties are available in [layouts] as the page.social.youtube, page.social.instagram, and page.social.twitter template data properties.

Guides

Add a blog page
Create your first blog using feed pages! Learn more

💬 Join the community

Stay up-to-date with the latest releases and other news from the Team behind HyperTemplates. Ask the developers questions, get help from the community, and share your creations! 🎨