Astro Plain Usage Guide

Astro Plain is a minimalist multilingual static blog template built on Astro, with no CSS / UI framework dependencies. This article includes an introduction to Astro Plain features, configuration instructions, content management, and deployment guides.

Reading time: 6 min
By:
test,Luka
Examples
AstroFrontendBlogTemplateGuide

NOTE

This article was translated using AI.

Key Features

Getting Started

Installation & Running

  1. Clone the repository:

    Terminal window
    git clone https://github.com/Aaakul/astro-plain.git
    Terminal window
    cd astro-plain

  2. Install dependencies:

    Terminal window
    bun install

  3. Start the local development server:

    Terminal window
    bun --bun run dev

    The dev server runs at http://127.0.0.1:4321 by default, and the browser will open automatically on startup.

  4. Static build and local preview:

    Terminal window
    bun --bun run build
    Terminal window
    bun --bun run preview

NOTE

Pagefind relies on static build output to generate its index. You must run the build command at least once before using it in the development environment for the first time. After adding or modifying posts, the dev server will not automatically regenerate the search index.

Configuration

Site Configuration

The core configuration file is located at site.config.ts and supports the following options:

OptionTypeDescriptionDefault
defaultLanguagestringDefault language code"zh-Hans"
ogImagestringDefault Open Graph / social sharing image (automatically prepends basePath)"/static/images/og.jpg"
languageNameMapRecord<string, string>Mapping of language codes to display names{"en-US": "English", "ja-JP": "日本語", "zh-Hans": "简体中文"}
siteUrlstringSite URL (reads from env variable SITE_URL if available)"http://127.0.0.1:4321"
basePathstringSubpath deployment prefix (reads from env variable BASE_PATH if available)""
allowRobotsbooleanWhether to allow crawlerstrue
cookieMaxAgeDays"session" | "none" | numberLanguage preference cookie lifetime (days, disabled, or session)"session"
postsPerPagenumberNumber of posts displayed per page in the blog list5
navLinksArray<{ href, titleKey }>Top navigation bar routes and multilingual key namesSee config file
disqus{ enable, shortname }Disqus comment configuration (can read env variables){ enable: false, shortname: "" }
clarity{ enable, projectId }Microsoft Clarity analytics configuration (can read env variables){ enable: false, projectId: "" }
isShowLogobooleanWhether to show the logo icon in the top navigation bartrue
codeTheme{ light, dark }Expressive Code light and dark highlighting themes{ light: "light-plus", dark: "dark-plus" }

Environment Variables

Refer to the comments in .env.example to create your .env file.

