Touchfish.blog

Shirone Authoring & Usage Guide

Wed, 26 Aug 2026 00:00:00 GMT

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:

# Create a single-file post
pnpm new-post my-first-post

# Or create a post in a sub-directory
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

---
title: "Exploring Material 3 Expressive Design"
published: 2026-08-26
updated: 2026-08-27
publishedAt: 2026-08-26T10:00:00+08:00
updatedAt: 2026-08-27T09:30:00+08:00
pinned: true
description: "A deep dive into dynamic HCT color science and fluid transitions in Shirone."
image: "./cover.webp"
tags: [M3E, Design, Frontend]
category: Guides
draft: false
comment: true
---

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.
`publishedAt`	`Date`	No	Precise publication instant used to order posts published on the same day. It must fall on `published` in the configured site time zone.
`updated`	`Date`	No	Last updated date. When provided, an update notice badge is displayed.
`updatedAt`	`Date`	No	Precise update instant used by feeds and machine-readable metadata. It must be paired with `updated`.
`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:

---
title: "Private Research Notes"
published: 2026-08-26
encrypted: true
password: "your-secret-passphrase"
passwordHint: "Favorite anime character"
hideHomeContent: true
---

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:

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

Single-File Structure (Lightweight Prose)

src/content/posts/
├── hello-world.md
└── 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:

:::tip
Use admonition containers to highlight key takeaways or best practices.
:::

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

5.2 GitHub Repository Cards

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

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

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

5.3 Expressive Code Blocks

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

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

const theme = themeFromSourceColor(argbFromHex("#f472b6"));
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

5.6 Image Galleries & Fancybox Lightbox

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

![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.

🔒 Password Protection and Post Encryption Demo

Thu, 20 Aug 2026 00:00:00 GMT

🔒 本文已加密保护，请访问博客网站输入密码阅读全文。

Shirone Markdown Enhancements

Wed, 19 Aug 2026 00:00:00 GMT

Shirone provides a collection of theme-exclusive Markdown extensions and custom syntax containers. Built on top of our native unified AST processing pipeline, all extensions render into accessible, semantic HTML during site build time with zero client JavaScript hydration overhead and 100% M3E design token alignment.

File Trees

File Trees turn multi-level project structures, source hierarchies, and terminal directory outputs into compact, interactive tree views with automatic extension icons, diff highlighting, and collapsible branches.

1. Nested List Syntax (`:::file-tree`)

Use the :::file-tree block directive when writing the file hierarchy directly as a Markdown nested list.

:::file-tree{title="Shirone source tree"}
- src
  - components/
    - ++ Navigation.svelte # added component
    - -- Button.astro # removed component
  - content
    - posts/
      - markdown-enhancements.md
  - layouts/
    - PostLayout.astro
  - plugins
    - markdown/
      - rehype-file-tree.mjs
  - styles
    - markdown/
      - trees.css
  - **content.config.ts** # important file
- public/
  - favicon.svg
- package.json
:::

:::file-tree{title="Shirone source tree"}

src
- components/
  - ++ Navigation.svelte # added component
  - -- Button.astro # removed component
- content
  - posts/
    - markdown-enhancements.md
- layouts/
  - PostLayout.astro
- plugins
  - markdown/
    - rehype-file-tree.mjs
- styles
  - markdown/
    - trees.css
- content.config.ts # important file
public/
- favicon.svg
package.json :::

Authoring Rules & Markers

Diff States: Prefix an item with ++ (green background & badge) or -- (red background & strikethrough) to highlight changes.
Comments: Any text following a # is rendered as a muted, right-aligned inline comment.
Emphasis: Wrap names in **bold** to give key files prominent visual weight.
Collapsible Folders: Directories inferred from nested list items start expanded by default. Add a trailing slash (e.g. components/) to create a collapsed directory that readers can expand on click or via keyboard navigation.

2. Terminal Output Syntax (```file-tree)

When you already have directory tree text generated from command-line tools like tree, paste it directly into a file-tree fenced code block. Both Unicode branch characters (├──, └──, │) and ASCII branches are automatically parsed.

```file-tree title="Build output" icon="simple"
dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico
```

dist
├── _astro/
│   ├── index.css
│   └── page.js
└── favicon.ico

Configuration Options

title="string": Sets a custom header title and accessible label for the tree.
icon="colored" | "simple": Choose between multi-color extension icons (colored, default) or minimal monochrome icons (simple).

Code Trees

Interactive Code Trees pair a multi-level file hierarchy navigation pane on the left with instant code panel switching on the right. They provide an IDE-like reading experience for multi-file examples, modules, or whole directory walk-throughs.

1. Container Syntax (`:::code-tree`)

Combine multiple fenced code blocks within a :::code-tree block directive. Each code block specifies its path via title="path/to/file".

:::code-tree{title="Shirone Component Demo" height="380px" entry="src/Button.svelte"}
```svelte title="src/Button.svelte"
<script lang="ts">
  let { label = "Click me" } = $props();
</script>

<button class="m3-btn">{label}</button>
```

```stylus title="src/styles/button.styl"
.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)
```

```json title="package.json"
{
  "name": "button-demo",
  "version": "1.0.0"
}
```
:::

:::code-tree{title="Shirone Component Demo" height="380px" entry="src/Button.svelte"}

<script lang="ts">
  let { label = "Click me" } = $props();
</script>

<button class="m3-btn">{label}</button>

.m3-btn
  background: var(--primary)
  color: var(--on-primary)
  border-radius: var(--shape-corner-m)

{
  "name": "button-demo",
  "version": "1.0.0"
}

:::

Configuration & Markers

title="string": Sets the header title and accessible label for the code tree.
height="string": Sets the height for the desktop view (default 420px, e.g. 380px, 26rem).
entry="filepath": Specifies which file is active upon first load.
icon="colored" | "simple": Switch between colorful or minimal monochrome file icons.
:active: Place :active on any fenced code block to designate it as the default active tab.

2. Local Directory Auto-Import (`@[code-tree]`)

Point directly to any local directory path in the workspace to automatically scan and generate an interactive code tree at build time without manually copying file contents.

@[code-tree title="Anime Utilities" entry="status.ts"](/src/utils/anime)

@code-tree title="Site Configuration" entry="siteConfig.ts"

Audio Reader: Japanese Anime Mystery Voices

Sat, 29 Aug 2026 00:00:00 GMT

These short Japanese voice fragments feel as though they were picked up from the edge of an anime scene: a teasing call, a bright greeting, a tiny laugh, and a few lines with no clear origin. They are mood samples rather than dialogue transcripts, so let the sound carry the meaning.

Audio Reader keeps them quiet until you choose to listen. Each speaker button loads and plays its clip only after it is pressed.

:audio-reader[Clip title]{src="/assets/audio/filename.wav"}

The fragments

