Skip to content
SwiftDocsv1.3.1

Journal

Articles are MDX files in src/content/journal/. The file name is the URL: fewer-carousels.mdx becomes /journal/fewer-carousels. MDX is Markdown that can also include components, so you can write in plain Markdown and reach for a component only when you need one.

Frontmatter

Section titled “Frontmatter”
src/content/journal/fewer-carousels.mdx
---
title: The case for fewer carousels
description: Carousels hide most of what you put in them. Here is what we build instead.
pubDate: 2026-05-21
author: Priya Raman
tags:
  - Interfaces
  - Web
cover: ../../assets/journal/fewer-carousels/cover.jpg
coverAlt: Person typing on a laptop at a wooden table
featured: false
draft: false
---


Every few months a client asks for a carousel on the home page…
Field Required Notes
title yes The headline
description yes Max 180 characters. Used on cards, in search results and the RSS feed
pubDate yes YYYY-MM-DD. Articles are sorted newest first
updatedDate no Shown on the article when set
author yes One of the names in authors in src/content/taxonomy.ts
tags no Free text. Each tag gets a page at /journal/tag/<tag>
cover yes Image path relative to the file
coverAlt yes Describe the image
featured no The newest featured article leads the journal and the first page skips it
draft no Drafts show in npm run dev and are left out of production builds

Images in the text

Section titled “Images in the text”

Use Markdown image syntax with a path relative to the article. Astro optimises these like every other image.

![Curved glass and steel roof of a station concourse](../../assets/journal/two-languages-one-sign/concourse.jpg)

An image on its own line spans the full text width. Keep an article’s images together in src/assets/journal/<slug>/.

What the theme adds

Section titled “What the theme adds”
  • Reading time, worked out from the text.
  • Related articles at the end: those sharing the most tags, newest first.
  • Tag pages at /journal/tag/<tag>, linked from each article and the journal index.
  • Pagination at /journal/2, /journal/3… Set the page size with journal.pageSize in site.ts.
  • RSS at /rss.xml, with every article in the default language.
  • Structured data: BlogPosting on each article and Blog on the index.
  • A home page teaser with the two newest articles.

Authors

Section titled “Authors”

Authors are a fixed list in src/content/taxonomy.ts so names are always spelled the same way. Replace the demo names with your team; the CMS offers them as a dropdown.

Translating

Section titled “Translating”

Translate an article by copying it into de/ or id/ with the same file name. Untranslated articles still appear in the German and Indonesian journal, in English, with an “In English” label and the right lang attribute. See Translating content.

SwiftAgency is made byLessCodexLicence