Shirone Authoring & Usage Guide

Welcome to Shirone (白音) — an expressive, anime-inspired blog theme crafted around Astro 7, Svelte 5, and the Material 3 Expressive (M3E) design system.

This guide walks you through post creation, frontmatter specifications, directory structure, and the full suite of built-in Markdown and MDX extensions.

TIP
Shirone renders content server-side first (SSR-first). When navigating within the site, Swup seamlessly swaps the main container while preserving the outer application shell and continuous music playback.

1. Creating a New Post#

You can quickly scaffold a new post with standard frontmatter using the built-in CLI command:

1
# Create a single-file post
2
pnpm new-post my-first-post
3

4
# Or create a post in a sub-directory
5
pnpm new-post guides/getting-started

The newly created file will be placed in src/content/posts/.

2. Frontmatter Specification#

Every Markdown (.md) or MDX (.mdx) post starts with a YAML frontmatter block defining its metadata.

Example#

1
---
2
title: "Exploring Material 3 Expressive Design"
3
published: 2026-08-26
4
updated: 2026-08-27
5
pinned: true
6
description: "A deep dive into dynamic HCT color science and fluid transitions in Shirone."
7
image: "./cover.webp"
8
tags: [M3E, Design, Frontend]
9
category: Guides
10
draft: false
11
comment: true
12
---

Supported Frontmatter Fields#

Field	Type	Required	Description
`title`	`string`	Yes	The main title of the post.
`published`	`Date`	Yes	Publication date in `YYYY-MM-DD` format.
`updated`	`Date`	No	Last updated date. When provided, an update notice badge is displayed.
`pinned`	`boolean`	No	Pin the post to the top of article lists (default: `false`).
`description`	`string`	No	Post summary displayed in article cards, search results, and OpenGraph metadata.
`image`	`string`	No	Cover image path. Supports relative (`./cover.webp`), public (`/images/cover.jpg`), or remote URLs.
`tags`	`string[]`	No	Array of tag names for taxonomy filtering and tag clouds.
`category`	`string`	No	Primary category name for taxonomy indexing.
`draft`	`boolean`	No	Mark as draft. Draft posts are hidden during production build (`pnpm build`).
`comment`	`boolean`	No	Toggle comment section for this specific post (default: `true`).
`lang`	`string`	No	Language code (e.g. `en`, `zh_CN`, `ja`) if different from site default.

3. Post Encryption#

Shirone provides client-side post encryption. For private journals or restricted articles, specify a password in frontmatter:

1
---
2
title: "Private Research Notes"
3
published: 2026-08-26
4
encrypted: true
5
password: "your-secret-passphrase"
6
passwordHint: "Favorite anime character"
7
hideHomeContent: true
8
---

encrypted: Set to true to enable encryption;
password: Passphrase string or number required to unlock the post;
passwordHint: Optional hint shown above the password entry form;
hideHomeContent: Hide word counts and content previews on the homepage to prevent data leakage.

4. Organizing Post Files#

Shirone supports both folder-based co-location and single-file layouts:

Folder Structure (Recommended for Local Assets)#

Co-locating your post and its media makes asset management straightforward:

1
src/content/posts/
2
├── my-great-post/
3
│   ├── index.md           <-- Post content
4
│   ├── cover.webp         <-- Cover image (image: "./cover.webp")
5
│   └── diagram.png        <-- Inline illustration referenced in markdown

Single-File Structure (Lightweight Prose)#

1
src/content/posts/
2
├── hello-world.md
3
└── quick-thoughts.md

5. Rich Markdown & MDX Extensions#

Shirone includes modern Markdown extensions out of the box:

5.1 Admonitions#

Use container directives for notes, tips, warnings, and alerts:

1
:::tip
2
Use admonition containers to highlight key takeaways or best practices.
3
:::
4

5
:::warning
6
Use warning containers to signal potential pitfalls or breaking changes.
7
:::

5.2 GitHub Repository Cards#

Embed live, beautifully styled GitHub repository cards using the directive syntax:

1
::github{repo="LyraVoid/Shirone"}

LyraVoid

Shirone

Waiting for api.github.com...

00K

Waiting...

5.3 Expressive Code Blocks#

Enhanced code blocks feature syntax highlighting, file name badges, line numbers, and selective line highlighting:

1
// Dynamic HCT color token derivation
2
import { argbFromHex, themeFromSourceColor } from "@material/material-color-utilities";
3

4
const theme = themeFromSourceColor(argbFromHex("#f472b6"));
5
console.log("Primary color token:", theme.schemes.light.primary);

5.4 Mathematical Typesetting (KaTeX)#

Render elegant LaTeX mathematical notation directly in Markdown:

Inline math: $E = mc^2$ or Euler’s formula $e^{i\pi} + 1 = 0$ .
Block math:

\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}

5.5 Mermaid Diagrams#

Create flowcharts, sequence diagrams, and architecture maps using plain text:

sequenceDiagram
    autonumber
    actor Visitor as Visitor
    participant Page as Shirone Page
    participant Swup as Swup Container
    participant Audio as Persistent Shell

    Visitor->>Page: Click Navigation Link
    Page->>Swup: Trigger Seamless Transition
    Swup->>Page: Replace #swup-container
    Note over Audio: Background music plays continuously
    Page-->>Visitor: New Page Rendered

Images automatically integrate with Fancybox for lossless zoom, pan gestures, and full-screen preview:

1
![Cover preview](./cover.jpeg)

6. Next Steps & Customization#

Site Configuration: Learn about global settings in src/config/siteConfig.ts and src/config/README.md.
Design Tokens: Explore tokens and color palettes in DESIGN.md and docs/m3e-standard.md.
Feedback & Community: Share your ideas and questions on GitHub Issues.

Shirone

1. Creating a New Post#

2. Frontmatter Specification#

Example#

Supported Frontmatter Fields#

3. Post Encryption#

4. Organizing Post Files#

Folder Structure (Recommended for Local Assets)#

Single-File Structure (Lightweight Prose)#

5. Rich Markdown & MDX Extensions#

5.1 Admonitions#

5.2 GitHub Repository Cards#

5.3 Expressive Code Blocks#

5.4 Mathematical Typesetting (KaTeX)#

5.5 Mermaid Diagrams#

6. Next Steps & Customization#

继续阅读

换条路线

Shirone

1. Creating a New Post#

2. Frontmatter Specification#

Example#

Supported Frontmatter Fields#

3. Post Encryption#

4. Organizing Post Files#

Folder Structure (Recommended for Local Assets)#

Single-File Structure (Lightweight Prose)#

5. Rich Markdown & MDX Extensions#

5.1 Admonitions#

5.2 GitHub Repository Cards#

5.3 Expressive Code Blocks#

5.4 Mathematical Typesetting (KaTeX)#

5.5 Mermaid Diagrams#

5.6 Image Galleries & Fancybox Lightbox#

6. Next Steps & Customization#

分享文章

沿着主题读

换条路线