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.

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

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

NOTE: the contents of the website configuration file are available as template data properties with the site. prefix. See custom properties for more information.

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.byline
The website author.

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

Sample

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

The site.byline 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.byline.name,site.byline.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.
site.config
Website configuration settings.

Sample

site.yaml 
1---
2title: HyperTemplates
3description: the pure-HTML templating system for the modern web.
4...: ...
5config:
6  builds_dir: .builds
7  theme: themes/ht/theme.json
8  tag_layout: tag.html

See Configuration for more information.

site.providers
A list of named hosting provider configurations.

Sample

site.yaml 
 1---
 2title: HyperTemplates
 3description: the pure-HTML templating system for the modern web.
 4...: ...
 5providers:
 6  default:
 7    kind: s3
 8    base_url: https://hypertemplates.net
 9    endpoint: https://5a8b6c901ff20ee02892cf121b1ead54.r2.cloudflarestorage.com
10    config:
11      bucket: hypertemplates-web-prod
12    exclude:
13      paths:
14        - '(^|/)\.DS_Store$'
15    secrets:
16      - name: access_key_id
17        key: AWS_ACCESS_KEY_ID
18      - name: secret_access_key
19        key: AWS_SECRET_ACCESS_KEY

See Hosting Providers for more information.

site.environments
A list of named hosting environments.

Sample

site.yaml 
1---
2title: HyperTemplates
3description: the pure-HTML templating system for the modern web.
4...: ...
5environments:
6  default: [s3, cdn]
7  production: [s3, cdn]
8  staging: [github]

See Hosting Environments for more information.

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.builds_dir
The build output directory (default: "builds").
site.config.data_dir
The namespaced template data subdirectory (default: "data").
site.config.content_dir
The content directory (default: "content").
site.config.layouts_dir
The layouts subdirectory (default: "layouts").
site.config.fragments_dir
The fragments subdirectory (default: "fragments").
site.config.static_dir
The static assets subdirectory (default: "static").
site.config.plugins_dir
The template variable plugins subdirectory (default: "plugins").
site.config.themes_dir
The themes subdirectory (default: "themes").
site.config.theme
The active [theme] (default: "./theme.json").

Set site.config.theme: "./theme." to use the website root directory as the theme directory.

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.tidy_mode
Configures whether template directives should be removed from rendered pages. Set site.config.tidy_mode: true to strip all template directives from generated HTML files.
site.config.markdown
The website markdown configuration.

Sample

site.yaml 
1---
2title: HyperTemplates
3description: the pure-HTML templating system for the modern web.
4...: ...
5config:
6  markdown:
7    mentions:
8      href_prefix: /tags/
9      href_suffix: /

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

  • mentions (default: {})
  • mentions.href_prefix (default: "/tags/")
  • 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.

Hosting Providers

site.providers.<name>
Hosting providers are named using a template data key.

Sample

site.yaml 
 1---
 2title: HyperTemplates
 3description: the pure-HTML templating system for the modern web.
 4...: ...
 5providers:
 6  github:
 7    kind: git
 8    endpoint: [email protected]:herdworks/hypertemplates-web.git
 9    config:
10      branch: gh-pages
11      publish_dir: .
12    secrets:
13      - name: ssh_private_key
14        key: GH_PRIVATE_KEY

In this this example, we have configured a provider named github.

site.providers.<name>.kind
The hosting provider kind (required).

Supported provider kinds:

  • s3
  • git
site.providers.<name>.endpoint
The hosting provider endpoint (required).

All hosting providers require an endpoint URL.

site.providers.<name>.config
Provider-specific configuration settings (optional).

Examples

 1providers:
 2  cloudflare_r2:
 3    kind: s3
 4    endpoint: https://xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.r2.cloudflarestorage.com
 5    config:
 6      bucket: my-website
 7    secets:
 8      - name: access_key_id
 9        key: AWS_ACCESS_KEY_ID
10      - name: secret_access_key
11        key: AWS_SECRET_ACCESS_KEY
site.providers.<name>.secrets
Authentication secrets for accessing the configured provider (required).

Hosting Environments

site.environments.<name>
Hosting environments are named using a template data key.

Sample

site.yaml 
1---
2title: HyperTemplates
3description: the pure-HTML templating system for the modern web.
4...: ...
5environments:
6  production: [git]

In this this example, we have configured a hosting environment named production.

site.environments.<name> providers
Hosting environments are configured by providing a list of provider names.

Sample

site.yaml 
 1---
 2title: HyperTemplates
 3description: the pure-HTML templating system for the modern web.
 4...: ...
 5providers:
 6  github:
 7    kind: git
 8    endpoint: [email protected]:herdworks/hypertemplates-web.git
 9    config:
10      branch: gh-pages
11      publish_dir: .
12    secrets:
13      - name: ssh_private_key
14        key: GH_PRIVATE_KEY
15environments:
16  production: [github]

In this this example, we have configured the production environment to use the github provider.

Guides

Link Verification
How to configure link verification using rel="me" links. 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! 🎨