Glossary SEO

Glossaries (content type: glossary) win their page-level keyword (e.g. tmux glossary) through the one-term-per-H2 structure. That structure alone does not rank each term for its own "what is X?" query, and it does not produce rich results. This page documents the two levers that do, plus the content strategy that makes them compound.

What H2-per-term does and does not do

Concern	H2-per-term effect
Page-level keyword (tmux glossary)	✅ Becomes the best-structured answer
Per-term long-tail (what is a pane in tmux)	⚠️ Feeds the cluster, but needs a dedicated page to rank
Definition / glossary rich results	❌ Requires structured data — headings alone don't trigger them
Content depth / topical authority	❌ Format is not substance; thin definitions stay thin

The two recommendations below close the gaps: internal links for per-term rankings and authority flow, DefinedTermSet schema for rich results.

1. Per-Term Internal Linking (Topical Cluster)

The rule

Every glossary term links to the deepest existing post about that concept — with descriptive anchor text. No dead-end terms.

The glossary is the hub; the reference/cheatsheet posts are the spokes:

Authoring contract

## Copy mode

A scrollback mode entered with `Ctrl-b [` where you can scroll and copy text.
See the [Tmux Reference](/demo/tmux-reference/) for how it fits into the
client–server model.

• Exactly one target per term — the deepest relevant post on that concept. Do not scatter links to two or three posts from one term.
• Descriptive anchor text — the anchor says what the target is about ("the client–server model"), not "click here". This reinforces the target post's relevance for its keyword.
• No dead-ends — a term with no deeper post either links to the closest existing page or is a candidate for a dedicated post (see The Dedicated-Page Play).
• Relative URLs (/demo/tmux-reference/) — consistent with how the sync pipeline renders links.

Why it works for SEO

1. PageRank / topical flow — internal links pass authority from the glossary into the posts you want to rank for each term.
2. Anchor-text relevance — descriptive anchors strengthen the target post's topical relevance.
3. Cluster signal — Google reads "glossary defines it, reference explains it", which raises topical authority for the whole subject across every page in the cluster.
4. User journey — reader lands on #pane, reads the definition, clicks to the deep reference: longer session, lower bounce.

2. DefinedTermSet Structured Data (Rich Results)

Headings let Google infer structure. Schema lets you declare it — and declared terms are what unlock definition / glossary rich results (term → definition accordions in the SERP).

Schema shape

Use a single DefinedTermSet per glossary post, one DefinedTerm per H2 term, with an anchor URL that matches the heading the sync pipeline already generates (markdown2's header-ids extra):

{
  "@context": "https://schema.org",
  "@type": "DefinedTermSet",
  "name": "Tmux Glossary",
  "url": "https://id86.net/demo/tmux-glossary/",
  "hasDefinedTerm": [
    {
      "@type": "DefinedTerm",
      "name": "Pane",
      "url": "https://id86.net/demo/tmux-glossary/#pane",
      "description": "A rectangular split region inside a window. Panes share the window's size and can be resized, zoomed, and rearranged."
    },
    {
      "@type": "DefinedTerm",
      "name": "Session",
      "url": "https://id86.net/demo/tmux-glossary/#session",
      "description": "A named collection of windows. Sessions survive detach and are the unit you attach to with tmux attach."
    }
  ]
}

Pipeline approach (recommended)

Generate the JSON-LD at sync time — the structure already exists in the Markdown (H2 = term, following paragraph = definition), and markdown2's header-ids extra already produces the #term anchors:

1. In sync.py / wp-sync-bridge.php, detect content type: glossary (frontmatter).
2. Parse the H2 → paragraph pairs into the hasDefinedTerm array.
3. Emit the JSON-LD into post_content as a <script type="application/ld+json"> block, or store it as SEOPress custom-schema post meta (_seopress_pro_schemas) so SEOPress renders it into <head>.

Status: documented recommendation — not yet implemented in the pipeline. Until it is, glossary posts carry no structured data.

Do not create a separate schema file for a normal glossary. Its terms and definitions already live in Markdown, so the preferred implementation is to generate DefinedTermSet JSON-LD at sync time. The optional schema-seo/ directory and Schema Path register column are reserved for manual schema exceptions; custom files use schema-seo/<PID>.json.

Caveats (be honest about these)

• Rich results are eligibility, not a guarantee — Google decides whether to render them. But you can't get a definition rich result without the markup.
• Schema must match visible content — same terms, same definitions. Divergence is flagged as spam.
• DefinedTermSet is the correct type for a glossary. FAQPage is a different type for question→answer pages — do not mix them on one post.
• Validate with the Rich Results Test after deployment.

3. The Dedicated-Page Play

Per-term rankings are won by dedicated depth pages, with the glossary feeding them. Two layers:

Layer	Job	Example
Glossary	Breadth + definitions + hub	Tmux Glossary
Dedicated post	Depth + per-term ranking	a future Tmux Panes Reference

Trigger from the register: for each glossary term, ask does a deeper post exist? If not, and the term's Target Keyword is high opportunity / Priority P1–P2, it is a candidate for its own reference or cheatsheet post. The glossary then links to it, closing the loop.

Verification

• Every glossary term has exactly one cross-link to the deepest relevant post (or is listed as a dedicated-post candidate).
• Anchor text describes the target, not "click here".
• Glossary posts serve DefinedTermSet JSON-LD matching the visible H2 terms.
• Rich Results Test shows the structured data as valid on origin.