Baka: :audio-reader[バカ]{src="/assets/audio/Baka.wav"}
Ciallo: :audio-reader[Ciallo！！]{src="/assets/audio/Ciallo.wav"}
Ehe: :audio-reader[A joking sense]{src="/assets/audio/Ehe.wav"}
Imoi: :audio-reader[イモい]{src="/assets/audio/Imoi.wav"}
Zako: :audio-reader[雑魚じゃん、雑魚雑魚]{src="/assets/audio/Zako.wav"}

src must use a site-root path or an HTTPS URL, and the directive label cannot be empty. Invalid or incomplete directives remain ordinary Markdown and do not load Audio Reader resources.

Markdown Collapse Panels

Fri, 28 Aug 2026 00:00:00 GMT

Collapse panels keep related optional details in one compact group. Titles and bodies retain inline and block Markdown, while native disclosure semantics make every panel usable without client JavaScript.

Independent panels

Items open independently by default. Prefix a title with :+ to open that item initially or :- to keep it closed when the group uses expand.

::: collapse

Package requirements

Use Node.js 22 or newer and enable Corepack before installing packages.
:+ Install dependencies

Run the workspace package command from the repository root.
```
pnpm.cmd install
```
Validation commands

Check the content pipeline before building the production output.
- pnpm.cmd check:manifest
- npx.cmd astro check :::

Accordion mode

Add accordion when only one answer should remain open. The browser groups the native disclosures directly, so opening another item closes the previous one without hydration.

::: collapse accordion expand

What does expand do here?

It opens the first item initially when no item has a :+ marker.
Can a title contain Markdown?

Yes. Titles support inline emphasis and code, while panel bodies support full block Markdown.
What happens on a narrow screen?

Content padding becomes compact, long text wraps, and embedded code keeps its own horizontal scrolling area. :::

Author syntax

::: collapse accordion
- :+ First title

  First panel content.

- Second title with `code`

  Second panel content.
:::

The container must contain exactly one top-level unordered list. Every item needs a title paragraph, a blank line, and body content. Invalid or mixed input remains an ordinary readable Markdown list.

Markdown Abbreviations

Fri, 28 Aug 2026 00:00:00 GMT

Abbreviations keep technical writing compact while preserving the full term for readers who need it. A defined term renders as a native abbr element with its meaning available on hover and to assistive technology.

In context

SSR-first output keeps the initial document visible before JavaScript runs. When measuring its reading experience, LCP and CLS reveal whether the first visible content is fast and stable.

An abbreviation can also appear next to ordinary Markdown such as SSR guidance, but literal code such as SSR and links like LCP documentation remain untouched.

Define terms

Place definitions anywhere in the same Markdown document. They do not render as visible paragraphs, and only matching terms in that article receive the semantic abbreviation treatment.

*[SSR]: Server-Side Rendering
*[LCP]: Largest Contentful Paint
*[CLS]: Cumulative Layout Shift

SSR makes an HTML response available before client code runs.

*[SSR]: Server-Side Rendering *[LCP]: Largest Contentful Paint *[CLS]: Cumulative Layout Shift

Authoring boundaries

Terms must begin with a letter or number and may contain letters, numbers, periods, underscores, plus signs, and hyphens. Each definition applies to the current article only; an invalid or duplicate definition remains ordinary Markdown instead of silently replacing another term.

Markdown File Includes

Fri, 28 Aug 2026 00:00:00 GMT

Shirone can include a local Markdown file or a safe slice of one.

The full file and line-range forms are also supported:

<!-- @include: src/content/snippets/include-example.md -->
<!-- @include: src/content/snippets/include-example.md{1-4} -->
<!-- @include: src/content/snippets/include-example.md{5-} -->
<!-- @include: src/content/snippets/include-example.md{-4} -->

Include comments inside fenced code remain literal.

Markdown Marker Highlights

Fri, 28 Aug 2026 00:00:00 GMT

Marker highlights bring attention to a specific phrase without turning the surrounding paragraph into a separate component. They render as native <mark> elements during the build and inherit the active M3E color system.

Default emphasis

Use ==text== when the article's primary color should carry the emphasis. This is useful for ==one decision that readers should retain== while they continue through an ordinary paragraph.

The marker may contain ==nested Markdown emphasis== when the phrase needs a stronger hierarchy.

Semantic colors

Use a suffix when the meaning needs a different tonal role. The available variants are primary, secondary, tertiary, error, and tip.

==Primary connects the phrase to the active theme=={.primary}
==Secondary keeps a supporting distinction quiet=={.secondary}
==Tertiary adds a separate editorial signal=={.tertiary}
==Error identifies a condition that needs correction=={.error}
==Tip highlights practical guidance=={.tip}

Author syntax

==Primary marker==

==Secondary marker=={.secondary}
==Tertiary marker=={.tertiary}
==Error marker=={.error}
==Tip marker=={.tip}

Inline code such as ==literal marker syntax== and fenced examples stay literal, so documentation can explain the syntax without triggering it.

Markdown Option Groups

Fri, 28 Aug 2026 00:00:00 GMT

Option groups keep equivalent instructions together without repeating the surrounding explanation. Each option accepts full block Markdown, while the selected value can synchronize with another group on the same page.

Choose a package manager

Use @tab:active to select the initial option. A suffix after # supplies a stable value without changing the visible title.

::: tabs#package-manager

@tab npm

Install the package with npm:

npm install astro

@tab:active pnpm#pnpm

Install the package with pnpm:

pnpm.cmd add astro

@tab Bun#bun

Install the package with Bun:

bun add astro

:::

Run the project

This group shares the package-manager id. Selecting an option above updates the matching command below and remembers that choice for the next visit.

::: tabs#package-manager

@tab npm

npm run dev

@tab pnpm

pnpm.cmd dev

@tab Bun#bun

bun run dev

:::

Many alternatives

Longer option rows remain on one line and scroll within their own navigation area on narrow screens.

::: tabs

@tab Local workstation

Use the local toolchain while developing a feature.

@tab Hosted preview environment

Publish a temporary preview for review.

@tab Continuous integration

Run deterministic validation for every change.

@tab Production deployment

Promote a verified artifact to production.

@tab Offline recovery workflow

Restore from a local artifact when the network is unavailable.

:::

Author syntax

::: tabs#package-manager

@tab npm

Use npm instructions here.

@tab:active **pnpm**#pnpm

Use pnpm instructions here.

:::

Each group needs at least two @tab sections, and every section needs body content separated from its marker by a blank line. Invalid or incomplete groups remain readable as ordinary Markdown.

Markdown Spoilers

Fri, 28 Aug 2026 00:00:00 GMT

Spoilers conceal a short answer or plot detail without removing it from the document. Hover, focus, or activate the native control to reveal the content.

Inline details

The answer is :spoiler[42], and this sentence remains ordinary Markdown around it.

Spoilers can include inline code and :spoiler[a longer detail with emphasis].

Author syntax

The answer is :spoiler[42].

The generated HTML uses a native button with an aria-expanded state. Without JavaScript, hover and focus still reveal the text; the optional runtime adds click and keyboard toggling.

Markdown Admonitions

Thu, 27 Aug 2026 00:00:00 GMT

Admonitions keep supporting information visually distinct while preserving the article's reading flow. Every form is rendered on the server and uses the same compact M3E component.

