Astro Narrow Theme Guide

Astro Narrow is an Astro-native version of the Narrow reading experience. It uses content collections, typed config, Astro components, and build-time Markdown transforms instead of Hugo compatibility code.

Configure site.ts#

src/config/site.ts controls site identity, navigation, layout width, comments, analytics, gallery behavior, and post settings.

export const siteConfig = {
  name: 'Astro Narrow',
  shortName: 'Narrow',
  description: 'A content-focused Astro theme.',
  contentWidth: '56rem'
}

export const siteConfig = {
  nav: ['posts', 'series', 'projects', 'archives'],
  footerNav: ['archives']
}

export const siteConfig = {
  nav: [
    'posts',
    { label: { it: 'GitHub', en: 'GitHub' }, href: 'https://github.com/', icon: 'simple-icons:github' }
  ]
}

Configure Content Types#

src/config/content.ts defines how each content type appears in navigation, lists, cards, and home sections.

export const contentTypes = {
  posts: {
    collection: 'posts',
    path: '/posts/',
    label: { it: 'Articoli', en: 'Posts' },
    cardStyle: 'article',
    listLayout: 'stack',
    gridColumns: 1
  }
}

Frontmatter#

Posts use Astro content collection fields. Keep frontmatter small and predictable.

Categories and tags are discovered automatically from published posts in the current locale. Ordered reading paths are defined separately under src/content/series/<locale>/, so posts do not repeat Series names or chapter numbers. Projects keep their own tags for cards and search, but they do not appear in Archives. Project entries also support featured and links.

links:
  - label: Website
    url: https://example.com
    icon: lucide:external-link
  - label: GitHub
    url: https://github.com/example/repo
    icon: simple-icons:github
featured: true

Markdown Features#

Note

Prefer Markdown-native input. Astro Narrow transforms common patterns with remark and rehype.

Code#

type ColorMode = 'light' | 'dark' | 'auto';

export function setMode(mode: ColorMode) {
  document.documentElement.classList.toggle('dark', mode === 'dark');
}

Gallery#

Math and Mermaid#

Inline math works as $E = mc^2$.