Blog Article

The page of one blog post: a header with the date, the reading time, the title, the author, the tags and the cover, then the body in a measured column that a beam fills as it is read, beside a contents list that follows the reader. The body is your rendered Markdown or MDX, and the contents list comes from the headings Astro returns with it. No script of its own: the beam is TracingBeam, the list is ReadingToc.

All posts

2026-10-093 min read

Sample post: a page built for reading

Sample AuthorSample role

Sample
Reading

This post is sample text. It describes the page it sits on, so every sentence can be checked against what the page does.

What follows you as you read

Two things on this page follow the reader: the line beside the text and the list of headings in the side column.

The beam

The line fills as the article scrolls past. It runs on the article's own view timeline, so the browser draws it and no script counts pixels.

The contents list

The list marks the heading you are reading. Its links are plain anchors, and a jump stops below the sticky bar.

Components a post brings

A post imports what it uses: a marker, code tabs, a gallery and a link card.

npmpnpm

npx astro add moonarc

pnpm astro add moonarc

The list beside this text is Reading Toc, and the line is its sibling.

Without JavaScript

The line is full and still, the list is a list of links, the pictures link to their full size, and the card is a plain link.

Live, from the library itself, at full size: scroll, hover, navigate away and back. The demo is never gated.

Measured

JavaScript of its own

0 B

Uses ReadingToc and the shared runtime (1.9 kB raw, once per site). With those included: 2.6 kB raw.

CSS 15.8 kB raw including the base tokens. Measured from a production build, and again in CI for every change that can move it.

Browser support

Limited availability

Chrome 115 · not Firefox · Safari 26; needs scroll-timeline, property. Elsewhere: Firefox shows the beam as a full, static line with its dot at the end; the contents list still marks the current heading, and the post reads the same..

Install Pro

The demo above is never gated; the source is. With a key in components.json (see account), the registry serves it like any other item:

terminal

npx shadcn@latest add @moonarc-pro/blog-article

src/pages/index.astro

---
import BlogArticle from '@/components/moonarc/pro/BlogArticle.astro';
import { getEntry, render } from 'astro:content';
// src/pages/blog/[slug].astro: the post from your collection, rendered; headings are the ids the Markdown pipeline wrote
const post = await getEntry('posts', Astro.params.slug!);
const { Content, headings } = await render(post!);
---
<BlogArticle
  title={post.data.title}
  date={post.data.pubDate}
  updated={post.data.updated}
  author={{ name: 'Ada Park', role: 'Engineering' }}
  tags={post.data.tags}
  minutes={6}
  cover={{ src: post.data.cover.src, alt: post.data.cover.alt }}
  headings={headings}
  offset={64}
  back={{ href: '/blog/', label: 'All posts' }}
  next={{ href: '/blog/next-post/', title: 'The next post' }}
>
  <Content />
</BlogArticle>

<!-- A post imports what it uses itself (HighlightMarker, CodeTabs, Lightbox, LinkPreview): they are the post's, not the
     section's, so a post without them ships none of their JavaScript. Code fences go through Shiki at build; pass
     markdown.shikiConfig the readableCode() transformer so their colours keep 4.5 : 1. -->

Without a key the registry answers 401 with an upgrade message. Everything this section composes is free: tracing-beam, reading-toc, page-transition.

Props

