SEO

Every sitemd site ships with comprehensive SEO out of the box. No configuration required — canonical URLs, Open Graph tags, Twitter Cards, JSON-LD structured data, enhanced sitemaps, and AI crawler directives are all generated automatically on every build. SEO renders fully in both trial and activated modes — file outputs like sitemap.xml and robots.txt are written to disk when activated.

What's included

Without touching any settings, every production page gets:

• Canonical URL — prevents duplicate content issues
• Open Graph tags — title, description, URL, type, site name, image
• Twitter Cards — summary_large_image when an image exists, summary otherwise
• JSON-LD structured data — BreadcrumbList on every page, plus type-specific schema (BlogPosting, TechArticle, FAQPage, HowTo, and more)
• Enhanced sitemap.xml — includes <lastmod> dates from file modification times
• robots.txt — with AI crawler directives (GPTBot, ClaudeBot, PerplexityBot, etc.)
• IndexNow — automatic search engine notification on every deploy (Bing, Yandex, Naver, Seznam)
• llms.txt — machine-readable site index for AI model discovery
• Markdown output — .md version of every page for AI crawlers and LLM tools (details)
• llms-full.txt — complete site content in one file for LLM ingestion
• RSS feeds — per-group RSS 2.0 feeds with autodiscovery (details)
• Auto-generated favicons — letter icon using your accent color (requires Sharp)

Settings

Edit settings/seo.md to customize. Every setting has a smart default — you only need to change what you want to override.

---
# Default title suffix appended to every page title (browser tab + social cards)
# Auto-populated into each page's frontmatter. Edit per-page to override.
# Set to "none" on a page to remove the suffix. Homepage uses just the site title.
titleSuffix: " | sitemd"

# Site language (ISO 639-1 code)
language: en

# OG social share image
# "auto" generates a branded card from your theme colors + site name
# Set a file path (e.g. /media/og-image.png) to use a custom image
# "none" disables OG images entirely
ogImage: auto

# ── Auto OG card options (only apply when ogImage: auto) ─────
# Card style: "template" (branded card) or "screenshot" (page capture)
# ogStyle: template
# Background color (defaults to your theme's background for defaultMode)
# ogBackground:
# Text color (defaults to your theme's text color for defaultMode)
# ogTextColor:
# Brand logo for OG cards (path to image in media/)
# ogLogo:

# JSON-LD structured data on every page
structuredData: true

# Generate /llms.txt for AI model discovery
llmsTxt: true

# Publish .md versions of every page (for AI crawlers and LLM tools)
markdownOutput: true

# Allow AI crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.)
allowAICrawlers: true

# IndexNow — auto-notify search engines on every deploy
indexNow: true

# Organization info for homepage schema
# (auto-derived from brandName / brandImage — override here if different)
# orgName:
# orgLogo:
---

All settings

Per-page frontmatter

Override any auto-derived SEO value on individual pages:

---
title: My Page Title
description: Custom meta description for this page.
image: /custom-og-image.png
canonical: https://example.com/canonical-url
robots: noindex, nofollow
ogTitle: Different OG Title
ogDescription: Different OG description
author: Jane Doe
published: 2026-01-15
updated: 2026-03-10
schemaType: BlogPosting
---

All fields are optional. When omitted, values are auto-derived:

• description — extracted from the first paragraph of your content, stripped of markdown formatting, truncated to 155 characters
• image — auto-generated OG card (when ogImage: auto), or the path set in ogImage from settings
• canonical — your site URL + the page slug
• schemaType — auto-detected from slug prefix (see below)

Browser tab title

By default, the browser tab shows {title}{titleSuffix}. Two frontmatter properties let you control the tab independently of the page heading and SEO title:

Both are auto-injected into every page's frontmatter on build (just like titleSuffix), so you can see and edit them directly. The homepage is skipped — it uses the site title alone with no suffix.

Example

---
title: Seamless integrations for everything a modern site needs
tabTitle: Integrations
tabTitleSuffix: " — sitemd"
---

• Browser tab → Integrations — sitemd
• Page heading → Seamless integrations for everything a modern site needs
• OG/social title → uses ogTitle if set, otherwise title + titleSuffix