Semantic variants

::: note Deployment context The spaced form accepts a plain custom title while remaining compatible with the reference syntax. :::

:::info Use information blocks for neutral context that helps readers understand the surrounding section. :::

:::tip[Existing label syntax] The original bracket label remains available and can contain inline Markdown emphasis. :::

[!IMPORTANT] GitHub Alert syntax enters the same renderer, so existing articles keep one visual language.

:::warning Check environment variables before running a production build. :::

:::caution Do not publish credentials, local configuration, or private keys with an example. :::

Optional details

::: details Inspect the complete command The disclosure uses native browser semantics and remains keyboard accessible without client JavaScript.

npx.cmd astro check
pnpm.cmd build

It starts closed.
Long code can scroll inside its own code block.
The container remains within the article width on narrow screens. :::

Author syntax

:::note[Existing title syntax]
Content
:::

::: warning Plume-compatible title syntax
Content
:::

> [!TIP]
> GitHub Alert syntax

::: details Optional content
Hidden until the reader opens it.
:::

Content Annotations

Thu, 27 Aug 2026 00:00:00 GMT

Content annotations keep supporting context close to a sentence without placing it directly in the reading flow. Activate the small note marker to reveal its content.

Basic syntax

Add a [+label] reference in ordinary prose, then define the matching note elsewhere in the same article.

Astro renders most of a page ahead of time and hydrates **interactive islands** [+islands] only when they need to become interactive.

[+islands]:
  An island is an interactive UI component surrounded by static HTML. This keeps the default page lightweight while preserving focused interactivity.

Astro renders most of a page ahead of time and hydrates interactive islands [+islands] only when they need to become interactive.

[+islands]: An island is an interactive UI component surrounded by static HTML. This keeps the default page lightweight while preserving focused interactivity.

Rich content

Definitions may contain paragraphs, emphasis, links, lists, and inline code [+rich-note] while the surrounding sentence continues normally.

[+rich-note]: Authoring guidance

Keep the first sentence self-contained.
Use a link when readers may need the primary source.
Prefer concise examples such as client:visible.

See the Astro islands documentation for the full model.

Multiple definitions

Reuse a label [+review] to present a short sequence of related notes behind one marker.

[+review]: Start with the decision that changes the reader's next action. [+review]: Keep implementation evidence separate from background context. [+review]: Remove details that belong in the main article instead of the annotation.

Undefined references such as [+missing] remain ordinary text, so an unfinished definition never creates an empty control.

Markdown Steps

Thu, 27 Aug 2026 00:00:00 GMT

Use Steps for procedures whose order matters. The component keeps the article reading flow intact: a quiet numbered rail provides orientation while headings, paragraphs, links, lists, and code retain their native Markdown roles.

Ordered list syntax

Wrap one Markdown ordered list in a :::steps container. Each top-level list item becomes one step.

:::steps[Production deployment]
1. **Clone and prepare the workspace**

   Clone the repository and enter the project directory.

   ```powershell
   git clone https://github.com/LyraVoid/Shirone.git
   Set-Location Shirone
   ```

2. **Install dependencies**

   Use the repository's pinned package manager.

   ```powershell
   pnpm.cmd install
   ```

3. **Run project checks**

   Confirm Astro diagnostics and TypeScript checks pass.

   ```powershell
   npx.cmd astro check
   pnpm.cmd type-check
   ```

4. **Build the production site**

   Generate the static site and search index.

   ```powershell
   pnpm.cmd build
   ```
:::

:::steps[Production deployment]

Clone and prepare the workspace

Clone the repository and enter the project directory.
```
git clone https://github.com/LyraVoid/Shirone.git
Set-Location Shirone
```
Install dependencies

Use the repository's pinned package manager.
```
pnpm.cmd install
```
Run project checks

Confirm Astro diagnostics and TypeScript checks pass.
```
npx.cmd astro check
pnpm.cmd type-check
```
Build the production site

Generate the static site and search index.
```
pnpm.cmd build
```

:::

Options

:::steps[Title] or title="Title" adds a visible label and accessible name.
start=4 changes the first displayed step number.
The container must contain exactly one ordered list. Invalid or mixed input remains ordinary readable Markdown instead of being interpreted heuristically.
Rendering is completed during the site build and adds no client JavaScript or network requests.

MDX Integration and M3E Atomic Components

Thu, 20 Aug 2026 00:00:00 GMT

:::tip MDX (Markdown + JSX) bridges the gap between static writing and application interfaces. In Shirone, authors can seamlessly mix dynamic logic, reactive Svelte 5 components, and Material 3 design tokens directly within post content. :::

1. Markdown vs MDX Capability Matrix

Feature	Standard Markdown (`.md`)	Shirone MDX (`.mdx`)	Execution Mode
Typography & Structure	Full Support	Full Support	Static SSR
Code Highlighting	Line Numbers, Frames, Collapsible	Line Numbers, Frames, Collapsible	Static SSR (Expressive Code)
Diagrams & Mathematics	Mermaid, KaTeX	Mermaid, KaTeX	Client Enhanced
Callout Admonitions	Note, Tip, Important, Warning, Caution	Note, Tip, Important, Warning, Caution	Static SSR
M3E Display Atoms	Not Available	Direct Integration (``, `<Skeleton>`)	Pure SSR (Zero Client JS)
Svelte 5 Reactive Islands	Not Available	On-Demand Hydration (`<Button>`, `<Switch>`)	`client:visible` Lazy Hydrated
Feedback & Loading Atoms	Not Available	Animated Morph (`<LoadingIndicator>`)	`client:visible` Reactive
Dynamic JSX Expressions	Not Available	Native Evaluation (`{authorInfo.ui}`)	Compile-Time / Client

2. Dynamic Expressions and Data Mapping

MDX allows declaring scoped constants using export const at the top of the file, which can be evaluated inline or mapped across templates:

Core Framework: {authorInfo.framework}
UI Engine: {authorInfo.ui}
Design Tokens: {authorInfo.tokens}
Architecture Pattern: {authorInfo.architecture}

Arrays and collections can be rendered dynamically into grid layouts:

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6"> {showcaseItems.map((item, idx) => ( <div key={item.name} class="p-4 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]"> <div class="flex items-center gap-2 mb-1"> <span class="w-6 h-6 rounded-full bg-[var(--primary)] text-[var(--on-primary)] text-xs flex items-center justify-center font-bold"> {idx + 1} </span> <span class="font-bold text-[var(--on-surface)]">{item.name}</span> </div> <p class="text-sm text-[var(--on-surface-variant)] m-0">{item.desc}</p> </div> ))} </div>

3. M3E Display and Layout Primitives (SSR-Only)

In accordance with Shirone's component architecture (docs/atomic-structure.md), stateless display components output clean, accessible semantic HTML with no client-side runtime payload.

3.1 Card Containers (`Card.svelte`)

