How To Use Publish Template Blocks And Starters

What these publish blocks actually are

Noute's publish system still uses plain Liquid files beside your notes or publish folder. In most cases publish-note.liquid defines the layout for published pages, and for folder sites an optional publish-index.liquid can define the full published root page by itself. The new built-in "blocks" are not a second templating language and they are not a locked visual builder.

They are:

• starter templates you can choose when creating publish-note.liquid
• built-in snippets you can insert from the template editor
• a richer render context so the snippets have useful data to work with

That combination matters because you can move fast without giving up control. You can start from a full blog or docs layout, then keep editing the raw Liquid yourself.

If you are new to file-based publishing, it helps to think of this as the same philosophy as Markdown itself: simple source files first, helpful structure on top.

How to start

When you create a publish template in Noute, you now choose a starter instead of always getting the same default file.

The built-in starters are:

• Essay: best for a single note, article, or content-first page
• Blog: best for a folder publish with a homepage, recent posts, and related posts
• Docs / Knowledge Base: best for navigation, article pages, and a table of contents
• Simple Website: best for a homepage-style site with a hero, featured content, and call to action

Each starter writes normal Liquid files. Multi-page starters can also create a publish-index.liquid root page template. There is nothing special to "unlock" later. You can edit any part of it.

Starter templates and snippets do different jobs

Use a starter when you want a full first draft of a page layout.

Use snippets when you already have a template and want to drop in a proven section such as:

• a site header
• a recent posts list
• a page header with metadata
• a footer
• a table of contents

In practice, many people start with Blog or Docs / Knowledge Base, then use the template editor's Insert snippet menu to add or replace sections as the site evolves.

The built-in snippets

Here is what the built-in snippet catalog is for.

Page Body

Renders the current page's HTML output safely.

Use it when:

• publishing an essay or note
• rendering the main article body on a blog post page
• placing the actual content area inside a wider docs layout

Typical Liquid:

<article class="publish-page-body">
  {{ page.body_html | safe_html }}
</article>

Site Header

Renders your site title plus links from site.meta.nav.

Use it when:

• you want a shared header across all published pages
• you are building a blog, docs site, or small marketing-style homepage

It usually reads from template frontmatter like this:

site:
  title: Notebook
  nav:
    - label: Home
      href: /
    - label: Writing
      href: /writing

Hero

Renders a homepage-style hero from site.meta.title, site.meta.tagline, site.meta.description, and site.meta.cta.

Use it when:

• publishing a personal site homepage
• giving a folder publish an obvious front page
• turning a notes workspace into a simple website rather than only a post archive

Page Header

Renders the current page title, summary, date, and tags from page.meta.

Use it when:

• publishing blog posts
• showing article metadata above the page body
• you want a repeatable structure for posts without manually typing the same HTML every time

This block becomes much better when your notes include frontmatter such as:

---
title: Shipping a smaller notes workflow
date: 2026-04-19
tags:
  - writing
  - notes
summary: What changed after cutting a big system down to a smaller local workflow.
---

Recent Posts

Renders the newest published posts from site.recentPosts.

Use it when:

• building a blog homepage
• adding a "latest writing" section to a website
• surfacing recent content in a sidebar or footer area

This list excludes notes marked as drafts or unpublished, and it follows the publish sort rules:

• newest date first
• then title
• then relative path

Featured Posts

Renders pages with featured: true in frontmatter from site.featured.

Use it when:

• your homepage should highlight a few anchor essays or flagship pages
• you want a curated layer above the normal recent-post stream

Example note frontmatter:

---
title: Start here
featured: true
summary: The best entry point if you are new here.
---

Post List

Renders a full archive from site.posts.

Use it when:

• building an archive page
• creating a docs or note index in a sidebar
• listing every published article without manually maintaining links

Tag List

Renders a derived taxonomy from site.tags.

Use it when:

• you want readers to understand the main themes in a site
• you need a quick tag cloud or a simple tag directory

Each tag includes:

• name
• slug
• count
• pages

Related Posts

Renders site.current.relatedPosts, which is built from shared tags with the current page.

Use it when:

• you want readers to keep exploring after a blog post
• your notes have meaningful tags and you want that structure to do real work

If the current page has no tags, this section will usually be empty.

Table of Contents

Renders heading links from page.toc.

Use it when:

• publishing long essays
• building docs or reference pages
• making article navigation easier without hand-maintaining anchor links

The TOC is generated from Markdown headings in the current page, so normal #, ##, and ### structure matters. If you care about this workflow, it connects naturally with clear note structure and linked writing practices.

Footer

Renders footer columns, social links, and the optional Noute attribution.

It reads from:

• site.meta.footer.columns
• site.meta.social
• publish.show_noute_footer

Use it when:

• you want shared footer navigation
• you need a light social or contact section
• you want the same footer across a whole folder publish

CTA Band

Renders a call-to-action section from site.meta.cta.

Use it when:

• building a simple website homepage
• adding a subscribe, contact, or "start here" block after featured content
• ending a blog homepage with one clear next step

The data these snippets use

The big change is not only the snippets. It is the render context behind them.

page

The current page object includes the basics:

• page.title
• page.relPath
• page.url
• page.body_html
• page.frontmatter

page.meta

This is the normalized metadata for the current page:

• title
• description
• date
• tags
• slug
• coverImage
• summary
• draft
• published
• featured
• readingTimeMinutes

Noute builds this from note frontmatter plus a few smart fallbacks.