Suppressing the tab suffix

Set tabTitleSuffix to "none" on any page to show just the tab title with no suffix:

---
tabTitle: Dashboard
tabTitleSuffix: "none"
---

Tab shows just "Dashboard".

Auto-detected schema types

The SEO system detects the right JSON-LD schema type based on your page's URL and content:

Override with the schemaType or ogType frontmatter fields when needed.

How does FAQ auto-detection work?

FAQPage schema is detected from content rather than URL. When a page contains three or more ### headings that end with a question mark, each followed by a paragraph answer, the page automatically gets FAQPage structured data. This triggers FAQ rich results in Google — expandable question/answer pairs directly in search results.

### What is sitemd?

sitemd is a markdown-first static site builder designed for AI coding agents.

### How do I install it?

Run npm install in your project directory or clone from GitHub.

### Does it work with Claude Code?

Yes. sitemd ships with MCP tools, skills, and context files for Claude Code.

How does HowTo schema work?

Pages under /guides/ or /tutorials/ automatically get HowTo structured data. Steps are extracted from ordered lists in your content, or from ### headings if no ordered list is found. This can trigger How-to rich results with step-by-step instructions in search results.

What is SoftwareApplication schema?

Set schemaType: SoftwareApplication in frontmatter for software product pages. Additional frontmatter fields are supported:

---
schemaType: SoftwareApplication
appName: My App
appCategory: DeveloperApplication
appOS: Windows, macOS, Linux
---

SoftwareApplication is not auto-detected — software product pages vary too much for reliable URL-based detection.

What is ProfilePage schema?

Pages under /team/ or /about/team/ automatically get ProfilePage schema wrapping a Person entity. The page title becomes the person's name, and the description and image from frontmatter are included. Set schemaType: ProfilePage on any page to apply it manually.

Organization schema

Your homepage automatically includes an Organization entity in its JSON-LD structured data. This tells search engines who runs the site and powers Knowledge Panel eligibility.

Two fields control it:

# settings/seo.md
---
# Organization info for homepage schema
# (auto-derived from brandName / brandImage — override here if different)
# orgName: Acme Inc.
# orgLogo: /media/acme-logo.png
---

By default, orgName uses your brandName from settings/meta.md and orgLogo uses your brandImage. Override them in settings/seo.md only when your legal organization name differs from your brand — for example, if your site brand is "Acme" but the legal entity is "Acme Holdings Ltd."

The organization entity also appears as the publisher on BlogPosting and Article pages, and as the author on SoftwareApplication pages.

OG image generation

A single branded Open Graph card is generated for your entire site, giving every page a consistent social preview image. The card displays your brand image and/or brand name on your theme's background, with an accent color bar on the left edge.

Set ogImage: auto in settings/seo.md (enabled by default for new sites).

How it works

On each build, the system:

1. Reads your theme colors (color-bg, color-text, color-accent) based on your defaultMode setting in theme.md
2. Loads your brand image from brandImage in settings/meta.md (if the file exists)
3. Computes a hash of the brand settings and colors
4. Skips generation if the cached hash matches (incremental builds)
5. Renders a single branded card to site/og/default.png

Every page without a custom image in frontmatter uses this shared card. Override ogBackground and ogTextColor in settings/seo.md to use specific colors instead of your theme's defaults.

Card layout

The generated card (1200×630px) uses a safe content area that remains visible across all social platform aspect ratios — from full-width Twitter cards to tighter iMessage and WhatsApp crops. Brand content is scaled to fill this area.

• Background — your dark theme color-bg (override with ogBackground)
• Brand image — centered in the safe area, from brandImage in settings/meta.md (if the file exists)
• Brand name — centered below the image (or alone if no image), scaled to fill available width, using dark theme color-text
• Accent bar — flush left edge with rounded right-side corners, using dark theme color-accent

Customizing card appearance

Override the auto-detected dark theme colors through settings/seo.md:

---
ogBackground: "#1a1a2e"
ogTextColor: "#ffffff"
---

When not set, ogBackground defaults to your dark theme color-bg and ogTextColor defaults to your dark theme color-text from settings/theme.md.

