Welcome to Astro Jing

Astro Jing is a calm blog theme powered by Astro. This post will show you how to use it.

Features:

• Auto-generate post descriptions based on character count or up to the <!-- more --> tag
• Auto-expanding & collapsing table of contents
• Open Graph image generation
• Full-text search
• Syntax highlighting
• Math equations
• Internationalization (i18n)
• Comment systems (Giscus / Disqus)
• Sitemap & RSS feed
• Static site

Usage

git clone https://github.com/ziteh/astro-theme-jing.git
cd astro-theme-jing
pnpm i
pnpm dev

Markdown

Posts

Place your post .md files in the src/content/blog/ directory.

Frontmatter

The YAML frontmatter format for posts broadly compatible with Hexo, the default values for some fields can be changed in the site.ts configuration (with defaultFm prefix).

*: required

About

The Markdown for about page is: src/content/about.md.

about.md does not require frontmatter; it is recommended not to include an h1 (i.e. # Header).

Configuration

There are some settings that need to be adjusted before deployment.

site.ts

src/config/site.ts

Basic site information and feature toggles.

*: important

lang.ts

src/config/lang.ts

Internationalization (i18n) language and locale settings.

Key settings:

• lang: BCP 47 language tag (e.g., en, zh-TW)
• langOg: Open Graph locale tag (e.g., en_US, zh_TW)
• timeZone: IANA time zone (e.g., America/New_York, Asia/Taipei)

To add a new language, modify the myLang object following the en template and update the exported _t constant.

socials.ts

src/config/socials.ts

Social media links displayed in the site footer.

Each social link object contains:

• name: Display name
• title: Hover text
• href: URL to the social profile
• icon: SVG icon component

Example:

{
  name: "GitHub",
  title: "My GitHub",
  href: "https://github.com/username",
  icon: IconGitHub,
}

astro.config.ts

astro.config.ts

Astro config, please refer to Configuration overview and Configuration Reference.

Features

Details of each feature.

Auto-generate Description

If there is no description in the frontmatter, one will be generated automatically. There are two ways this is done:

1. If there is a <!-- more --> tag, the description will be the content from the first line up to the <!-- more --> tag.
2. If there is no <!-- more --> tag, the first getDescriptionCount characters will be used.

For performance reasons, only the first getDescriptionMaxLines lines of each .md file will be processed.

You can adjust getDescriptionCount and getDescriptionMaxLines in site.ts.

Fonts

By default, Astro Jing downloads Noto Sans (body) and Fira Mono (code) at build time via Astro’s built-in font API.

If you prefer system-native fonts — for example, to use Traditional Chinese fonts like PingFang TC / Microsoft JhengHei without any web font download — you can switch manually:

1. astro.config.ts — Remove the --font-body and --font-mono entries from the fonts array. Keep --font-og (Satori needs it to generate OG images).

fonts: [
  // Remove --font-body and --font-mono entries
  {
    cssVariable: "--font-og",
    name: "Noto Sans",
    weights: [400],
    styles: ["normal"],
    formats: ["woff"],
    provider: fontProviders.fontsource(),
  },
],

2. src/layouts/BaseLayout.astro — Replace the two <Font> tags with an inline style that defines the CSS variables directly:

<!-- Replace: -->
<Font cssVariable="--font-body" preload />
<Font cssVariable="--font-mono" />

<!-- With: -->
<style is:inline>
  :root {
    --font-body:
      "PingFang TC", "Microsoft JhengHei", "Noto Sans TC", system-ui, -apple-system,
      BlinkMacSystemFont, "Segoe UI", sans-serif;
    --font-mono: ui-monospace, "Cascadia Code", Menlo, Monaco, Consolas, "Courier New", monospace;
  }
</style>

Use is:inline so Astro does not scope the <style> tag — scoped styles would prevent :root from applying globally.

All other CSS files (global.css, post.css, etc.) already use var(--font-body) and var(--font-mono) and require no changes.

Syntax highlighting

Astro Jing uses Expressive Code for syntax highlighting; please refer to https://expressive-code.com/

You can adjust its config in astro.config.ts. Themes

Example:

export default defineConfig({
  // ...
  integrations: [
    expressiveCode({
      plugins: [pluginLineNumbers()],
      themes: ["catppuccin-latte", "one-dark-pro"],
      defaultProps: {
        wrap: false,
        showLineNumbers: false,
      },
    }),
    // ...
  ],
});

Deploy

You can easily deploy Astro Jing to a variety of platforms, including GitHub Pages, Netlify, Cloudflare, Vercel, and more, please refer to Deploy your Astro Site.