Hugo Graph Architecture Guide

Hugo Graph adds durable structure to ordinary Hugo content. Your knowledge lives in YAML front matter, Hugo turns it into a fast static site, and the graph remains useful outside the website.

The idea: keep everything developers love about Hugo—Markdown, Git, fast builds, and static hosting—while giving every important subject a stable identity and every connection an explicit meaning.

The AI-first path

You do not need to start by designing an ontology. Use the Copy Graph Builder Prompt button above, paste the prompt into your AI, then add whatever you already have: one sentence, rough notes, existing pages, research, or complete documents.

The AI will turn that unstructured material into one validated Graph Spine Manifest in YAML. Its graph section contains the canonical ontology, stable nodes, and typed relationships. A separate generation_metadata section carries evidence, publishing suggestions, and review notes without changing the graph architecture.

The workflow is deliberately simple:

1. Paste the prompt and your source material into AI.
2. Review the generated YAML and resolve any items the AI flags.
3. Save it as graph-spine.yaml, keep it as the source of truth, and tell the AI to generate the Hugo site from it.

For the third step, this is enough:

Use this Graph Spine Manifest to generate a Hugo site with the unchanged Hugo Graph Architecture at https://github.com/raiford-nashville-ai/hugo-graph. Treat only graph_spine.graph.ontology and graph_spine.graph.nodes as canonical graph data. Use generation_metadata as planning and evidence, never as additional node or ontology fields. Preserve every stable node ID, write the ontology to site/data/ontology.yaml, create the suggested content files, validate every relationship target, and run the Hugo build before you finish.

[paste the generated YAML here]

The first prompt discovers and structures the knowledge. The manifest then gives the site-building AI a precise contract instead of asking it to infer your content model while it writes templates.

Get running in five minutes

You need Hugo installed. This reference site is tested with Hugo 0.165.0.

1. Clone and run the reference site

git clone https://github.com/raiford-nashville-ai/hugo-graph.git
cd hugo-graph
hugo server --source site

Open http://localhost:1313/graph/. You now have a working graph with entities, a concept, an expression, and relationships between them.

2. Create your first node

Use an included archetype so every required field starts in the right place:

hugo new content --source site --kind entity graph/entities/acme.md

Open site/content/graph/entities/acme.md and make the generated node specific:

---
title: "Acme"
description: "A fictional product company."

node:
  id: "acme"
  name: "Acme"
  description: "A fictional company that develops connected products."
  aliases: []
  type: "entity"
  kind: "company"
  properties:
    status: "active"
    salience: 0.8
  relationships: []
---

Save the file. Hugo rebuilds it immediately and adds the node to the graph navigation and overview.

3. Connect it to another node

Relationships are stored once, on the source node, and point to another node’s stable ID:

relationships:
  - predicate: "develops"
    target: "widget"
    properties:
      confidence: 1.0

The target must match an existing node.id. Hugo Graph resolves that ID to the target page when it renders the site, so the relationship survives renamed files and changed URLs.

The mental model

There are three broad node types:

• Entities are identifiable things: people, companies, products, sources, or events.
• Concepts are ideas: technologies, strategies, or risks.
• Expressions are authored interpretations: articles, overviews, or analyses.

Ordinary Hugo pages still work normally. Only content that belongs in the knowledge graph needs a node block.

How a request becomes a graph page

1. Hugo reads Markdown and YAML from site/content/.
2. The ontology in site/data/ontology.yaml supplies the allowed vocabulary.
3. A cached partial builds an index from every node.id to its Hugo page.
4. The shared node renderer uses that index to turn relationship targets into links.
5. Hugo publishes ordinary static HTML—no runtime database, API, or JavaScript graph library is required.

This separation is the important part: Hugo owns presentation, while the front matter owns the knowledge.

Bring Hugo Graph into your site

Start small. You do not need to redesign your entire content model at once.

1. Copy site/data/ontology.yaml and adjust its kinds and predicates for your domain.
2. Copy the entity, concept, and expression archetypes.
3. Add a node block to a few high-value subjects.
4. Copy or adapt graph-node-index.html and node-detail.html for your theme.
5. Add graph-aware navigation only where it improves discovery.
6. Add validation before the collection becomes large.

Rules worth keeping

• Use globally unique lowercase kebab-case IDs.
• Never change an ID just because a file, title, or URL changes.
• Put facts about the current node in properties.
• Put references to other nodes in relationships.
• Use predicates from the ontology instead of inventing them page by page.
• Store each relationship once and derive incoming links when needed.

Follow the working source

This website is the reference implementation, not a separate marketing demo. The shortest path through the code is:

1. apple.md — a complete node with relationships.
2. ontology.yaml — the shared vocabulary.
3. graph-node-index.html — stable ID lookup.
4. node-detail.html — shared relationship rendering.
5. docs/architecture.md — the full rules and implementation reference.

Run the example, change one relationship, and watch Hugo rebuild it. That small loop is the quickest way to understand the architecture—and the easiest way to decide how it fits your own site.

Browse the live graph or explore the complete repository.