Entities

In SchemaFlux, an entity is the fundamental unit of content. Every markdown file in your content directory represents one entity. Entities carry metadata through frontmatter, rendered content through their markdown body, and computed properties generated by the compiler passes.

What Is an Entity?

An entity is any discrete piece of content that should become a page on your site. This could be a blog post, a product review, a recipe, a documentation page, or anything else you want to publish. SchemaFlux does not impose any semantic meaning on entities -- they are simply structured data containers that flow through the compiler pipeline.

Each entity has three parts:

1. Frontmatter: YAML metadata at the top of the file, delimited by ---
2. Body: Markdown content below the frontmatter, rendered to HTML during parsing
3. Computed fields: Properties added by compiler passes, such as slugs, URLs, related entities, and JSON-LD schemas

The frontend parses the first two parts from disk. The compiler passes generate the third.

Frontmatter Fields

The frontmatter is where you define the metadata for your entity. SchemaFlux recognizes several standard fields and passes any additional fields through as custom metadata available in templates.

Required Fields

---
title: "My Entity Title"
---

The title field is the only strictly required field. It is used by the slug resolver to generate URL slugs, by templates to render page titles, and by the schema pass to generate structured data.

Standard Optional Fields

---
title: "Best Wireless Headphones 2025"
description: "A comprehensive review of the top wireless headphones."
date: "2025-06-15"
updated: "2025-07-01"
draft: false
categories:
  - "reviews"
  - "audio"
tags:
  - "headphones"
  - "wireless"
  - "bluetooth"
brand: "Sony"
rating: 4.5
image: "/images/headphones.jpg"
---

Custom Fields

You can add any additional fields to your frontmatter. They are stored in the entity metadata map and accessible in templates. This is useful for domain-specific data like prices, specifications, affiliate links, or structured attributes.

---
title: "Sony WH-1000XM5"
price: 349.99
affiliate_url: "https://example.com/buy/sony-xm5"
specs:
  driver_size: "30mm"
  battery_life: "30 hours"
  weight: "250g"
---

Custom fields are preserved through the entire pipeline and can be referenced in templates using their frontmatter key names.

Body Content

The body is standard markdown content below the frontmatter. It is parsed by the frontend into HTML and stored in the entity's Body field. The body supports all standard markdown features including headings, lists, code blocks, links, images, and tables.

---
title: "My Entity"
---

## Introduction

This is the body content. It supports **bold**, *italic*, and `code`.

### Features

- Feature one
- Feature two
- Feature three

Here is a code example:

    func main() {
        fmt.Println("Hello, SchemaFlux")
    }

The rendered HTML body is available in templates as .Entity.Body. SchemaFlux does not apply any additional processing to the body content beyond standard markdown rendering.

Relationships Between Entities

Entities are not isolated. They form relationships through shared taxonomy terms. When two entities share a category or tag, SchemaFlux recognizes them as related. The related pass scores these relationships based on the number of shared terms, and the graph_enrich pass builds a full relationship graph.

For example, if Entity A has tags ["go", "cli"] and Entity B has tags ["go", "web"], they share the tag "go" and will be identified as related. The more terms they share, the higher their relatedness score.

These relationships are used in templates to show "Related Articles" sections, to build internal linking structures, and to enrich the JSON-LD structured data with references to related content.

Entity Lifecycle

An entity flows through the following stages during a build:

1. Parsed by the frontend from a markdown file on disk
2. Slugified by the slug_resolve pass, which generates a URL slug from the title
3. Sorted by the sort pass into the configured order
4. Enriched by the enrichment pass with computed metadata
5. Categorized by the taxonomy pass into taxonomy indices
6. Related by the related and graph_enrich passes to other entities
7. Analyzed by the content_analysis pass for content metrics
8. URL-resolved by the url_resolve pass with absolute URLs
9. Schema-enriched by the schema pass with JSON-LD data
10. Validated by the validate pass for completeness
11. Rendered by the backend into an HTML page

After step 10, the entity is fully enriched and its data is effectively frozen. The backend in step 11 only reads from the entity; it never modifies it.