JSON-LD structured data (schema.org)

Fields missing from NoteView (must be added)

NoteView (internal/model/note.go:156) today has Title, CreatedAt,
Description *string, FirstImage *string, Permalink, Lang. It has no
author, no modified/updated date, no tags. Confirmed: ExtractMetaData()
(note.go:548) extracts description, reading time, headings, charts, code
languages, TOC, layout, MCP, RSS, routes, lang — but not author/tags/updated.
CreatedAt comes from the DB and is overridden by frontmatter
created_at/created_on (note_created_at.go).

So we add (Story 1): Author string, UpdatedAt time.Time, Tags []string,
parsed from frontmatter author, updated/modified/updated_at, and
tags/keywords.

Escaping — verified

quicktemplate output tags behave as follows (verified against generated
views.html.go and library usage):

• {%s= x %} → qw.N().S(x) — raw, no escaping (would corrupt JSON; not used here).
• {%q= x %} → qw.N().Q(x) — JSON/JS-quoted string (used for __trip2g_settings).
• {%z= b []byte %} → qw.N().Z(b) — writes raw bytes, no escaping. This is
  exactly how the existing form spec is embedded in a <script>:
  views.html:306-308 → qw.N().Z(specJSON) (views.html.go:1372).
• There is no {%j %} tag in this quicktemplate version; the codebase always
  uses explicit json.Marshal + {%z= %} / {%s= string(b) %}.

Recommended approach: build the payload in Go (ctx.JSONLD() []byte via
json.Marshal) and emit with {%z= %}, identical to FormSpecJSON.

</script> safety: Go's encoding/json.Marshal escapes <, >, and & to
<, >, & by default (HTML-safe), so a </script> inside
any string value cannot break out of the <script> element. Do NOT disable this
with SetEscapeHTML(false). (Note: FormSpecJSON in templateviews/note.go:351
uses enc.SetEscapeHTML(true) — keep the same for JSON-LD; the template.go
FormSpecJSON path uses plain json.Marshal, which is also HTML-safe.)

Template snippet (after line 44 in views.html):

{% code jsonld := ctx.JSONLD() %}
{% if len(jsonld) > 0 %}
<script type="application/ld+json">{%z= jsonld %}</script>
{% endif %}