Screenshot mode

For page screenshots instead of the branded card, install Puppeteer and switch the style:

npm install puppeteer

---
ogStyle: screenshot
---

Screenshot mode captures each page at 1200×630 viewport, giving social previews that show your actual page content. Falls back to template mode if Puppeteer isn't installed.

Favicons

Favicons are auto-generated on every build when Sharp is installed. Three modes are available: letter (auto from title + theme accent), brand (uses your logo), and custom (your uploaded image). In letter mode, per-theme SVG favicons are generated and the browser tab icon updates live when visitors toggle between light, dark, and paper modes.

Favicon settings are configured in settings/meta.md, not settings/seo.md. See Site Identity — Favicon for the full setup guide.

Custom OG images

Site-wide branded image

Use the /og-image skill to generate a branded social share image from your theme colors and content. It produces a 2400×1260 PNG with two layout options (simple or browser mockup), saves to media/og-image.png, and configures settings/seo.md automatically. See Custom OG Images for the full guide.

Per-page images

To use a custom image for a specific page, add the image field to that page's frontmatter:

---
image: /my-custom-og.png
---

Place the image file in media/seo/og/ — it gets copied to your site output on build.

Custom image

To use a custom OG image instead of auto-generated cards, set ogImage to a file path:

---
ogImage: /media/og-image.png
---

IndexNow

IndexNow automatically notifies Bing, Yandex, Naver, and Seznam every time you deploy. Changed URLs are submitted immediately rather than waiting for search engines to re-crawl your sitemap — typically reducing indexing time from days to minutes.

How it works

1. On first deploy, sitemd auto-generates an API key and saves it to your project config (.sitemd/config.json)
2. A verification file ({key}.txt) is written to your site output and deployed alongside your pages
3. After each deploy, sitemd compares the current sitemap against the previous deploy to find new, changed, and removed URLs
4. Changed URLs are submitted to api.indexnow.org in a single POST — all participating engines receive the notification simultaneously
5. On subsequent deploys, only URLs that changed since the last deploy are submitted

Configuration

IndexNow is enabled by default. Disable it in settings/seo.md:

---
indexNow: false
---

The API key is managed via the CLI config store. View it with:

sitemd config get indexnow.apiKey

Set a custom key if needed:

sitemd config set indexnow.apiKey your-custom-key

For CI environments, use the SITEMD_INDEXNOW_KEY environment variable.

What IndexNow does not cover

Google does not participate in IndexNow. For Google indexing, submit your sitemap via Google Search Console — sitemd generates the sitemap automatically.

AI visibility

sitemd generates several files that help AI models discover and understand your site:

llms.txt

A machine-readable index of your site following the llms.txt proposal. Generated at /llms.txt with pages grouped by section. Excludes pages marked noindex. When markdown output is enabled, links point to .md versions of each page for direct LLM consumption.

llms-full.txt

When both llmsTxt and markdownOutput are enabled, a /llms-full.txt file is generated containing the full markdown content of every page on your site. AI tools can ingest your entire site in one request.

Markdown output

Every page gets a sibling index.md file containing clean markdown — no HTML, no layout, no scripts. AI crawlers and LLM tools get structured content by fetching yoursite.com/docs/page/index.md. Each HTML page also includes a <link rel="alternate" type="text/markdown"> tag pointing to its markdown version.

See Markdown Output for full documentation.

robots.txt AI directives

The allowAICrawlers setting controls whether AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Amazonbot, CCBot) can access your site. Defaults to true — set to false to block them via robots.txt.

SEO Preview

Preview how your pages appear in search results and social cards without deploying. Navigate to /{slug}/seo-preview on your dev server to see Google SERP mockups, social card previews, keyword analysis, meta tag audits, and structured data — all with character count badges showing whether your titles and descriptions fit within recommended limits.

See SEO Preview for full documentation.

SEO Audit

Run /seo to get a comprehensive health check of your SEO configuration and page metadata. The audit scores your site from 0–100, flags errors and warnings with educational explanations, and offers to fix issues. It runs automatically during builds and deploys.

See SEO Audit for the full check catalog and scoring details.