Article presentation

The current publication-level contract is documented in Editorial Constellation. This document retains the Markdown-body, figure, pullquote, math, and adoption details.

Foundry Core ships a shared article shell for long-form Markdown content through layouts/blog/single.html and layouts/blog/section.html. It also ships Markdown-first rich-body primitives through layouts/_default/_markup/render-image.html and layouts/shortcodes/pullquote.html so downstream sites can support figures, captions, credits, and editorial pull quotes without site-local raw HTML becoming the default contract.

Release Target

Downstream sites should adopt this contract from the first tagged Foundry Core release that includes the shared blog templates and rich-body primitives. For consumers currently pinned to v0.1.16, the expected upgrade target is v0.1.17 or later. Do not point a downstream site at unreleased main commits and call the toolkit supported.

Math Notation V1 is a later additive article-body capability introduced in Foundry Core v0.1.40 and included in the latest tagged Core release, v1.0.0. The Foundry Core v1.1.0 candidate requires Hugo Extended v0.165.0 or newer.

What Core Owns

• The normalized article shell and its guide, essay, feature, and conversation presentations: hero framing, visible facts, canonical contributors, lead media, reading body, table of contents, sources, review, sharing, newsletter placement, related reading, and series navigation.
• Front Page, Reading Room, and Dispatch Mosaic collection anatomy plus contributor, category, tag, and series archives with real pagination.
• Markdown-first rendering with sensible fallbacks when optional metadata is not present.
• Search/discovery normalization through helpers/discovery-model.html and framework/pagefind-metadata.html.
• Markdown-first image and pull-quote primitives that work inside article body content, not only in composed block arrays.
• Build-time LaTeX-style math transformation to semantic MathML, with strict validation and no browser math runtime.
• A reusable list/single baseline, Story Card, and deterministic selection model that downstream sites can adopt directly or override intentionally.

What Remains Site-Owned

• Brand voice, CTA copy, section hero art direction, and any business-specific conversion framing.
• The approved contributor records stored in the site’s data/authors files, taxonomy vocabulary, public publication name, badge wording, and editorial governance decisions. Core owns their portable resolver and renderer.
• Whether an existing site-level layouts/blog/single.html override should be retained for branded storytelling. The shared figure and pull-quote primitives can still come from core even when the article shell stays site-owned.
• Full template overrides when a site needs materially different storytelling or regulatory treatment.

Single Article Contract

The shared blog/single shell assumes the article body is normal Markdown content in .Content. Front matter enriches the shell; it does not replace the body.

Notes:

• The article-resource-starter asks for an author_key and an editorial_presentation; it intentionally omits a fake image, source, or review claim. Add those only after real assets, sources, and editorial review exist. The shared shell renders the page title, so the Markdown body must begin with the opening paragraph rather than a duplicate # heading.
• layouts/blog/single.html is the shared template path named in the page manifest.
• post-hero, pullquote, related-posts, and similar article blocks remain allowed, but they are optional inserts rather than required scaffolding for a standard Markdown article.
• section_key: body still describes the optional composed-article path. The shared shell does not require a block array to render a complete article.

Markdown-First Rich Body Primitives

Figures via render-image

Standalone Markdown images now render through layouts/_default/_markup/render-image.html.

• Default authoring path: ![Alt text](/images/article/example.jpg "Caption | Credit")
• Attribute-enhanced path: use Goldmark block attributes to set caption, credit, variant, aspect, rounded, shadow, id, class, width, or height.
• Supported variant values: contained, wide, full-bleed, float-left, float-right
• Supported aspect values: auto, 16:9, 4:3, 3:2, square

Base example:

![Consultation planning diagram](/images/blog/consultation-planning.jpg "How the treatment map is explained in consultation | Illustration: Foundry demo asset")

Attribute-driven example:

![Layered facial analysis](/images/blog/facial-analysis.jpg "Layered facial analysis")
{credit="Photo: Foundry demo asset" variant="wide" aspect="3:2"}

To make standalone Markdown images render as figures instead of inline images, downstream consumers must enable Goldmark block-image behavior:

markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false
      attribute:
        block: true

Without that parser configuration, Markdown images still render, but caption, credit, and layout attributes will not activate consistently for standalone figures.

Pull Quotes via pullquote

Markdown articles can now insert a shared pull quote with:

  







    

      

        
        

          Treat the shared shell as the baseline and keep the branded persuasion layer
site-owned.
        
        
          
        
      
    
  

Shortcode parameters:

• author, role: attribution text
• variant: accent-bar, filled, oversized, or minimal
• align: center or left
• id, class: optional wrapper targeting hooks

