SEO

Hwaro includes built-in SEO features: sitemaps, RSS feeds, robots.txt, and social sharing meta tags.

Sitemap

Automatically generates sitemap.xml for search engines.

Configuration

[sitemap]
enabled = true
filename = "sitemap.xml"
changefreq = "weekly"
priority = 0.5
exclude = ["/private", "/drafts"]

Output

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2024-01-15</lastmod>
  </url>
  <url>
    <loc>https://example.com/about/</loc>
  </url>
</urlset>

Excluding Pages

Set in_sitemap = false in front matter:

+++
title = "Private Page"
in_sitemap = false
+++

RSS Feeds

Generate RSS feeds for your site and sections.

Configuration

[feeds]
enabled = true
type = "rss"              # "rss" or "atom"
limit = 20                # Maximum number of items
truncate = 0              # Truncate to N characters (0 = no truncation)
full_content = true       # true = full HTML body, false = description/summary only
filename = ""             # Leave empty for default (rss.xml or atom.xml)
sections = []             # Limit to specific sections, e.g., ["posts"]

Section Feeds

Enable per-section feeds:

+++
title = "Blog"
generate_feeds = true
+++

Generates /blog/rss.xml.

Output

• /rss.xml — Site-wide feed
• /blog/rss.xml — Section feed (if enabled)

Multilingual Feeds

When the site is multilingual, feeds are generated per language automatically:

By default, the main site feed includes only default language pages (default_language_only = true). Set default_language_only = false to include all languages in the main feed. Each non-default language with generate_feed = true gets its own separate feed regardless of this setting.

[feeds]
enabled = true
default_language_only = true   # true (default): main feed = default language only
                               # false: main feed includes all languages

Per-language feed control:

[languages.ko]
language_name = "한국어"
generate_feed = true    # Generates /ko/rss.xml (default: true)

[languages.ja]
language_name = "日本語"
generate_feed = false   # No /ja/rss.xml will be generated

Language feeds share the same sections, limit, truncate, and full_content settings from [feeds] config. RSS language feeds include a <language> tag, and Atom feeds include an xml:lang attribute. The feed title includes the language name (e.g., "My Site (한국어)").

Custom Feed Templates

To take full control of the feed markup, create a template named after the feed output:

Any template extension works (.jinja, .j2, .jinja2, .html) — only the final extension is stripped, so rss.xml.jinja loads under the key rss.xml. Whatever the extension, the file is always rendered as Jinja (an .ecr file is picked up too, but ECR <%= %> tags pass through as literal text — use Jinja syntax). The template file itself is the opt-in: when it's absent, Hwaro emits its built-in feed exactly as before, and deleting the template falls back to the built-in output. The override applies to all four feed kinds — the main feed, per-section feeds, per-language feeds, and per-taxonomy-term feeds — and a custom [feeds] filename still controls the output path.

{% include %} works inside feed templates, and a broken template fails the build with a template error naming the file.

Context variables

feed — metadata about the feed being rendered:

pages — the sorted, limit-applied entry list. Each entry:

Example

Values are not pre-escaped — applying xml_escape (or emitting CDATA) is the template author's job:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ feed.title | xml_escape }}</title>
    <link>{{ feed.home_url | xml_escape }}</link>
    <description>{{ feed.description | xml_escape }}</description>
    {% if feed.language %}<language>{{ feed.language | xml_escape }}</language>{% endif %}
    <atom:link href="{{ feed.url | xml_escape }}" rel="self" type="application/rss+xml" />
    {% for p in pages %}
    <item>
      <title>{{ p.title | xml_escape }}</title>
      <link>{{ p.url | xml_escape }}</link>
      <guid>{{ p.url | xml_escape }}</guid>
      <description>{{ p.summary | xml_escape }}</description>
      {% if p.date_rfc822 %}<pubDate>{{ p.date_rfc822 }}</pubDate>{% endif %}
      {% for term in p.categories %}<category>{{ term | xml_escape }}</category>{% endfor %}
    </item>
    {% endfor %}
  </channel>
</rss>

Template Links

<link rel="alternate" type="application/rss+xml" 
      href="{{ base_url }}/rss.xml" 
      title="{{ site.title }}">