<div class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6"> <Card variant="filled" class="!p-5"> <div class="font-bold text-[var(--primary)] mb-2">Filled Card</div> <div class="text-sm text-[var(--on-surface-variant)]">Default container background with no elevation shadow. Ideal for grouped content blocks.</div>

<div class="font-bold text-[var(--primary)] mb-2">Elevated Card</div>
<div class="text-sm text-[var(--on-surface-variant)]">Level 1 container elevation with interactive state layering for heightened visual focus.</div>



<div class="font-bold text-[var(--primary)] mb-2">Outlined Card</div>
<div class="text-sm text-[var(--on-surface-variant)]">A crisp 1px outline boundary providing clean separation on neutral surfaces.</div>

</div>

3.2 Accent Bars and Badges (`AccentBar` & `Badge`)

<div class="flex-1"> <span class="font-bold text-lg">System Announcement</span> <p class="text-xs text-[var(--on-surface-variant)] m-0">Combine AccentBar with Badge to build prominent visual callouts</p> </div> M3E v0.192 </div>

3.3 Skeleton Placeholders (`Skeleton.svelte`)

For previewing layout skeletons or prototyping async states:

<div class="flex flex-col gap-1.5 flex-1">
  
  
</div>

</div>

4. Feedback and Loading Indicators

Shirone features full-fidelity Material 3 Expressive motion and feedback atoms:

4.1 Morphing Loading Indicator (`LoadingIndicator.svelte`)

Implemented with androidx.graphics.shapes polygon morphing, providing smooth spring-interpolated 7-shape animations:

</div>
<span class="text-xs text-[var(--on-surface-variant)]">Indeterminate Shape Morph</span>

</div>

</div>
<span class="text-xs text-[var(--on-surface-variant)]">Contained Circular Variant</span>

</div>

</div>
<span class="text-xs text-[var(--on-surface-variant)]">Determinate Progress (68%)</span>

</div> </div>

4.2 Linear and Indeterminate Progress (`ProgressIndicator.svelte`)

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]"> <div class="flex flex-col gap-2"> <div class="flex justify-between text-xs text-[var(--on-surface-variant)]"> <span>Pipeline Compilation</span> <span>80%</span> </div>

</div>

<div class="flex flex-col gap-2 mt-2"> <div class="text-xs text-[var(--on-surface-variant)]">Continuous Dual-Line Animation</div>

</div> </div>

5. Interactive Svelte 5 Islands

Components declared with client:visible are lazy-hydrated via IntersectionObserver when entering the viewport:

5.1 Button Matrix (`Button.svelte`)

<div class="flex flex-wrap items-center gap-3 my-6 p-4 rounded-xl border border-[var(--outline-variant)]"> Filled Button Elevated Tonal Button Outlined Text Button </div>

5.2 Filter Chips and Segmented Buttons (`Chips` & `SegmentedButton`)

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]"> <div> <div class="text-xs font-bold text-[var(--on-surface-variant)] mb-2">M3E Filter Chips</div>

</div>

<div> <div class="text-xs font-bold text-[var(--on-surface-variant)] mb-2">Segmented Control</div>

</div> </div>

5.3 Switches, Checkboxes, and Sliders (`Switch`, `Checkbox`, `Slider`)

<div class="flex flex-col gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)]"> <div class="flex items-center justify-between"> <span class="font-bold text-sm">Switch with Status Icons</span>

</div>

<div class="flex items-center justify-between"> <span class="font-bold text-sm">Selection Checkboxes</span> <div class="flex items-center gap-4">

</div>

</div>

<div class="flex flex-col gap-2"> <span class="font-bold text-sm">Hue Spectrum Slider</span>

</div> </div>

5.4 Input Controls (`TextField.svelte`)

</div>

6. Markdown Extension Compatibility

Shirone's SSOT unified plugin pipeline preserves full compatibility with all Markdown extensions:

6.1 GitHub Repository Cards

::github{repo="saicaca/fuwari"}

6.2 Mermaid Architecture Diagrams

flowchart TD
    MDX[MDX Source Entry] --> Compiler["@astrojs/mdx Compiler"]
    Compiler --> Plugins["Remark / Rehype SSOT Pipeline"]
    Plugins --> Islands["Svelte 5 Interactive Islands"]
    Islands --> Swup["Swup Client Navigation Shell"]
    Swup --> Screen["M3E Expressive Article View"]

6.3 Mathematical Expressions (LaTeX / KaTeX)

Inline equation: Mass-energy equivalence $E = mc^2$ and Gaussian integral $\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$.

Block equation:

$$ \mathcal{L}{M3E} = \sum{i=1}^{N} \left( \text{Token}_i \cdot \text{ContrastRatio} \right) + \lambda |\text{MotionElegance}| $$

7. Summary

The native integration of MDX empowers technical writers to build rich, interactive documentation while preserving Shirone's ultra-fast static performance. All components adhere to the Material 3 Expressive token design system, ensuring consistency, accessibility, and visual harmony.

Image Gallery Grid: Syntax and Complete Examples

Mon, 13 Jul 2026 00:00:00 GMT

:::grid is the blog's image gallery container directive. It arranges ordinary Markdown images in a responsive grid with a consistent aspect ratio and automatically enables lightbox viewing. Use it for article images, screenshots, portfolios, or small albums.

Images in the same gallery use the same card ratio. By default, center cropping fills every card and keeps each row tidy; clicking an image opens the complete original in a lightbox. Every gallery has its own lightbox group and does not mix with other images in the post.

This post is both feature documentation and a visual test page. View the examples at desktop, tablet, and mobile widths, then click any image to verify lightbox grouping.

Minimal Syntax

Write Markdown images directly between :::grid and the closing ::::

:::grid
![Image description](./image-1.webp)

![Image description](./image-2.webp)
:::

Each image must occupy its own paragraph, with a blank line between images. Keep only images in a gallery; write paragraphs, lists, and code blocks outside the container.

Here is the result of the minimal syntax. Without parameters, the grid uses three columns, a 16/10 ratio, and cover by default.

:::grid

:::

Parameters at a Glance

Write all parameters in braces after the opening directive: :::grid{parameter="value"}.

Parameter	Allowed values	Default	Purpose
`columns`	Integers from `1` to `6`	`3`	Number of columns per row on desktop. Invalid values fall back to `3`.
`aspect`	A positive ratio, such as `16/9`, `3/4`, or `1/1`	`16/10`	The displayed card ratio, not the original image ratio.
`fit`	`cover`, `contain`	`cover`	Image fitting mode. `cover` crops to fill; `contain` preserves the complete image and may leave empty space.

Complete example:

:::grid{columns="3" aspect="16/9" fit="cover"}
![First image](./image-1.webp "Optional caption")

![Second image](./image-2.webp "Optional caption")

![Third image](./image-3.webp "Optional caption")
:::

The following result uses the three-column landscape syntax above. Compare the card ratio, column count, and the way a title takes precedence over alt text as the caption:

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

Captions and Alt Text

An image's alt text serves both as accessible alternative text and as its default caption. When an image has an optional title, the title is used as the caption instead:

![Text used for accessibility](./image.webp "Caption shown below the image")

