Astro Narrow

Astro Narrow is a multi-color Astro blog theme, migrated from Hugo Narrow, that produces a static site with built-in search, multilingual content, math and diagram rendering, and configurable gallery layouts.

What is Astro Narrow?

Astro Narrow is a blogging theme built on the Astro framework and styled with Tailwind CSS. It takes Markdown content placed in content collections and generates a static website with posts, projects, series, and archive pages. The theme is a direct migration of the Hugo Narrow design, so it retains the original narrow-column layout while adding Astro-specific tooling. The project is licensed under the GNU General Public License Version 3.

Key Features

• Multiple color palettes — A dock exposes several themes that visitors can switch from the interface, configured through the themes option in src/config/theme.ts.
• Search — Visitors can search the site's content without an external search service.
• Multilingual support — Locales and display names are defined in src/config/i18n.ts, and each locale gets its own content directories; adding a locale requires updating astro.config.mjs and src/content.config.ts.
• Math and diagrams — The theme renders mathematical formulas and diagrams from Markdown content, useful for technical or academic posts.
• Multiple gallery layouts — Gallery display options are controlled via the gallery setting in src/config/site.ts, giving authors layout choices for image collections.
• Table of contents — Post pages can show an auto-generated table of contents for navigation inside long articles.
• Content taxonomy — Posts use string-array categories and tags; projects use only tags, and pages use neither; archive URLs like /archives/?category=Guides can be shared directly.
• Ordered series — Series are defined as Markdown files with a chapters array of post IDs; a series and its chapters must share a locale, and each post can appear in only one public series.
• GitHub Pages workflow — A ready-to-use deployment workflow sits in .github/workflows/deploy.yml; it sets ASTRO_SITE and ASTRO_BASE automatically for user and project pages.

Who is it for?

• Bloggers who want a clean, narrow-column reading layout with a theme switcher and local search.
• Technical writers who publish tutorials or documentation with math, diagrams, and ordered chapter series.
• Multilingual content creators who need separate locale directories and i18n configuration for each language.
• Astro developers who want a configurable starting point for a personal site with posts, projects, and archives.

What can you do with Astro Narrow?

• Structure long-form writing — Organize posts into ordered series, each with an introduction page under /series/<slug>/, so readers follow chapters in sequence.
• Publish mixed content types — Use categories for broad groups like Guides or Essays, and tags for specific topics; projects and pages have their own taxonomy rules.
• Customize navigation — Configure nav and footerNav in site.ts to show posts, series, projects, and archives; custom nav items need localized labels, a URL, and a Lucide icon.
• Deploy to GitHub Pages — Push the repository and rely on the included workflow; just set the Pages source to GitHub Actions before the first deployment.

How does Astro Narrow work?

The theme uses content collections defined in src/content.config.ts to validate frontmatter. Markdown files are placed under src/content/posts/<locale>/ and src/content/series/<locale>/, then the site is built with pnpm build. Configuration is centralized in TypeScript files: site behavior in site.ts, content listing defaults in content.ts, locale metadata in i18n.ts, and theme palettes in theme.ts. The remark-directive syntax enables Markdown tabs that can contain nested code blocks.

FAQ

Is Astro Narrow free?

Yes, the theme is open source under the GNU General Public License Version 3, so you can use and modify it freely with the same license.

Does Astro Narrow support multiple languages?

Yes. Locales are defined in src/config/i18n.ts, and content is organized per locale. When you add a locale, you must also update the i18n.locales field in astro.config.mjs and the allowed lang values in src/content.config.ts.

What frontmatter fields are available?

Posts accept title, pubDate, categories, and tags, where categories and tags are string arrays. Projects use only tags, and pages use neither. Series files use title, description, chapters, draft, and lang.

Can I deploy Astro Narrow to GitHub Pages?

Yes, the repository includes a deployment workflow in .github/workflows/deploy.yml. Before the first run, set your repository Settings > Pages > Build and deployment source to GitHub Actions; otherwise the deploy action can fail with an HTTP 404 error.

How do I create a series?

Create a Markdown file under src/content/series/<locale>/. Its filename becomes the URL slug, and the frontmatter requires title and a chapters array with at least two post IDs. All chapters must be published and belong to the same locale.