Article presentation

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.

What Core Owns

• The generic article shell structure: hero framing, metadata row, featured media placement, reading-width body, optional table of contents, author context, aside modules, related reading, and section index layout.
• 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.
• A reusable list/single baseline that downstream sites can adopt directly or override lightly.

What Remains Site-Owned

• Brand voice, CTA copy, section hero art direction, and any business-specific conversion framing.
• Site-specific author resolution layers such as data/authors.yaml lookups or custom byline/profile imagery rules.
• Taxonomy definitions, badge wording, and editorial governance requirements.
• 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:

• 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.

Article Section Contract

The shared blog/section shell targets content/blog/_index.md and article lists in the blog section.

Adoption Guidance

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

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

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

4. 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.

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

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

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

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.