In the same row, captions align to the bottom of every card. A wrapping caption does not make the others float at a different height. Ratio text such as 3:4 and 16:9 can be written directly in body text, headings, and alt text without escaping.

This example demonstrates the default alt-text caption, an explicit title caption, and bottom alignment for a longer caption:

:::grid{columns="3" aspect="1/1"}

:::

Layout and Cropping

Desktop layouts use the number of columns specified by columns. Below 768px, grids use at most two columns; below 480px, they switch to one column. The card wrapper fixes the aspect ratio and clips rounded corners, while the image fills the card without the theme's default image margins.

Choose cover: the recommended default. Images are cropped from the center to fill the card, making the gallery look consistent.
Choose contain: the full original image is shown without cropping. When its ratio differs from the card, the theme background remains visible; use this for images that cannot be cropped.
To preserve the complete image without empty space, set aspect close to the original image ratio or place the image in a grid of its own.

The following examples place the same portrait images in 16/9 cards with cover and contain. The first crops them; the second preserves the full image and leaves background space.

:::grid{columns="3" aspect="16/9" fit="cover"}
![Image description](./image-1.webp "Optional caption")

![Image description](./image-2.webp "Optional caption")
:::

:::grid{columns="3" aspect="16/9" fit="contain"}
![Image description](./image-1.webp "Optional caption")

![Image description](./image-2.webp "Optional caption")
:::

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

:::grid{columns="3" aspect="16/9" fit="contain"}

:::

Default Configuration

Without attributes, the default is three columns, a 16/10 ratio, and cover cropping. These three portrait images verify default cropping and captions.

:::grid
![Image description](./image-1.webp)

![Image description](./image-2.webp)

![Image description](./image-3.webp)
:::

:::grid

:::

Three-Column Portraits: 3:4

With aspect="3/4", the three portrait images fill consistently proportioned vertical cards. If an original image has a different ratio, cover crops its edges from the center.

:::grid{columns="3" aspect="3/4"}
![Portrait image description](./portrait-1.webp)

![Portrait image description](./portrait-2.webp)

![Portrait image description](./portrait-3.webp)
:::

:::grid{columns="3" aspect="3/4"}

:::

Three-Column Landscapes: 16:9

This set demonstrates a common video-cover ratio in a three-column layout. Cropping is minimal when the landscape images are close to the card ratio.

:::grid{columns="3" aspect="16/9"}
![Landscape image description](./landscape-1.webp)

![Landscape image description](./landscape-2.webp)

![Landscape image description](./landscape-3.webp)
:::

:::grid{columns="3" aspect="16/9"}

:::

Two-Column Squares: 1:1

Two columns work well when larger preview cards are needed. The third image moves to the next row. The final row keeps its grid-track width instead of stretching images to fill the row.

:::grid{columns="2" aspect="1/1"}
![Square image description](./square-1.webp)

![Square image description](./square-2.webp)

![Square image description](./square-3.webp)
:::

:::grid{columns="2" aspect="1/1"}

:::

Four Columns with `contain`

fit="contain" does not crop the original image. When the image ratio differs from the card ratio, the theme background remains visible. This is intentional, not a layout issue. It also verifies that four-column grids and separate lightbox groups do not interfere with each other.

:::grid{columns="4" aspect="16/9" fit="contain"}
![Image description](./image-1.webp)

![Image description](./image-2.webp)

![Image description](./image-3.webp)
:::

:::grid{columns="4" aspect="16/9" fit="contain"}

:::

Single-Column Detail Image

One column is suitable when an image needs a larger reading size. It remains one column on desktop, tablet, and mobile, and the original is still available in the lightbox.

:::grid{columns="1" aspect="16/9"}
![Image description](./detail.webp)
:::

:::grid{columns="1" aspect="16/9"} :::

Sparse Five-Column Row

Five columns verify a higher supported column count. With only three images, the final row remains left-aligned instead of stretching the images.

:::grid{columns="5" aspect="1/1"}
![Thumbnail description](./thumb-1.webp)

![Thumbnail description](./thumb-2.webp)

![Thumbnail description](./thumb-3.webp)
:::

:::grid{columns="5" aspect="1/1"}

:::

Mixed Images in Six Columns

Six columns are the current maximum. Mixing landscape and portrait images verifies cover cropping, captions on narrow cards, and a dense desktop layout. For readable article content, two to four columns are usually preferable.

:::grid{columns="6" aspect="1/1"}
![Image description](./image-1.webp)

![Image description](./image-2.webp)

![Image description](./image-3.webp)

![Image description](./image-4.webp)

![Image description](./image-5.webp)

![Image description](./image-6.webp)
:::

:::grid{columns="6" aspect="1/1"}

:::

Four-Column Squares: 1:1

Four square images with the same ratio are a typical four-column layout. Desktop displays all four in one row; tablet collapses to two columns and mobile to one.

:::grid{columns="4" aspect="1/1"}
![Square image description](./square-1.webp)

![Square image description](./square-2.webp)

![Square image description](./square-3.webp)

![Square image description](./square-4.webp)
:::

:::grid{columns="4" aspect="1/1"}

:::

Six-Column Landscapes: 16:9

Six landscape columns work well for thumbnail previews, portfolios, and screenshot indexes. Even if original ratios differ slightly, cover fills every 16/9 card consistently.

:::grid{columns="6" aspect="16/9"}
![Landscape image description](./landscape-1.webp)

![Landscape image description](./landscape-2.webp)

![Landscape image description](./landscape-3.webp)

![Landscape image description](./landscape-4.webp)

![Landscape image description](./landscape-5.webp)

![Landscape image description](./landscape-6.webp)
:::

:::grid{columns="6" aspect="16/9"}

:::

Three-Column Portraits: 3:4

This group of six portrait images demonstrates a common layout for people, posters, or mobile screenshots. The images form two rows of three, with captions aligned to the bottom.

:::grid{columns="3" aspect="3/4"}
![Portrait image description](./portrait-1.webp)

![Portrait image description](./portrait-2.webp)

![Portrait image description](./portrait-3.webp)

![Portrait image description](./portrait-4.webp)

![Portrait image description](./portrait-5.webp)

![Portrait image description](./portrait-6.webp)
:::

:::grid{columns="3" aspect="3/4"}

:::

Edge-Critical Content: `cover` and Lightbox

These images contain important text or details near their edges. cover keeps the grid tidy but may crop those edges; click an image to view the uncropped original in the lightbox. Use clear captions for edge-sensitive images, or use contain below.

:::grid{columns="3" aspect="16/9" fit="cover"}
![Edge-critical content](./critical-1.webp "Open the lightbox to view the complete edge content")

![Edge-critical content](./critical-2.webp "Open the lightbox to view the complete edge content")

![Edge-critical content](./critical-3.webp "Open the lightbox to view the complete edge content")
:::

:::grid{columns="3" aspect="16/9" fit="cover"}

:::

Extreme Ratios with `contain`

For banners, long screenshots, and other extreme image ratios, contain displays the complete original. Unlike cover, it may leave theme-background space, but it never crops content.