After editing views.html you MUST run
go generate ./internal/defaulttemplate/... and commit the regenerated
views.html.go together with the template (CLAUDE.md, "Critical: Default
Template Pipeline").

Story 1: NoteView metadata fields

Add to internal/model/note.go (NoteView struct, near Description):

type NoteView struct {
    // ... existing fields ...

    Author    string    // frontmatter "author"
    UpdatedAt time.Time // frontmatter "updated"/"modified"/"updated_at"; zero if unset
    Tags      []string  // frontmatter "tags" or "keywords"
}

Extract in ExtractMetaData() (call a new extractJSONLDFields() alongside the
existing extractors):

func (n *NoteView) extractJSONLDFields(loc *time.Location) {
    if a, ok := n.RawMeta["author"].(string); ok {
        n.Author = strings.TrimSpace(a)
    }
    for _, key := range []string{"updated_at", "updated", "modified"} {
        if v, ok := n.RawMeta[key].(string); ok {
            if t, parsed := parseDate(v, loc); parsed {
                n.UpdatedAt = t
                break
            }
        }
    }
    n.Tags = extractTagList(n.RawMeta["tags"], n.RawMeta["keywords"])
}

Reuse the existing parseDate helper (note_created_at.go:43). loc is already
threaded into ExtractCreatedAt(time.UTC) from the loader
(mdloader/loader.go:224) — pass the same loc.

TDD: extend the model tests (pattern: note_codelang_test.go,
table-driven, testify/require). Cases: author present/absent; each date alias;
tags as []interface{}, []string, single string, absent; invalid date adds no
field (and optionally a warning).

Story 2: templateviews accessors

Add narrow accessors to internal/templateviews/note.go (do NOT make templates
Unwrap() the model — same rule as mermaid, mermaid.md):

func (n *Note) Author() string       { return n.nv.Author }
func (n *Note) UpdatedAt() time.Time  { return n.nv.UpdatedAt }
func (n *Note) Tags() []string        { return n.nv.Tags }

CreatedAt(), Title(), Description(), Lang(), FirstImageURL(),
Permalink() already exist.

TDD: small accessor tests in note_test.go.

Story 3: JSON-LD builder

Add a jsonld.go file in internal/defaulttemplate/ with the payload structs
and the type-decision function. Build typed Go structs (not map) marshaled with
json.Marshal so field order and omitempty are controlled:

type ldNode struct {
    Context          string      `json:"@context,omitempty"`
    Type             string      `json:"@type"`
    Headline         string      `json:"headline,omitempty"`
    Description      string      `json:"description,omitempty"`
    URL              string      `json:"url,omitempty"`
    MainEntityOfPage string      `json:"mainEntityOfPage,omitempty"`
    InLanguage       string      `json:"inLanguage,omitempty"`
    DatePublished    string      `json:"datePublished,omitempty"`
    DateModified     string      `json:"dateModified,omitempty"`
    Image            string      `json:"image,omitempty"`
    Keywords         []string    `json:"keywords,omitempty"`
    Author           *ldPerson   `json:"author,omitempty"`
    Publisher        *ldOrg      `json:"publisher,omitempty"`
}

ctx.JSONLDType() implements the decision table above. ctx.JSONLD() []byte
assembles a @graph with: the page node (BlogPosting/ProfilePage/...), a
BreadcrumbList, and the site WebSite+Organization. Returns nil when the
gate (Story 6) says the page is non-indexable.

Use ctx.OGTags["og:url"] for url/mainEntityOfPage (route/domain aware).
Dates via .Format(time.RFC3339). Keep SetEscapeHTML enabled (default).

TDD: table-driven tests on JSONLD() output — unmarshal the bytes back and
assert @type, presence/absence of optional fields per input, and that a string
containing </script> is escaped (assert raw bytes contain </script).
Magazine/home/profile/faq type selection. Tests live next to the builder
(jsonld_test.go) and need a Ctx with a wrapped *model.NoteView — follow
magazine_test.go for Ctx construction.

Story 4: BreadcrumbList + WebSite/Organization graph

Inside JSONLD():

• BreadcrumbList: split note.Permalink on /, build ListItems with name
  (title-cased segment, or resolved note title via ctx.Notes.ByPermalink when
  available) and item (full URL = publicURL + cumulative path). Home is item 1.
• WebSite: name + url from site config; optional potentialAction
  SearchAction pointing at the site search if desired (optional).
• Organization (publisher): name + logo from site config. Source the site
  name/logo from env.SiteConfig(ctx) (already used in buildDefaultTemplateCtx,
  endpoint.go:544) — thread the needed values onto Ctx in Story 5 rather than
  calling env from the template.

TDD: assert breadcrumb item count and URLs for a nested permalink
(/a/b/c), and that the graph always includes WebSite+Organization.

Story 5: wire data into Ctx

Ctx (internal/defaulttemplate/template.go:43) needs the site-level values not
currently present: site name, site logo URL, and the canonical public base URL.
Add fields:

SiteName    string
SiteLogoURL string
PublicURL   string // base, e.g. https://example.com

Populate them in buildDefaultTemplateCtx
(internal/case/rendernotepage/endpoint.go:471) from
env.SiteConfig(context.Background()) and env.PublicURL() (both already used
in that function). No new env methods required — PublicURL() and SiteConfig()
are already on the Env interface used here.

TDD: a focused test that buildDefaultTemplateCtx copies these through
(or assert via the existing endpoint/resolve test harness,
rendernotepage/resolve_test.go).

Story 6: template injection + indexability gate

Add ctx.ShouldEmitJSONLD() bool to template.go:

func (ctx *Ctx) ShouldEmitJSONLD() bool {
    if ctx.Note == nil { return false } // magazine root handled separately if desired
    if ctx.PaywallError != nil || ctx.SigninWallError != nil { return false }
    if ctx.OnboardingMode || ctx.NotFoundMode || ctx.UnsupportedFileExt != "" { return false }
    if strings.Contains(ctx.MetaRobots, "noindex") { return false }
    return true
}

JSONLD() returns nil when !ShouldEmitJSONLD().

Edit internal/defaulttemplate/views.html Render() <head>, after the OG
block (after line 44):

{% code jsonld := ctx.JSONLD() %}
{% if len(jsonld) > 0 %}
<script type="application/ld+json">{%z= jsonld %}</script>
{% endif %}

Run go generate ./internal/defaulttemplate/... and commit views.html.go.

TDD: render a full page via the existing template test path and assert the
<script type="application/ld+json"> is present for a normal note and absent for
paywall/404/onboarding. An e2e check can be added to e2e/vault.spec.js
(pattern: the mermaid "loads on /mermaid but not elsewhere" test) asserting the
ld+json block exists on a content page and parses as JSON.

Story 7 (optional): FAQPage detection

Detect a FAQ structure for FAQPage @type:

• Simplest: frontmatter faq: true → treat all H2/H3 + following content as
  Q/A pairs using Note.Headings + PartialRenderer().Sections(level)
  (note.go:213, note.go:101). Build mainEntity: [{ @type: Question, name, acceptedAnswer: { @type: Answer, text } }].
• This is additive; default behavior (BlogPosting) is unaffected when faq is
  unset.

TDD: a note with faq: true and two H2 sections produces two Question
entries with the section text as the answer.