The shortcode reuses the shared blocks/pullquote.html visual contract, so composed pages and Markdown-first articles do not drift apart stylistically.

Math Notation

Math can appear inside the normal Markdown article body:

The energy relation is \(E = mc^2\).

\[
\int_0^1 x^2\,dx = \frac{1}{3}
\]

Core supports inline \(...\) and display \[...\] or $$...$$. It renders MathML during the Hugo build and keeps wide display expressions inside their own responsive scroll container. Single-dollar inline math, full .tex documents, packages, macros, numbering, and cross-references are not part of V1.

See Math Notation for configuration merge requirements, selective mounts, validation, migration, and rollback.

Article Section Contract

The shared blog/section shell targets content/blog/_index.md and article lists in the blog section. It uses the Editorial Constellation collection contract and shared Story Card.

Article Table Of Contents

The shared article shell renders desktop and mobile table-of-contents widgets from .TableOfContents. Core owns the progressive interaction runtime in assets/js/foundry-motion.js:

• selecting an item scrolls to the matching heading with the sticky-header offset applied
• the URL hash follows the selected section
• the current item exposes aria-current="true" and remains visible in a scrollable rail
• the progress bar tracks the reader’s position across article headings
• the compact mobile panel expands accessibly and collapses after selection
• static links remain usable if JavaScript is unavailable

A downstream site that mounts layouts/blog and the Core assets receives this behavior without a site-local JavaScript file. A site-level layouts/blog/single.html is a full Hugo template shadow: keep one only when the site intentionally owns a different article structure and accepts responsibility for tracking future Core article changes.

The article-heavy-site compatibility fixture protects the desktop and mobile interaction contract through browser smoke. Changes to the article shell, TOC widget, motion runtime, or related CSS should run:

go run ./cmd/foundry validate compatibility-fixtures article-heavy-site \
  --browser-smoke --require-browser

Adoption Guidance

1. Upgrade the downstream site to Foundry Core v0.1.17 or later.

2. Selectively mount layouts/blog at layouts/blog when adopting the shared article shell. Confirm a site-local layouts/blog/single.html is absent unless the site intentionally owns a full template fork.

3. Enable markup.goldmark.parser.wrapStandAloneImageWithinParagraph = false and markup.goldmark.parser.attribute.block = true in the downstream Hugo config before relying on attribute-driven figures.

4. Keep article content Markdown-first in content/blog/, using normal Markdown images and the shared pullquote shortcode for rich-body editorial moments.

5. If the downstream site already overrides layouts/blog/single.html, keep the override only for branded story structure. Do not fork image or pull-quote primitives into site-local partials unless the site truly needs a different contract.

6. Use examples/content-kits/article-rich-body-primitives.md as the baseline authoring example for figures, captions, credits, and pull quotes.

7. When using math, mount layouts/_default/_markup, preserve Core module configuration, and add markup._merge: deep if the site defines its own markup table. Use examples/content-kits/article-math-notation.md as the baseline equation example.

8. Run the core validators in this repo before tagging the supporting Foundry release:

   node scripts/validate-block-contract.js
   node scripts/validate-blocks.js
   

   For equation-bearing sites, also run:

   foundry validate math --site /absolute/path/to/site --json
   

Downstream Verification

Core Release Verification

Before declaring the shared toolkit ready for a downstream release:

• Run node scripts/validate-block-contract.js
• Run node scripts/validate-blocks.js
• Review docs/ARTICLE-PRESENTATION.md and examples/content-kits/article-rich-body-primitives.md together so the docs and authoring example still match the shared template behavior

First Proof-Profile Verification

A high-consideration service proof site is the first downstream verification profile for this toolkit. When a site in that profile adopts the release:

1. Update foundry.lock.yaml and go.mod to a Foundry Core tag of v0.1.17 or later.
2. Ensure the proof site does not add local overrides for layouts/_default/_markup/render-image.html or layouts/shortcodes/pullquote.html unless it intentionally wants a different contract.
3. Confirm the site’s Hugo config enables wrapStandAloneImageWithinParagraph: false and attribute.block: true.
4. Create or preview a blog article using the sample in examples/content-kits/article-rich-body-primitives.md.
5. Verify the resulting article page shows:
   • standalone Markdown images as figures with captions and credits
   • variant="wide" figures at the wider reading width
   • the shared pull quote styling inside the existing high-consideration service proof-site article shell
   • no requirement for site-local raw HTML in the article body
6. Run the proof site’s normal preview build and inspect the rendered article in browser, not only the raw Markdown source.