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
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

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.

1. Markdown vs MDX Capability Matrix

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 items-center gap-4 my-4 p-4 rounded-lg bg-[var(--surface-container-high)]">

<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-3 my-6 p-5 rounded-xl border border-[var(--outline-variant)] bg-[var(--surface-container-low)]"> <div class="flex items-center gap-3">

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

</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 class="grid grid-cols-1 md:grid-cols-3 gap-4 my-6 p-6 rounded-2xl bg-[var(--surface-container)] border border-[var(--outline-variant)] text-center"> <div class="flex flex-col items-center gap-2"> <div class="h-16 flex items-center justify-center">

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

</div>

<div class="flex flex-col items-center gap-2"> <div class="h-16 flex items-center justify-center">

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

</div>

<div class="flex flex-col items-center gap-2"> <div class="h-16 flex items-center justify-center">

</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 class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">

</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.

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"}.

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

1. Images in each grid have consistent dimensions, with captions below the cards.
2. Images scale slightly on hover; after clicking, they can be zoomed, rotated, and navigated with the keyboard.
3. Clicking "16:9 test image one" lets the lightbox browse only the other two landscape images in that section.
4. Below 768px, grids use at most two columns; below 480px, they use one column.
5. Portrait images in "Four Columns with contain" are fully visible with empty space and no cropping.
6. 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.

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.

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

Syntax Highlighting

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

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

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

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

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

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')

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:

1. first item
2. second item
3. 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:

1. First, get these ingredients:

   • carrots
   • celery
   • lentils

2. Boil some water.

3. 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.

---
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

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

Bilibili

<iframe width="100%" height="468" src="//player.bilibili.com/player.html?bvid=BV1fK4y1s7Qf&p=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>