:::grid{columns="3" aspect="16/9" fit="contain"}
![Complete screenshot description](./wide-1.webp)

![Complete screenshot description](./wide-2.webp)

![Complete screenshot description](./wide-3.webp)
:::

:::grid{columns="3" aspect="16/9" fit="contain"}

:::

Transparent Images

Transparent images reveal the card's theme background. This single-column contain example makes the transparent areas, original edges, and lightbox behavior easy to inspect.

:::grid{columns="1" aspect="16/9" fit="contain"}
![Transparent image description](./transparent.webp)
:::

:::grid{columns="1" aspect="16/9" fit="contain"} :::

Lightbox Navigation

Click any image in a grid to open the Fancybox lightbox. There you can zoom, rotate, enter fullscreen, view thumbnails, and navigate with the arrow keys. Navigation is limited to the current :::grid container: for example, clicking "16:9 test image one" only opens the other two landscape images in that section.

Ordinary Markdown images in the same post continue to be handled separately; they are not added to any grid gallery.

Checklist

Images in each grid have consistent dimensions, with captions below the cards.
Images scale slightly on hover; after clicking, they can be zoomed, rotated, and navigated with the keyboard.
Clicking "16:9 test image one" lets the lightbox browse only the other two landscape images in that section.
Below 768px, grids use at most two columns; below 480px, they use one column.
Portrait images in "Four Columns with contain" are fully visible with empty space and no cropping.
Five- and six-column grids retain their specified column count on wide screens, then collapse to two or one column according to the responsive rules.

Mermaid Diagram Gallery

Thu, 02 May 2024 00:00:00 GMT

Mermaid turns text descriptions in Markdown into diagrams. The examples below use Shirone's content workflow to demonstrate diagram types commonly used in technical articles and project notes.

Flowchart

Flowcharts describe a process, including decisions and paths that return to an earlier step.

flowchart TD
    accTitle: Article publishing workflow
    accDescr: An article moves through writing, validation, preview, and build before publication. Failed validation returns it for revision.
    Draft[Write Markdown] --> Check{Validation passed?}
    Check -->|No| Revise[Revise article]
    Revise --> Check
    Check -->|Yes| Preview[Preview locally]
    Preview --> Build[Build static page]
    Build --> Publish[Publish]

Sequence Diagram

Sequence diagrams present collaboration between participants in chronological order. This example follows a Swup navigation from request to Mermaid rendering.

sequenceDiagram
    accTitle: Diagram rendering after in-site navigation
    accDescr: A reader starts navigation, Swup replaces the article content, and the Mermaid renderer enhances diagrams on the new page.
    actor Reader
    participant Browser
    participant Swup
    participant Content as Article region
    participant Renderer as Mermaid renderer
    Reader->>Browser: Open another article
    Browser->>Swup: Start in-site navigation
    Swup->>Content: Replace page content
    Swup-->>Renderer: Emit content:replace
    Renderer->>Content: Find Mermaid containers
    Renderer-->>Browser: Insert themed SVGs

Entity Relationship Diagram

Entity relationship diagrams model structured data and the connections between authors, posts, tags, and comments.