{% if page.language and page.language != "en" %}
<link rel="alternate" type="application/rss+xml"
      href="{{ base_url }}/{{ page.language }}/rss.xml"
      title="{{ site.title }} ({{ page.language }})">
{% endif %}

Robots.txt

Control search engine crawling.

Configuration

[robots]
enabled = true

With custom rules:

[robots]
enabled = true
rules = [
  { user_agent = "*", disallow = ["/admin", "/private"] },
  { user_agent = "GPTBot", disallow = ["/"] }
]

When no rules are configured, Hwaro generates a default allow-all rule. If a rule has both allow and disallow empty, an explicit Allow: / is added to prevent ambiguous behavior.

Output

User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml

LLMs.txt

Generate instruction files for AI/LLM crawlers following the llms.txt standard.

[llms]
enabled = true
instructions = "This site's content is provided under the MIT license."
full_enabled = true

See LLMs.txt for full configuration and output details.

OpenGraph Tags

Social sharing meta tags for Facebook, LinkedIn, etc.

Configuration

[og]
default_image = "/images/og-default.png"
type = "website"
fb_app_id = "your_fb_app_id"

Page-Level Override

+++
title = "My Article"
description = "Article description"
image = "/images/article-cover.png"
+++

Template Usage

<head>
  {{ og_tags | safe }}
</head>

Output

<meta property="og:title" content="My Article">
<meta property="og:type" content="article">
<meta property="og:url" content="https://example.com/my-article/">
<meta property="og:description" content="Article description">
<meta property="og:image" content="https://example.com/images/article-cover.png">

Twitter Cards

Twitter-specific sharing tags.

Configuration

[og]
twitter_card = "summary_large_image"
twitter_site = "@yourusername"
twitter_creator = "@authorusername"

Template Usage

<head>
  {{ twitter_tags | safe }}
</head>

Or include both OG and Twitter:

<head>
  {{ og_all_tags | safe }}
</head>

Output

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="My Article">
<meta name="twitter:description" content="Article description">
<meta name="twitter:image" content="https://example.com/images/article-cover.png">
<meta name="twitter:site" content="@yourusername">

JSON-LD Structured Data

Hwaro automatically generates Article and BreadcrumbList JSON-LD for every page.

<head>
  {{ jsonld | safe }}
</head>

Additional schema types (FAQ, HowTo, WebSite, Organization) are also available. See Structured Data for all types, configuration, and output examples.

Template Variables

Pre-rendered HTML

These variables output ready-to-use HTML tags:

Structured SEO Object

The seo object provides individual field access for building custom meta tags:

<head>
  <link rel="canonical" href="{{ seo.canonical_url }}">
  <meta property="og:title" content="{{ page.title }}">
  <meta property="og:type" content="{{ seo.og_type }}">
  <meta property="og:url" content="{{ seo.canonical_url }}">
  {% if page.description %}
  <meta property="og:description" content="{{ page.description }}">
  {% endif %}
  {% if seo.og_image %}
  <meta property="og:image" content="{{ seo.og_image }}">
  {% endif %}
  {% if seo.fb_app_id %}
  <meta property="fb:app_id" content="{{ seo.fb_app_id }}">
  {% endif %}
  <meta name="twitter:card" content="{{ seo.twitter_card }}">
  <meta name="twitter:title" content="{{ page.title }}">
  {% if seo.twitter_site %}
  <meta name="twitter:site" content="{{ seo.twitter_site }}">
  {% endif %}
</head>

Complete Example

config.toml

title = "My Site"
description = "A great site"
base_url = "https://example.com"

[sitemap]
enabled = true

[feeds]
enabled = true
limit = 20

[robots]
enabled = true

[og]
default_image = "/images/og-default.png"
type = "website"
twitter_card = "summary_large_image"
twitter_site = "@mysite"

templates/base.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>{{ page.title }} - {{ site.title }}</title>
  <meta name="description" content="{{ page.description | default(value=site.description) }}">
  {{ og_all_tags | safe }}
  {{ canonical_tag | safe }}
  {{ hreflang_tags | safe }}
  {{ jsonld | safe }}
  <link rel="alternate" type="application/rss+xml" href="{{ base_url }}/rss.xml">
</head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

See Also

• LLMs.txt — AI/LLM crawler instructions
• Multilingual — Hreflang and canonical tags for i18n
• Configuration — Full config reference