Favicons & Static Assets

  • Favicons and images Replace public/favicon.ico public/favicon.svg public/apple-touch-icon.png src/assets/*
  • Static assets directory (public/static/):
    • Static assets that do not need to be optimized by Vite / Astro build (such as site-wide public images, documents, etc.) can be placed in the public/static/ directory and referenced directly via the /static/... path.

Social Sharing Image (OG Image)

  • Global default sharing image: Configured via the ogImage field in site.config.ts (defaults to "/static/images/og.jpg", corresponding to public/static/images/og.jpg), used as the site-wide Open Graph and social sharing preview image. Recommended dimensions are 1200x630.
  • Post-specific sharing image: If image (post cover image) is configured in the post’s Frontmatter, it will be used preferentially.

Internationalization (i18n)

Language Association Mechanism (translationKey)

This project uses the translationKey field in Frontmatter to establish associations between posts in different languages:

  • Files for the same content in different language versions must declare the same translationKey.
  • Language switch links and corresponding hreflang tags for pages are automatically generated based on translationKey.
  • Blog posts do not need to be organized into language-specific subdirectories like /zh-Hans/.

Adding a New Language

  1. Add the new language code to languageNameMap in site.config.ts (e.g., "fr-FR": "Français").
  2. Create the corresponding dictionary file in the i18n/messages/ directory (e.g., fr-FR.ts).
  3. Import the translation file in i18n/utils.ts.
  4. Create a language directory under src/content/author/<language-code>/ and add the author info file (at least default.mdx).

For more information, see i18n Guide.

Content Authoring Guidelines

Content collections are located in src/content/, with schemas defined in src/content.config.ts.

Hero Section

Files are located at src/content/mdx/<language-code>/hero.mdx.

Posts (src/content/blog/)

Both .md and .mdx formats are supported.

src/content/blog/my-first-post.mdx
---
title: "Post Title" # Required
summary: "Short summary for list display and SEO description" # Optional
translationKey: "unique-key" # Required: used to associate posts across different language versions
language: "zh-Hans" # Required: language code, must be included in `languageNameMap` in `site.config.ts`
date: "2026-08-30T10:00:00Z" # Required: publication date, ISO 8601 format
lastmod: "2026-08-30T12:00:00Z" # Optional: last modified date, ISO 8601 format
isCanonical: true # Optional: whether this is the canonical version of the multilingual post (generates `x-default` and `canonical` links)
draft: false # Optional: draft flag, set to `true` to skip during build
authors: ["default"] # Optional: author list, use corresponding filenames, defaults to `["default"]`
categories: ["Tech"] # Optional: post categories
tags: ["Astro", "Frontend"] # Optional: post tags
enableComments: false # Optional: whether to enable comments for this post, defaults to `true`
image: "@/assets/banner.jpg" # Optional: post cover image at the top
---

Post URL format is /<language-code>/{slugified-file-path}, e.g., /zh-Hans/blog/my-first-post

Author Information (src/content/author/)

This template supports multiple authors. The default author file is default.mdx.

src/content/author/zh-Hans/test.mdx
---
name: "test" # Required: author name
language: "zh-Hans" # Required: language code
avatar: "@/assets/avatar.svg"
occupation: "Full-Stack Engineer"
company: "Acme Inc."
email: "hello@example.com"
link:
  github: "https://github.com/Aaakul"
---
Body content...

Non-default author page URL format is /<language-code>/about/{slugified-filename}, e.g., /zh-Hans/about/test

Project Showcase (src/content/project/)

src/content/project/plain.mdx
---
name: "Astro Plain" # Required: project title
language: "zh-Hans" # Required: language code
website: "https://example.com"
image: "@/assets/project-preview.png"
link:
  github: "https://github.com/Aaakul/astro-plain"
---
Body content...

Markdown Writing Syntax & MDX Component Guide

See Markdown & MDX Writing Guide for examples of Markdown syntax, Expressive Code highlighting, and built-in MDX components such as <Steps>, <FileTree>, and <Tabs>.

Deployment

This project outputs pure static files after building. The build output directory is dist.

Example: Using Cloudflare Pages

  1. Fork this repository to your own GitHub account.

  2. Log in to the Cloudflare Dashboard (opens in a new tab), click Compute -> Workers and Pages -> Create Application -> Continue to Pages, and connect your GitHub repository.

  3. Configure build settings:

    • Build command:

      Terminal window
      npm run build

    • Build output directory: dist

    • Environment variables: Set SITE_URL to the deployed site domain (e.g., https://example.pages.dev), and configure Disqus and Microsoft Clarity as needed.

  4. Save and deploy. Any subsequent push to the main branch will automatically trigger a build and deployment.

Project Directory Structure

  • Directoryi18n/ Multilingual dictionaries, type definitions, and utility functions
    • Directorymessages/ Localization translation key-value files for each language (zh-Hans, en-US, ja-JP)
      • …
    • …
  • Directorylib/ Rehype / Remark plugins and Starlight MDX components
    • …
  • Directorypublic/ Static assets (favicons, OG images, etc.)
    • Directorystatic
      • Directoryimages
        • og.jpg
    • apple-touch-icon.png
    • favicon.ico
    • favicon.svg
    • _headers HTTP response headers configuration (CSP security policy and cache rules)
  • Directorysrc/
    • Directoryassets/ Static assets optimized during build (post images, author avatars)
      • avatar.svg
      • …
    • Directorycomponents/ Astro UI components (navbar, search, comments, MDX components)
      • …
    • Directorycontent/ Content data collections (blog, author, project, hero)
      • …
    • Directorylayouts/ Page layout templates
      • …
    • Directorypages/ Astro route files
      • …
    • Directorystyles/ Global CSS stylesheets
      • …
    • content.config.ts Astro Content Layer collection definitions
  • astro.config.mjs Astro configuration file
  • site.config.ts Site core configuration file
  • package.json Dependencies and run scripts
  • .env.example Environment variable configuration example

License

This project is open-sourced under the MIT License. Stars, PRs, and Issues are welcome.

Last modified:

Related Posts

Last modified:

Internationalization Guide

Examples
Astroi18nInternationalizationGuide

A guide to i18n in Astro Plain: how to use translation functions and add new languages.

Last modified:

Markdown / MDX Writing Guide

Examples
AstroMDXMarkdownExpressive CodeGuide

This guide covers common Markdown syntax, Expressive Code integration in Astro Plain, GitHub-style alert blocks, and how to use MDX components from Starlight.