Website

Website reference

Overview

A website is a collection of pages (HTML documents). A website is managed as a directory containing a configuration file in YAML (site.yaml) or JSON (site.json) format.

Directory structure

In the HyperTexting CMS, every website is a directory. The structure of website subdirectories and files to determine how the generated website content will be organized.

 1my-website/         # website directory
 2  site.yaml         # website configuration file
 3  content/          # website content subdirectory
 4    index.md        # URL: /index.html
 5    about/          # URL: /about/
 6      index.md      # URL: /about/index.html
 7      me.png        # URL: /about/me.png
 8    blog/           # URL: /blog/
 9      index.yaml    # URL: /blog/index.html
10      hello-world/  # URL: /blog/hello-world/
11        index.md    # URL: /blog/hello-world/index.html
12  static/           # website assets subdirectory
13      favicon.ico   # URL: /favicon.ico

For more information on how pages are managed, see the pages reference documentation.

Example

A HyperTexting CMS website configuration file.

 1---
 2base_url: https://hypertemplates.net
 3title: HyperTemplates
 4description: the pure-HTML templating system for the modern web.
 5author:
 6    username: "@hypertemplates.net"
 7    name: HyperTemplates
 8    href: /
 9    favicon: /img/favicon-512x512.png
10    email: [email protected]
11links:
12  - rel: apple-touch-icon
13    href: /img/apple-touch-icon.png
14    sizes: 180x180
15  - rel: icon
16    href: /img/apple-touch-icon.png
17    sizes: 180x180
18  - rel: icon
19    href: /img/favicon-128x128.png
20    sizes: 128x128
21  - rel: icon
22    href: /img/favicon-192x192.png
23    sizes: 192x192
24  - rel: icon
25    href: /img/favicon-256x256.png
26    sizes: 256x256
27  - rel: icon
28    href: /img/favicon-512x512.png
29    sizes: 512x512
30  - rel: me
31    href: https://github.com/hypertemplates
32  - rel: me
33    href: https://mastodon.social/@herdworks
34copyright: "2025"
35config:
36    tidy_mode: true
37    theme_dir: theme
38    tag_layout: tag
39provider:
40    kind: s3
41    endpoint: https://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.cloudflarestorage.com
42    store: hypertemplates-net
43    secrets:
44        - name: access_key_id
45          provider: env
46          key: AWS_ACCESS_KEY_ID
47        - name: secret_access_key
48          provider: env
49          key: AWS_SECRET_ACCESS_KEY

The website configuration file provides a standardized set of core properties for layout and theme developers.

Properties

site.base_url

The website URL.

site.title

The website title.

The site.title template data property should be used by theme developers as the default value for the <title> element.

Example

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

site.description

The website description.

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

Example

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

site.author

The website author.

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

Sample

site.yaml

 1---
 2title: HyperTemplates
 3description: the pure-HTML templating system for the modern web.
 4...: ...
 5author:
 6    username: "@hypertemplates.net"
 7    name: "HyperTemplates"
 8    href: "/"
 9    favicon: "/favicon.ico"
10    email: "[email protected]"

The site.author template data property should be used by theme developers as the default value for the <meta name='author'> element and related page metadata (e.g. OpenGraph Protocol).

Example

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

site.metadata

A list of website metadata properties.

Sample

site.yaml

 1---
 2title: HyperTemplates
 3description: the pure-HTML templating system for the modern web.
 4...: ...
 5metadata:
 6  - name: example
 7    content: example
 8  - property: og:type
 9    content: website
10  - property: og:url
11    content: https://hypertemplates.net/
12  - property: og:title
13    content: HyperTemplates
14  - property: og:description
15    content: the pure-HTML templating system for the modern web.

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

Example

1<meta ht-template='meta:site.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 site.metadata value.

site.links

A list of website links, or relationships, to other resources.

Sample

site.yaml

1---
2title: HyperTemplates
3description: the pure-HTML templating system for the modern web.
4...: ...
5links:
6  - rel: icon
7    href: /favicon.ico
8  - rel: me
9    href: https://mastodon.social/@calebhailey

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

1<link ht-template='link:site.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 site.links value.

Custom properties

All properties defined in site.yaml or site.json files are available as template data properties with the site. prefix.

Example

site.yaml

1---
2title: Example website
3description: Example website description
4...: ...
5banana: yellow

In this example, the banana property is available in layouts as the site.banana template data property.

Configuration

site.config

The website configuration.

All site.config properties have default values, so these only need to be added to site.yaml or site.json if a value other than the default is preferred.

Example

 1{
 2  site: {
 3    config: {
 4      builds_dir:  "builds",
 5      content_dir:  "content",
 6      data_dir:  "data",
 7      drafts_dir:  "drafts",
 8      static_dir:  "static",
 9      theme_dir:  "theme",
10      tag_layout: "default",
11      tag_path: "tags",
12      refresh_interval: 0,
13      tidy_mode: true
14      markdown: {
15        mentions: {
16          href_prefix: "/tags/",
17          href_suffix: "/"
18        }
19      }
20    }
21  }
22}

The site.config property is a key:value template data object containing the following properties:

• site.config.builds_dir (default: "builds")

  Configures the build output subdirectory.

• site.config.content_dir (default: "content")

  Configures the page content subdirectory.

• site.config.data_dir (default: "data")

  Configures the namespaced template data subdirectory.

• site.config.drafts_dir (default: "drafts")

  Configures the draft pages subdirectory.

• site.config.static_dir (default: "static")

  Configures the static assets subdirectory.

• site.config.theme_dir (default: "theme")

  Configures the theme subdirectory (e.g. layouts, theme assets, etc). Set site.config.theme_dir: "." to use the website root directory as the theme directory.

• site.config.tag_layout (default: "tag.html")

  See site.config.tag_layout below.

• site.config.refresh_interval (default: integer 0)

  See site.config.refresh_interval below.

• site.config.tidy_mode (default: boolean false)

  See site.config.tidy_mode below.

• site.config.markdown

  See site.config.markdown below.

The directory configuration settings provide HyperTemplates with instructions on where to look for the various

site.config.tag_layout

Configures the layout to use for automatically generated tag pages (default: "default").

site.config.tag_path

Configures the path prefix for auto-generated tag pages (default: "tag").

site.config.refresh_interval

Configures the page.refresh computed property interval for redirect pages.

site.config.tidy_mode

Configures whether template attributes should be removed from rendered pages. Set site.config.tidy_mode: true to strip all template attributes from generated HTML files.

site.config.markdown

The website markdown configuration.

Sample

 1{
 2  site: {
 3    config: {
 4      markdown: {
 5        mentions: {
 6          href_prefix: "/tags/"
 7          href_suffix: "/"
 8        }
 9      }
10    }
11  }
12}

The site.config.markdown property is a key:value template data object containing the following properties:

• site.config.markdown.mentions (default: {})
• site.config.markdown.mentions.href_prefix (default: "/tags/")
• site.config.markdown.mentions.href_suffix (default: "/")

NOTE: the href_prefix and href_suffix properties are used to configure the <a href> for hashtag links. Use href_prefix: "https://x.com/hashtag/" and href_suffix: "/" to create links to an external hashtag service.

Guides

Link Verification

How to configure link verification using rel="me" links.

Learn more