mdxui.dev
npm7.0.0-alpha.0
Alpha: Ships on npm at 7.0.0-alpha.07.0.0-alpha.0

post-list

A blog index: a head, then the posts as ruled rows.

View as JSON
From Sidework › homevaultlineOpen the frame

When to use

Use a post list for a blog index or a changelog. It holds a head and one to 24 posts, each with a tag of 20 characters, a dateline, a title of 80 and a dek of 360.

Write the dek as what the reader learns. For products or listings, use product-list.

Date every post and keep the newest first. Tag by topic, in one word where it fits.

Use instead

The record

pages/sidework/home.json, section 4
{
  "kind": "section",
  "shell": { "inset": "listing", "density": "listing" },
  "block": {
    "type": "post-list",
    "head": {
      "eyebrow": "Latest",
      "title": "Recent issues",
      "lede": "The newest three, and issue 1. Issue 1 is free to read; the rest come with the paid letter."
    },
    "read": "Read",
    "posts": [
      {
        "href": "/subscribe",
        "tag": "Pricing",
        "dateline": {
          "date": "2026-10-20",
          "read": { "minutes": 5, "unit": "min read" }
        },
        "title": "Pricing a rush job",
        "dek": "A rush costs your evenings twice: the work and what it pushes out. Price both, and say the rush fee first."
      },
      {
        "href": "/subscribe",
        "tag": "Work",
        "dateline": {
          "date": "2026-10-13",
          "read": { "minutes": 7, "unit": "min read" }
        },
        "title": "When to quit the day job",
        "dek": "Three numbers decide it: months of costs saved, months of revenue booked, and the hours the side work takes."
      },
      {
        "href": "/subscribe",
        "tag": "Tax",
        "dateline": {
          "date": "2026-10-06",
          "read": { "minutes": 6, "unit": "min read" }
        },
        "title": "The year-end checklist, early",
        "dek": "Twelve items to clear in October, so January holds a return and not a search for receipts."
      },
      {
        "href": "/issues/the-first-invoice",
        "tag": "Money",
        "dateline": {
          "date": "2026-05-12",
          "read": { "minutes": 6, "unit": "min read" }
        },
        "title": "The first invoice",
        "dek": "What goes on it, when to send it, and the one line that gets it paid on time."
      }
    ]
  }
}

Smallest that parses

{
  "type": "post-list",
  "head": {
    "eyebrow": "Latest",
    "title": "Recent issues",
    "lede": "The newest three, and issue 1. Issue 1 is free to read; the rest come with the paid letter."
  },
  "read": "Read",
  "posts": [
    {
      "href": "/subscribe",
      "tag": "Pricing",
      "dateline": { "date": "2026-10-20" },
      "title": "Pricing a rush job",
      "dek": "A rush costs your evenings twice: the work and what it pushes out. Price both, and say the rush fee first."
    }
  ]
}

Fields and bounds

From @mdxui/site@7.0.0-alpha.0. A count reads as min–max × item; a string bound is its maximum length in characters, and links its refusal.

PropType and boundRequired
headobjectyes
head.eyebrowstring ≤28yes
head.titlestring ≤64yes
head.ledestring ≤200yes
readstring ≤16yes
posts1–24 × objectyes
posts[].hrefstring ≤160yes
posts[].tagstring ≤20yes
posts[].datelineobjectyes
posts[].dateline.datestring (pattern)yes
posts[].dateline.readobjectno
posts[].titlestring ≤80yes
posts[].dekstring ≤360yes

Variants and counts

One layout, from 1 post to 24.

post-listopen

One record in five Themes

vaultlineSidework’s ownopen
certificateopen
quaypointopen
callboardopen
directoryopen

Shells

paperopen
tintopen
glassopen

In three Businesses

Carried by the blog Template. Seen on pages/sidework/home.json, section 4.

Sidework › home · vaultlineA weekly letter lists 24 issues in its archive.
Diffkeel › changelog · certificateA developer tool lists releases with what each changed.
Harbor tides › blog · quaypointAn API product lists notes on how its tables are made.

Do and do not

Doopen
A dek that says what the reader learns.
Don’topen
A dek that repeats the title gives the reader no reason to open the post.
Doopen
A tag of one or two words.
Don’trefused
"tag": "Windows and draft planning"
SectionSchema.safeParse(record)block.posts.0.tag26 charactersToo big: expected string to have <=20 characters
A tag past 20 characters is refused at its path.

Accessibility

Check, on the exemplar renderLimitNowPass
Skipped heading levels00yes
Unnamed nav landmarks00 of 0yes
Scroll regions a keyboard cannot reach00 of 0yes
Copy controls that announce the resultall0 of 0yes
Images and icons with no text alternative00yes

Text pairs below AA across the 5 Themes and every scheme they emit: 5. See Render checks.

  • Landmark The list sits in main. It adds no landmark.
  • Heading level The head title renders as the page h1 and each post title as an h2.
  • Focus order Each post is one link, in record order.
Directoryproduct-listUse it for products, not posts.