erDiagram
    accTitle: Blog content relationships
    accDescr: Authors write posts, posts receive comments, and join records connect posts to multiple tags.
    AUTHOR ||--o{ POST : writes
    POST ||--o{ COMMENT : receives
    POST ||--o{ POST_TAG : classified_by
    TAG ||--o{ POST_TAG : groups
    AUTHOR {
        string id PK
        string display_name
    }
    POST {
        string slug PK
        string title
        datetime published_at
        string author_id FK
    }
    COMMENT {
        string id PK
        string post_slug FK
        string body
    }
    TAG {
        string id PK
        string label
    }
    POST_TAG {
        string post_slug FK
        string tag_id FK
    }

Class Diagram

Class diagrams communicate responsibilities, public methods, and dependency directions in a software design.

classDiagram
    accTitle: Markdown rendering modules
    accDescr: The content pipeline uses a Mermaid plugin to create fallback markup, which the client renderer later enhances into an SVG.
    class ContentPipeline {
        +render(markdown)
        +collectMetadata()
    }
    class MermaidPlugin {
        +transform(codeFence)
        +createFallback()
    }
    class DiagramRenderer {
        +initialize()
        +renderAll()
        +refreshTheme()
    }
    class ThemeTokens {
        +primary
        +surface
        +outline
    }
    ContentPipeline --> MermaidPlugin : uses
    DiagramRenderer --> MermaidPlugin : enhances output
    DiagramRenderer --> ThemeTokens : reads

State Diagram

State diagrams show the lifecycle of an object and the events that move it between states.

stateDiagram-v2
    accTitle: Article lifecycle
    accDescr: An article moves from draft to review and publication. It may return for revision or eventually be archived.
    [*] --> Draft
    Draft --> InReview : submit
    InReview --> Draft : request changes
    InReview --> Published : approve
    Published --> Draft : retract
    Published --> Archived : archive
    Archived --> [*]

XY Chart

XY charts combine bars and lines to compare values and trends over a shared axis.

xychart-beta
    accTitle: Six weeks of content performance
    accDescr: Bars show normalized weekly publishing volume, while the line shows normalized reading completion.
    title "Six weeks of content performance"
    x-axis "Week" [1, 2, 3, 4, 5, 6]
    y-axis "Relative score" 0 --> 100
    bar [36, 52, 44, 68, 76, 84]
    line [48, 55, 62, 61, 73, 81]

Pie Chart

Pie charts provide a compact comparison of how categories contribute to a whole.

pie showData
    accTitle: Article topics by share
    accDescr: Engineering accounts for forty percent, design systems for twenty-five percent, and the remainder is split between guides and essays.
    title Article topics by share
    "Engineering" : 40
    "Design systems" : 25
    "Guides" : 20
    "Essays" : 15

Gantt Chart

Gantt charts arrange tasks, dependencies, and milestones along a calendar timeline.

gantt
    accTitle: Theme release plan
    accDescr: The release plan moves from requirements and interaction design through component development, testing, and release.
    title Theme release plan
    dateFormat YYYY-MM-DD
    axisFormat %m/%d
    section Design
    Confirm requirements :done, brief, 2024-05-06, 2d
    Refine interactions :done, interaction, after brief, 3d
    section Implementation
    Develop components :active, components, after interaction, 6d
    Write examples :examples, after interaction, 4d
    section Validation
    Automated tests :tests, after components, 3d
    Release :milestone, release, after tests, 0d

Mind Map

Mind maps expand a central topic into related areas and supporting concepts.

mindmap
  root((Shirone))
    Content experience
      Markdown
      Search
      Diagrams
    Interface system
      M3E tokens
      Responsive layout
      Color schemes
    Engineering quality
      Astro Check
      Playwright
      Accessibility

Timeline

Timelines summarize significant events or phases without requiring exact calendar durations.

timeline
    title Mermaid support evolution
    Pipeline design : Detect Mermaid fences
                    : Preserve source fallback
    Client enhancement : Load the runtime on demand
                       : Apply theme tokens
    Reliability : Support Swup navigation
                : Verify responsive and accessible output

User Journey

User journey diagrams combine actions, participants, and experience scores across the stages of a task.

journey
    accTitle: A reader understanding a technical article
    accDescr: The reader discovers an article, combines prose with diagrams to understand it, and then explores related topics.
    title A reader understanding a technical article
    section Discover
      Browse the article list: 4: Reader
      Choose a topic: 5: Reader
    section Understand
      Read the article: 4: Reader
      Inspect a relationship diagram: 5: Reader
    section Continue
      Open a related article: 4: Reader
      Bookmark the page: 3: Reader

Git Graph

Git graphs show how work progresses on a feature branch before it merges into the main line.

gitGraph
    accTitle: Mermaid feature branch history
    accDescr: A feature branch adds the renderer and tests before merging into the main branch for release.
    commit id: "base"
    branch mermaid
    checkout mermaid
    commit id: "add-renderer"
    commit id: "add-tests"
    checkout main
    merge mermaid id: "merge-mermaid"
    commit id: "release"

Kanban Board

Kanban boards group tasks by workflow state to make current progress easy to scan.

kanban
  backlog[Backlog]
    docs[Write author documentation]
    examples[Expand example data]
  active[In progress]
    themes[Verify theme adaptation]
  complete[Complete]
    fallback[Source fallback]
    rendering[Client rendering]

Sankey Diagram

Sankey diagrams use link width to show how traffic or another quantity flows between nodes.

sankey-beta
Landing,Reading,720
Discovery,Reading,430
Reading,Explore,360
Reading,Topics,210
Reading,Outbound,140

Each example uses a standard mermaid code fence. The server preserves readable source markup, and the browser enhances it into an SVG that follows the active theme. Diagrams render again when the theme changes or when Swup navigates to this article.

Markdown Extended Features

Wed, 01 May 2024 00:00:00 GMT

GitHub Repository Cards

You can add dynamic cards that link to GitHub repositories, on page load, the repository information is pulled from the GitHub API.

::github{repo="Fabrizz/MMM-OnSpotify"}

Create a GitHub repository card with the code ::github{repo="<owner>/<repo>"}.

::github{repo="saicaca/fuwari"}

Mermaid Diagrams

Fenced mermaid blocks are rendered as diagrams and follow the active color scheme.

flowchart LR
    accTitle: Markdown rendering pipeline
    accDescr: Markdown source is transformed into semantic HTML and then enhanced as a themed SVG diagram.
    A[Markdown source] --> B[Astro content pipeline]
    B --> C[Semantic HTML]
    C --> D[Themed diagram]

Admonitions

Following types of admonitions are supported: note tip important warning caution

:::note Highlights information that users should take into account, even when skimming. :::

:::tip Optional information to help a user be more successful. :::

:::important Crucial information necessary for users to succeed. :::

:::warning Critical content demanding immediate user attention due to potential risks. :::

:::caution Negative potential consequences of an action. :::

Basic Syntax

:::note
Highlights information that users should take into account, even when skimming.
:::

:::tip
Optional information to help a user be more successful.
:::

Custom Titles

The title of the admonition can be customized.

:::note[MY CUSTOM TITLE] This is a note with a custom title. :::

:::note[MY CUSTOM TITLE]
This is a note with a custom title.
:::

GitHub Syntax

[!TIP] The GitHub syntax is also supported.

> [!NOTE]
> The GitHub syntax is also supported.

> [!TIP]
> The GitHub syntax is also supported.

Spoiler

You can add spoilers to your text. The text also supports Markdown syntax.

The content :spoiler[is hidden ayyy]!

The content :spoiler[is hidden **ayyy**]!

Image Widths and Captions

A standalone image accepts an optional w-N% width token in its alt text and a Markdown title rendered as a centered caption below the image:

![Image description w-50%](./image.webp "Visible caption")

Valid widths range from w-1% to w-100%; invalid tokens stay in the alt text. The width and the caption are independent — a title alone also produces a caption:

Expressive Code Example

Wed, 10 Apr 2024 00:00:00 GMT

Here, we'll explore how code blocks look using Expressive Code. The provided examples are based on the official documentation, which you can refer to for further details.

Expressive Code

Syntax Highlighting

Regular syntax highlighting

console.log('This code is syntax highlighted!')

Rendering ANSI escape sequences

ANSI colors:
- Regular: [31mRed[0m [32mGreen[0m [33mYellow[0m [34mBlue[0m [35mMagenta[0m [36mCyan[0m
- Bold:    [1;31mRed[0m [1;32mGreen[0m [1;33mYellow[0m [1;34mBlue[0m [1;35mMagenta[0m [1;36mCyan[0m
- Dimmed:  [2;31mRed[0m [2;32mGreen[0m [2;33mYellow[0m [2;34mBlue[0m [2;35mMagenta[0m [2;36mCyan[0m

256 colors (showing colors 160-177):
[38;5;160m160 [38;5;161m161 [38;5;162m162 [38;5;163m163 [38;5;164m164 [38;5;165m165[0m
[38;5;166m166 [38;5;167m167 [38;5;168m168 [38;5;169m169 [38;5;170m170 [38;5;171m171[0m
[38;5;172m172 [38;5;173m173 [38;5;174m174 [38;5;175m175 [38;5;176m176 [38;5;177m177[0m

Full RGB colors:
[38;2;34;139;34mForestGreen - RGB(34, 139, 34)[0m

Text formatting: [1mBold[0m [2mDimmed[0m [3mItalic[0m [4mUnderline[0m

Editor & Terminal Frames

Code editor frames

console.log('Title attribute example')

<!-- src/content/index.html -->
<div>File name comment example</div>

Terminal frames

echo "This terminal frame has no title"

Write-Output "This one has a title!"

Overriding frame types

echo "Look ma, no frame!"

# Without overriding, this would be a terminal frame
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
New-Alias tail Watch-Tail

Text & Line Markers

Marking full lines & line ranges

// Line 1 - targeted by line number
// Line 2
// Line 3
// Line 4 - targeted by line number
// Line 5
// Line 6
// Line 7 - targeted by range "7-8"
// Line 8 - targeted by range "7-8"

Selecting line marker types (mark, ins, del)

function demo() {
  console.log('this line is marked as deleted')
  // This line and the next one are marked as inserted
  console.log('this is the second inserted line')

  return 'this line uses the neutral default marker type'
}

Adding labels to line markers

// labeled-line-markers.jsx
<button
  role="button"
  {...props}
  value={value}
  className={buttonClassName}
  disabled={disabled}
  active={active}
>
  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Adding long labels on their own lines

// labeled-line-markers.jsx
<button
  role="button"
  {...props}

  value={value}
  className={buttonClassName}

  disabled={disabled}
  active={active}
>

  {children &&
    !active &&
    (typeof children === 'string' ? <span>{children}</span> : children)}
</button>

Using diff-like syntax

+this line will be marked as inserted
-this line will be marked as deleted
this is a regular line

--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+this is an actual diff file
-all contents will remain unmodified
 no whitespace will be removed either

Combining syntax highlighting with diff-like syntax

  function thisIsJavaScript() {
    // This entire block gets highlighted as JavaScript,
    // and we can still add diff markers to it!
-   console.log('Old code to be removed')
+   console.log('New and shiny code!')
  }

Marking individual text inside lines

function demo() {
  // Mark any given text inside lines
  return 'Multiple matches of the given text are supported';
}

Regular expressions

console.log('The words yes and yep will be marked.')

Escaping forward slashes

echo "Test" > /home/test.txt

Selecting inline marker types (mark, ins, del)

function demo() {
  console.log('These are inserted and deleted marker types');
  // The return statement uses the default marker type
  return true;
}

Word Wrap

Configuring word wrap per block

// Example with wrap
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with wrap=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Configuring indentation of wrapped lines

// Example with preserveIndent (enabled by default)
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

// Example with preserveIndent=false
function getLongString() {
  return 'This is a very long string that will most probably not fit into the available space unless the container is extremely wide'
}

Collapsible Sections

// All this boilerplate setup code will be collapsed
import { someBoilerplateEngine } from '@example/some-boilerplate'
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'

const engine = someBoilerplateEngine(evenMoreBoilerplate())

// This part of the code will be visible by default
engine.doSomething(1, 2, 3, calcFn)

function calcFn() {
  // You can have multiple collapsed sections
  const a = 1
  const b = 2
  const c = a + b

  // This will remain visible
  console.log(`Calculation result: ${a} + ${b} = ${c}`)
  return c
}

// All this code until the end of the block will be collapsed again
engine.closeConnection()
engine.freeMemory()
engine.shutdown({ reason: 'End of example boilerplate code' })

Line Numbers

Displaying line numbers per block

// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')

// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')

Changing the starting line number

console.log('Greetings from line 5!')
console.log('I am on line 6')

Markdown Example

Sun, 01 Oct 2023 00:00:00 GMT

An h1 header

Paragraphs are separated by a blank line.

2nd paragraph. Italic, bold, and monospace. Itemized lists look like:

this one
that one
the other one

Note that --- not considering the asterisk --- the actual text content starts at 4-columns in.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all in chapters 12--14"). Three dots ... will be converted to an ellipsis. Unicode is supported. ☺

An h2 header

Here's a numbered list:

first item
second item
third item

Note again how the actual text starts at 4 columns in (4 characters from the left side). Here's a code sample:

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

define foobar() {
    print "Welcome to flavor country!";
}

(which makes copying & pasting easier). You can optionally mark the delimited block for Pandoc to syntax highlight it:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

An h3 header

Now a nested list:

First, get these ingredients:
- carrots
- celery
- lentils
Boil some water.

Dump everything in the pot and follow this algorithm:

 find wooden spoon
 uncover pot
 stir
 cover pot
 balance wooden spoon precariously on pot handle
 wait 10 minutes
 goto first step (or shut off burner when done)

Do not bump wooden spoon or it will fall.

Notice again how text always lines up on 4-space indents (including that last line which continues item 3 above).

Here's a link to a website, to a local doc, and to a section heading in the current doc. Here's a footnote [^1].

[^1]: Footnote text goes here.

Tables can look like this:

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

A horizontal rule follows.

Here's a definition list:

apples : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Here's a "line block":

| Line one | Line too | Line tree

and images can be specified like so:

Inline math equations go in like so: $\omega = d\phi / dt$. Display math should get its own line and be put in in double-dollarsigns:

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: `foo`, *bar*, etc.

Include Video in the Posts

Tue, 01 Aug 2023 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

::youtube{id="5gIf0_xpFPI" title="YouTube video" preload="auto"}

Bilibili

::bilibili{bvid="BV1fK4y1s7Qf" title="Bilibili video" p=1 preload="auto"}

AcFun

::acfun{acid="ac48649632" title="AcFun video" preload="auto"}

ArtPlayer

::artplayer{src="https://www.pexels.com/download/video/38538991/" title="Sintel trailer" preload="auto"}

Touchfish.blog

Shirone Authoring & Usage Guide

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

🔒 Password Protection and Post Encryption Demo

Shirone Markdown Enhancements

File Trees

1. Nested List Syntax (:::file-tree)

Authoring Rules & Markers

2. Terminal Output Syntax (```file-tree)

Configuration Options

Code Trees

1. Container Syntax (:::code-tree)

Configuration & Markers

2. Local Directory Auto-Import (@[code-tree])

Audio Reader: Japanese Anime Mystery Voices

The fragments

Markdown Collapse Panels

Independent panels

Accordion mode

Author syntax

Markdown Abbreviations

In context

Define terms

Authoring boundaries

Markdown File Includes

Markdown Marker Highlights

Default emphasis

Semantic colors

Author syntax

Markdown Option Groups

Choose a package manager

Run the project

Many alternatives

Author syntax

Markdown Spoilers

Inline details

Author syntax

Markdown Admonitions

Semantic variants

Optional details

Author syntax

Content Annotations

Basic syntax

Rich content

Multiple definitions

Markdown Steps

Ordered list syntax

Options

MDX Integration and M3E Atomic Components

1. Markdown vs MDX Capability Matrix

2. Dynamic Expressions and Data Mapping

3. M3E Display and Layout Primitives (SSR-Only)

3.1 Card Containers (Card.svelte)

3.2 Accent Bars and Badges (AccentBar & Badge)

3.3 Skeleton Placeholders (Skeleton.svelte)

4. Feedback and Loading Indicators

4.1 Morphing Loading Indicator (LoadingIndicator.svelte)

4.2 Linear and Indeterminate Progress (ProgressIndicator.svelte)

5. Interactive Svelte 5 Islands

5.1 Button Matrix (Button.svelte)

5.2 Filter Chips and Segmented Buttons (Chips & SegmentedButton)

5.3 Switches, Checkboxes, and Sliders (Switch, Checkbox, Slider)

5.4 Input Controls (TextField.svelte)

6. Markdown Extension Compatibility

6.1 GitHub Repository Cards

1. Nested List Syntax (`:::file-tree`)

1. Container Syntax (`:::code-tree`)

2. Local Directory Auto-Import (`@[code-tree]`)

3.1 Card Containers (`Card.svelte`)

3.2 Accent Bars and Badges (`AccentBar` & `Badge`)

3.3 Skeleton Placeholders (`Skeleton.svelte`)

4.1 Morphing Loading Indicator (`LoadingIndicator.svelte`)

4.2 Linear and Indeterminate Progress (`ProgressIndicator.svelte`)

5.1 Button Matrix (`Button.svelte`)

5.2 Filter Chips and Segmented Buttons (`Chips` & `SegmentedButton`)

5.3 Switches, Checkboxes, and Sliders (`Switch`, `Checkbox`, `Slider`)

5.4 Input Controls (`TextField.svelte`)

Four Columns with `contain`

Edge-Critical Content: `cover` and Lightbox

Extreme Ratios with `contain`