Prop	Type	Default	Description
`title`	`string`	none	The post's title: the h1 unless `level` says 2. Required.
`level`	`1 \| 2`	`1`	Heading level of the title: 1 on the post page, 2 under another h1 (a demo). Write the body's headings from h2 either way.
`date`	`string \| Date`	none	Publication day. A string prints as given and is the datetime; a Date (a collection's z.coerce.date()) prints through Intl.DateTimeFormat in UTC, the day the file names, with that day in ISO form as the datetime. BlogGrid prints the same day the same way.
`updated`	`string \| Date`	none	Day of the last real change, printed after the date through updatedLabel as a second <time>.
`locale`	`string`	`unset (the runtime's)`	Intl locale a Date prints in.
`dateStyle`	`'full' \| 'long' \| 'medium' \| 'short'`	`'medium'`	Intl date style of a Date (medium: Mar 2, 2026).
`updatedLabel`	`string`	`'Updated {date}'`	The updated line; {date} becomes the <time>. Without {date} the build fails.
`author`	`{ name, role?, avatar? }`	none	Who wrote it. avatar is a URL or an imported image (its src, width and height are used); it is decorative (alt="") because the name is printed beside it.
`tags`	`string[]`	`[]`	Tags, printed as a list under the author.
`minutes`	`number`	none	Reading time in minutes, rounded, at least 1. Compute it at build from the body's word count.
`minutesLabel`	`string`	`'{n} min read'`	The reading-time text; {n} is the number. Without {n} the build fails.
`cover`	`{ src, alt }`	none	The cover image: a URL or an imported image. Its transition name is ma-cover- and the page's path, the name BlogGrid gives the same post's card, so the router morphs one into the other. alt describes the picture, or is empty for a decorative one.
`headings`	`{ depth, slug, text }[]`	`[]`	Astro's headings from render(): depth 2 and 3 become the contents list, linking to the ids the Markdown pipeline wrote.
`toc`	`boolean`	`true`	Show the contents list. It is rendered only when two headings or more qualify.
`tocTitle`	`string`	`'On this page'`	The contents list's visible title and the name of its nav.
`offset`	`number`	`80`	Height of the page's sticky bar in px. The side column sticks below it, a jump to a heading stops below it (scroll-margin), and ReadingToc counts a heading as current from that line down.
`back`	`{ href, label }`	none	A link back above the title (the blog index); its arrow turns in a right-to-left document.
`prev`	`{ href, title }`	none	The previous post, linked under the body with rel="prev".
`next`	`{ href, title }`	none	The next post, linked under the body with rel="next".
`prevLabel`	`string`	`'Previous'`	The small line above the previous post's title.
`nextLabel`	`string`	`'Next'`	The small line above the next post's title.
`pagerLabel`	`string`	`'More posts'`	The name of the nav that holds the two links.
`tone`	`'surface' \| 'muted' \| 'ink' \| 'brand'`	`unset (paints nothing)`	The ground: the page surface, a muted band, an always-dark ink panel, or a deep brand panel. Each paints --background, --ma-tone-muted (over --muted, with a --border hairline), --ma-tone-ink or --ma-tone-brand (over --primary) with the matching text. With theme.css, a painted tone also re-declares --card, --border, --input and --ring inside the section. The beam is the theme's primary on an unset, surface or muted ground and the tone's text on ink and brand; the contents list's rule and mark follow the text.
`density`	`'compact' \| 'cozy' \| 'roomy'`	`'cozy'`	Block padding and the main gaps ×0.8 / ×1 / ×1.25 through --ma-density.

Theming and overrides

The section reads the theme contract (shadcn's variable names with the base tokens as fallback), so a pasted theme or one --ma-brand recolours it. Its class names are the override surface and stay stable; a named slot replaces the matching prop with your own markup.

Classes

.ma-article.ma-article__arrow.ma-article__author.ma-article__avatar.ma-article__back.ma-article__beam.ma-article__cover.ma-article__footer.ma-article__head.ma-article__inner.ma-article__layout.ma-article__layout--side.ma-article__meta.ma-article__name.ma-article__pager.ma-article__prose.ma-article__role.ma-article__side.ma-article__step.ma-article__step--next.ma-article__step-label.ma-article__step-title.ma-article__tags.ma-article__title.ma-article__toc.ma-article__who.ma-toc__link

Slots

slot="aside"slot="footer"

Reduced motion

The beam is a full, still line, the contents list moves its mark without easing, and the back arrow does not travel. The list still marks the current heading.

With `ClientRouter`

ReadingToc binds through the runtime's onMount and drops its scroll listener before every swap, so a post reached by a ClientRouter navigation has one listener. The cover's transition name pairs it with BlogGrid's card for the same post.

Why it is built this way

The body is a slot, so the post is whatever your Markdown or MDX renders. The components a post uses are imported by the post: a post without a lightbox ships no lightbox script.
The contents list is built from the headings Astro returns with the rendered post, so its links are the ids the Markdown pipeline wrote, never ids guessed from the text.
The side column sticks under the page's bar (offset) and is capped at the viewport's height minus that bar, so a long list scrolls inside it instead of running off the screen. Under 60 rem of the section's width, the list moves above the body as a plain list.
The body is capped at 70 characters a line. Headings jump to a line below the sticky bar through scroll-margin, and code blocks scroll sideways inside the measure.
The beam sits in the first column of TracingBeam's grid, so a right-to-left document puts it on the right with no rule of its own.
A Date prints in UTC through Intl, as BlogGrid prints it, so the card and the post name the same day for a date written without a time.

Replaces: Blog post layouts (Tailwind Plus) · Article pages (shadcnblocks) · TracingBeam post layouts (Aceternity). See the migration table.

npmpnpmbun

npx astro add moonarc

pnpm astro add moonarc

bunx astro add moonarc

Code Tabs

A code block with tabs (for example npm, pnpm, bun) and a copy button per panel.

every browserclick

Highlight Marker

Text

A highlighter sweeps across the phrases you marked, one after another, when the sentence scrolls into view.

every browserscroll

click · grows from its thumbnail · ← →

Lightbox

A thumbnail gallery whose images open full size: the image grows out of its own thumbnail on a same-document view transition and returns to it on close, and ← → move through the set.

newly · Chrome 111 · Firefox 144 · Safari 18click

Link Preview

A link that shows a small card (image, title, one line, domain) after a moment on hover or focus, above everything, flipping when there is no room.

newly · Chrome 125 · Firefox 147 · Safari 26hover

Install

Each heading becomes current when it crosses a line near the top of this box; the scroll listener sits on this box.

Only aria-current is written; the bar is CSS.

Tokens

Each heading becomes current when it crosses a line near the top of this box; the scroll listener sits on this box.

Only aria-current is written; the bar is CSS.

Runtime

Each heading becomes current when it crosses a line near the top of this box; the scroll listener sits on this box.

Only aria-current is written; the bar is CSS.

Ship

Each heading becomes current when it crosses a line near the top of this box; the scroll listener sits on this box.

Only aria-current is written; the bar is CSS.

The end.

Reading TOC

Scroll

A table of contents that lights up as you read.

every browserscroll

scroll inside

The line is the part you have read.

One registered percentage runs on the article's own view timeline; the fill's height and the dot's position both read it, so the two cannot drift apart.

The range is contain: 0 % when the top of this article meets the top of the box, 100 % when its end meets the bottom.

Without scroll timelines the line is full and still, which is the honest state: a finished article.

The fill is a gradient from a third of the colour to all of it, so the beam reads as light travelling down rather than a progress bar.

The head is five line-widths across with a soft ring; it sits exactly where the fill ends because both read the same value.

The end.

Tracing Beam

Scroll

A line beside an article fills as it is read, with a dot at its head.

Chrome 115 · not Firefox · Safari 26scroll

2026-10-09Release

Endpoint, Homescreen, Estate, Practice and Stay, templates for developer products, mobile apps, estate agents, practices and places to stay, and thirty sections

Endpoint, a template for a product with an HTTP API: a console on the home page that sends a request and streams the response back with its status, its time and its region, an API reference written at build from your OpenAPI document, a quickstart and four guides, usage pricing with a slider, a status page, the regions on a map, a changelog with a feed, search and a contact page for sales.

2026-10-07Release

newly · Chrome 111 · Firefox 144 · Safari 18scrollhoverclick

Also: view transitions · how costs are measured · browser support · accessibility policy · five-minute setup · MCP for agents · this page as Markdown

Blog Article

Sample post: a page built for reading

What follows you as you read

The beam

The contents list

Components a post brings

Without JavaScript

Measured

Install Pro

Props

Theming and overrides

Classes

Slots

Reduced motion

With `ClientRouter`

Why it is built this way

Code Tabs

Highlight Marker

Lightbox

Link Preview

Install

Tokens

Runtime

Ship

Reading TOC

Tracing Beam

Endpoint, Homescreen, Estate, Practice and Stay, templates for developer products, mobile apps, estate agents, practices and places to stay, and thirty sections

This site in Plus Jakarta Sans and JetBrains Mono

The terms, privacy and refunds, checked against Indonesian law

Core and the MCP server on npm

Creator, a template for one person's work, and seven sections

Blog Grid

Blog Article

Live demo

What follows you as you read

The beam

The contents list

Components a post brings

Without JavaScript

Measured

Install Pro

Props

Theming and overrides

Classes

Slots

Reduced motion

With ClientRouter

Why it is built this way

Related

With `ClientRouter`