Important behavior:

• summary falls back to the first meaningful paragraph when not provided
• coverImage accepts either coverImage or cover
• published defaults to true for folder publishing unless you explicitly set published: false

page.toc

An array of heading objects for the current page:

• id
• title
• depth

Use this for table-of-contents navigation.

site.meta

This is the site-wide config you set in the template frontmatter.

Supported keys include:

• site.title
• site.tagline
• site.description
• site.baseUrlLabel
• site.nav
• site.footer.columns
• site.social
• site.cta

site.pages

Every page in the published site, sorted by path. This is the widest collection.

Use it when you want:

• a full site map
• custom navigation logic
• a path-based page index rather than a blog-style list

site.posts

Published, non-draft pages sorted like posts.

Use it when:

• you want a full archive
• you need a blog list page
• you want collection-driven sections without including drafts

site.recentPosts

The newest subset of site.posts, limited by defaults.recentPostsLimit.

This is what the built-in Recent Posts snippet uses.

site.tags

Derived tags from published posts.

Each entry includes the tag name, slug, count, and matching pages.

site.featured

Published posts with featured: true.

site.current

Context about the current page inside the site:

• page
• previous
• next
• relatedPosts

This is especially useful in folder publishing, where previous and next links make sense across a collection.

publish

The publish object includes context such as:

• publish.kind
• publish.show_noute_footer
• publish.template_id

That lets templates react to whether they are rendering a note or folder site and whether the Noute footer should appear.

How to configure a site inside publish-note.liquid

Template frontmatter now does more than naming the template. It can carry site-wide config, which keeps the template portable.

Example:

---
name: My Blog
description: A simple writing site
site:
  title: Hui's Notes
  tagline: Writing, software, and research
  description: Essays and working notes published from Noute.
  nav:
    - label: Home
      href: /
    - label: Archive
      href: /archive
  footer:
    columns:
      - title: Explore
        links:
          - label: Notes
            href: /
          - label: About
            href: /about
  social:
    - label: GitHub
      href: https://github.com/example
  cta:
    eyebrow: Keep reading
    body: Start with the most useful essays and notes.
    label: Open archive
    href: /archive
defaults:
  postsFolder: blog
  recentPostsLimit: 6
---
<!DOCTYPE html>
<html lang="en">
  <body>
    {% if site %}
      {{ page.body_html | safe_html }}
    {% endif %}
  </body>
</html>

The most important defaults are:

• defaults.postsFolder: helps scope post-oriented snippets when your publish tree mixes posts with other pages
• defaults.recentPostsLimit: controls how many items land in site.recentPosts

A practical blog example

If you want a simple blog homepage and post template, the Blog starter is the best first move.

The rough structure is:

1. Site Header
2. Hero on the homepage
3. Featured Posts
4. Recent Posts
5. CTA Band
6. Footer

On non-home pages, the same starter usually switches to:

1. Page Header
2. Page Body
3. Related Posts
4. Footer

That gives you a credible blog layout very quickly, especially if your notes already have title, date, tags, summary, and featured frontmatter.

A practical docs example

If you are publishing reference pages or a knowledge base, start with Docs / Knowledge Base.

That starter is built around:

• a shared header
• a left-side post or page list
• a content area
• a right-side table of contents

The key habit here is to keep heading structure clean. If your Markdown uses clear sections, page.toc becomes useful immediately.

What to put in note frontmatter

The blocks work best when your note frontmatter is predictable.

The most useful fields are:

---
title: Post title
description: Optional search or share description
date: 2026-04-19
tags:
  - notes
  - publishing
summary: Optional short summary shown in lists
featured: false
draft: false
published: true
cover: /images/cover.jpg
---

You do not need every field on every page. But for a blog or website, title, date, tags, and summary are enough to make most of the built-in snippets worthwhile.

When to use which block

The shortest rule of thumb is:

• for a single article or essay: use Page Header, Page Body, and maybe Footer
• for a blog homepage: use Site Header, Hero, Featured Posts, Recent Posts, and CTA Band
• for a blog post: use Page Header, Page Body, Related Posts, and Footer
• for docs: use Site Header, Post List, Page Header, Table of Contents, Page Body, and Footer

A good editing workflow

The most reliable workflow is:

1. Create publish-note.liquid from the closest starter.
2. Add template frontmatter for site title, nav, footer, and defaults.
3. Make sure your notes have the frontmatter fields the blocks expect.
4. Use Insert snippet for sections you want to add.
5. Edit the inserted HTML and Liquid directly until it matches your site.

That approach keeps the source obvious and avoids the hidden complexity that often shows up in visual page builders.

If you are still choosing a long-term notes workflow, the broader context in Markdown notes on Mac is useful: simple local files age better than locked publishing systems.

One important limitation to understand

These snippets help with common publishing patterns, but they do not replace custom template work entirely.

If you need:

• pagination
• search
• custom taxonomies beyond tags
• highly interactive landing pages
• a full CMS-like content model

you will still need to write your own Liquid and HTML around the built-in data.

That is intentional. The system is optimized for notes, blogs, docs, and lightweight websites, not a full visual site builder.

The main idea

The publish template system is strongest when you treat the built-ins as accelerators, not constraints.

Start with a built-in starter. Insert a few snippets. Let your note frontmatter feed the template. Then keep editing the Liquid like any other source file.

That keeps the publishing workflow fast, understandable, and close to the same file-first mindset that makes Markdown useful in the first place.