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

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.

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

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.

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.

<!-- @include: src/content/snippets/include-example.md#public-api -->

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.

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.

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.

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.

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

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.

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]

1. Clone and prepare the workspace

   Clone the repository and enter the project directory.

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

2. Install dependencies

   Use the repository's pinned package manager.

   pnpm.cmd install
   

3. Run project checks

   Confirm Astro diagnostics and TypeScript checks pass.

   npx.cmd astro check
   pnpm.cmd type-check
   

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

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.

CNB 同步到 Github

在CNB仓库里新建一个 .cnb.yml 文件，如果本身就有 .cnb.yml 的话直接复制 - stages 以下代码，内容如下：

main:
    push:
      - stages:
          - name: sync to github
            # CNB同步到Github
            image: tencentcom/git-sync
            # 创建私钥 密钥名.yml
            # 文件内容：
            # GIT_USERNAME: Github用户名
            # GIT_ACCESS_TOKEN: Github的令牌
            # 直接raw复制链接，填写到 imports: 密钥链接地址
            imports: 密钥链接地址
            settings:
              #cnb同步到github
              target_url: https://github.com/用户名/仓库名字.git
              auth_type: https
              username: ${GIT_USERNAME}
              password: ${GIT_ACCESS_TOKEN}

创建好后，顺手把CNB的令牌建好，操作如下：

CNB → 个人设置 → 访问令牌 → 生成新令牌
权限：勾选 repo-code:rw （勾选读写）
令牌：token（复制保存）

:::tip[题外话] CNB可以建立密钥仓库，将密钥存在密钥仓库里，raw出来的链接不显示内容，比存放在公共&私有仓库安全的多。 :::

Github 同步到 CNB

先在Github仓库里新建一个仓库密钥，操作如下：

仓库 → Settings → Secrets and variables → Actions → New repository secret

Name: GIT_PASSWORD
Value: {token}  ← 保留{}，粘贴CNB的令牌

然后在Github仓库 .github/workflows 文件夹下新建 sync-cnb.yml 内容如下：

name: Sync to CNB
on: [push]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Sync to CNB Repository
        uses: docker://tencentcom/git-sync
        env:
          PLUGIN_TARGET_URL: "https://cnb.cool/用户名/仓库名.git"
          PLUGIN_AUTH_TYPE: "https"
          PLUGIN_USERNAME: "cnb"
          PLUGIN_PASSWORD: ${{ secrets.GIT_PASSWORD }}
          PLUGIN_FORCE: "true"

这样基本就大功告成完成了。

来源于CNB的Git Sync Plugin ：一个用于在不同 Git 平台之间同步代码的插件。支持通过 HTTPS 或 SSH 方式同步代码到其他 Git 托管平台。

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.

同一画廊中的图片使用相同的卡片比例。默认情况下，中心裁剪会填满每张卡牌并保持每行整齐;点击图片会在灯箱中打开完整的原作。每个画廊都有自己的Lightbox组，不会和其他图片混在一起。

这篇文章既是功能文档，也是视觉测试页面。查看桌面、平板和移动端宽度的示例，然后点击任意图片验证光箱分组。

最小语法

直接在 :::grid 和 ::: 之间写Markdown图像:

:::grid
![图片描述](./image-1.webp)

![图片描述](./image-2.webp)
:::

每张图片必须占据自己的段落，图片之间必须留一行空白。只在画廊中保留图片;在容器外写段落、列表和代码块。

这是最小语法的结果。在没有参数的情况下，网格默认使用三列、16/10 的比率和覆盖率。

:::grid

:::

参数一览

在开场指令后用大括号写下所有参数: :::grid{parameter="value"}.

完整示例:

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

![Second image](./image-2.webp "可选标题")

![Third image](./image-3.webp "可选标题")
:::

以下结果使用了上面的三列横向语法。比较卡片比例、列数以及标题优先于alt文本作为标题的方式：

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

:::

标题和Alt文本

图像的alt文本既可以作为可访问的替代文本，也可以作为其默认标题。当图像具有可选标题时，标题将用作标题：

![用于辅助功能的文本](./image.webp "图片下方显示的标题")

在同一行中，标题与每张卡片的底部对齐。包装说明不会使其他人漂浮在不同的高度。比例文本，如 3:4 和 16:9 ，可以直接写在正文、标题和alt文本中，而无需转义。

此示例演示了默认的alt文本标题、显式标题标题和较长标题的底部对齐方式：

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

:::

布局和裁剪

桌面布局使用由列指定的列数。低于 768px ，网格最多使用两列；低于 480px 时，它们会切换到一列。卡片包装固定了纵横比并剪裁了圆角，而图像填充了卡片，没有主题的默认图像边距。

• 选择 cover: 推荐的默认值。图像从中心裁剪以填充卡片，使图库看起来一致。
• 选择 contain: 显示完整的原始图像而不`进行裁剪。当其比例与卡片不同时，主题背景仍然可见；将其用于无法裁剪的图像。
• 要保留完整图像而不留空白，请将 aspect 设置为接近原始图像比率，或将图像放置在自己的网格中。

以下示例将相同的肖像图像放置在带封面和内容的 16/9 卡片中。第一批作物；第二种保留了完整图像并留下背景空间。

:::grid{columns="3" aspect="16/9" fit="cover"}
![图片描述](./image-1.webp "可选标题")

![图片描述](./image-2.webp "可选标题")
:::

:::grid{columns="3" aspect="16/9" fit="contain"}
![图片描述](./image-1.webp "可选标题")

![图片描述](./image-2.webp "可选标题")
:::

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

:::

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

:::

默认配置

如果没有属性，默认值为三列、 16/10 比率和覆盖裁剪。这三幅肖像图像验证了默认裁剪和字幕。

:::grid
![图片描述](./image-1.webp)

![图片描述](./image-2.webp)

![图片描述](./image-3.webp)
:::

:::grid

:::

三柱肖像: 3:4

当 aspect = 3/4 `时，三幅肖像图像填充了比例一致的垂直卡片。如果原始图像的比率不同，cover会从中心裁剪其边缘。

:::grid{columns="3" aspect="3/4"}
![肖像图像描述](./portrait-1.webp)

![肖像图像描述](./portrait-2.webp)

![肖像图像描述](./portrait-3.webp)
:::

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

:::

三柱景观: 16:9

此集演示了三列布局中常见的视频覆盖率。当风景图像接近卡片比率时，裁剪最小。

:::grid{columns="3" aspect="16/9"}
![景观图像描述](./landscape-1.webp)

![景观图像描述](./landscape-2.webp)

![景观图像描述](./landscape-3.webp)
:::

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

:::

两个方形柱: 1:1

当需要更大的预览卡时，两列可以很好地工作。第三张图片移动到下一行。最后一行保持其网格轨迹宽度，而不是拉伸图像以填充该行。

:::grid{columns="2" aspect="1/1"}
![方形图像描述](./square-1.webp)

![方形图像描述](./square-2.webp)

![方形图像描述](./square-3.webp)
:::

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

:::

四列 contain

fit="contain" 不会裁剪原始图像。当图像比率与卡片比率不同时，主题背景仍然可见。这是故意的，不是布局问题。它还验证了四个柱网和单独的灯箱组不会相互干扰。

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

![图片描述](./image-2.webp)

![图片描述](./image-3.webp)
:::

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

:::

单柱详图图像

当图像需要更大的读取尺寸时，一列是合适的。它仍然是台式机、平板电脑和移动设备上的一列，原始版本仍然可以在灯箱中使用。

:::grid{columns="1" aspect="16/9"}
![图片描述](./detail.webp)
:::

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

稀疏五列排

当图像需要更大的读取尺寸时，一列是合适的。它仍然是台式机、平板电脑和移动设备上的一列，原始版本仍然可以在灯箱中使用。

:::grid{columns="5" aspect="1/1"}
![缩略图描述](./thumb-1.webp)

![缩略图描述](./thumb-2.webp)

![缩略图描述](./thumb-3.webp)
:::

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

:::

六列混合图像

五列验证了更高的支持列数。只有三张图像，最后一行保持左对齐，而不是拉伸图像。

:::grid{columns="6" aspect="1/1"}
![图片描述](./image-1.webp)

![图片描述](./image-2.webp)

![图片描述](./image-3.webp)

![图片描述](./image-4.webp)

![图片描述](./image-5.webp)

![图片描述](./image-6.webp)
:::

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

:::

四柱正方形: 1:1

具有相同比率的四个正方形图像是典型的四柱布局。桌面将所有四个显示在一行中；平板电脑可折叠为两列，移动为一列。

:::grid{columns="4" aspect="1/1"}
![方形图像描述](./square-1.webp)

![方形图像描述](./square-2.webp)

![方形图像描述](./square-3.webp)

![方形图像描述](./square-4.webp)
:::

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

:::

六柱景观: 16:9

六个横向列适用于缩略图预览、作品集和屏幕截图索引。即使原始比率略有不同，封面也会始终如一地填充每张 16/9 的卡片。

:::grid{columns="6" aspect="16/9"}
![景观图像描述](./landscape-1.webp)

![景观图像描述](./landscape-2.webp)

![景观图像描述](./landscape-3.webp)

![景观图像描述](./landscape-4.webp)

![景观图像描述](./landscape-5.webp)

![景观图像描述](./landscape-6.webp)
:::

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

:::

三柱肖像: 3:4

这组六张肖像图片展示了人物、海报或手机截图的常见布局。这些图像形成两行三行，标题与底部对齐。

:::grid{columns="3" aspect="3/4"}
![肖像图像描述](./portrait-1.webp)

![肖像图像描述](./portrait-2.webp)

![肖像图像描述](./portrait-3.webp)

![肖像图像描述](./portrait-4.webp)

![肖像图像描述](./portrait-5.webp)

![肖像图像描述](./portrait-6.webp)
:::

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

:::

边缘关键内容: cover and Lightbox

这些图像在边缘附近包含重要的文本或细节。盖子可以保持网格整洁，但可能会修剪这些边缘；单击图像以在lightbox中查看未剪切的原稿。对边缘敏感的图像使用清晰的标题，或使用下面的“包含”。

:::grid{columns="3" aspect="16/9" fit="cover"}
![边缘关键内容](./critical-1.webp "打开灯箱查看完整的边缘内容")

![边缘关键内容](./critical-2.webp "打开灯箱查看完整的边缘内容")

![边缘关键内容](./critical-3.webp "打开灯箱查看完整的边缘内容")
:::

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

:::

极端比率 contain

对于横幅、长截图和其他极端的图像比例，包含完整的原始显示。与封面不同，它可能会留下主题背景空间，但永远不会裁剪内容。

:::grid{columns="3" aspect="16/9" fit="contain"}
![完整的屏幕截图描述](./wide-1.webp)

![完整的屏幕截图描述](./wide-2.webp)

![完整的屏幕截图描述](./wide-3.webp)
:::

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

:::

透明图像

透明图像显示了卡片的主题背景。这个包含单个列的示例使透明区域、原始边缘和灯箱行为易于检查。

:::grid{columns="1" aspect="16/9" fit="contain"}
![透明图像描述](./transparent.webp)
:::

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

灯箱导航

单击网格中的任何图像以打开Fancybox灯箱。在那里，您可以缩放、旋转、进入全屏、查看缩略图和使用箭头键导航。导航仅限于当前的:::grid 例如:单击 “16:9测试图像一” 仅打开该部分中的另外两个横向图像。

同一帖子中的普通Markdown图片继续单独处理；它们不会添加到任何网格库中。

清单

1. 每个网格中的图像具有一致的尺寸，卡片下方有标题。
2. 图像在悬停时略微缩放；点击后，可以用键盘缩放、旋转和导航。
3. 点击 “16:9测试图像一” ，灯箱仅浏览该部分中的另外两个景观图像。
4. 低于768px，网格最多使用两列；在480px以下，他们使用一列。
5. “四列包含” 中的肖像图像完全可见，没有空白，也没有裁剪。
6. 五列和六列网格在宽屏幕上保留其指定的列数，然后根据响应规则折叠为两列或一列。

废话不多说，教程开始。

:::caution[注意！！！] 注意第二步！注意第二步！！注意第二步！！！  :::

一、 先在EO点击创建项目=>直接上传，项目名称和仓库名相同。

二、 ［！！！注意！！！］加速区域别忘记更改为：【全球可用区（不含中国大陆）】！！！『域名备案过的可无视这条』

三、 上传所需部署的源（可能不会部署成功）或直接用示例模板开始部署（项目名称别忘改！！！改成和仓库名相同。）

四、 顺便在 API Token 里创建一个Token，一会要用。

五、 返回cnb继续操作其它操作，不用管EO部署。

• 建立一个 envs.yml 文件

EDGEONE_API_TOKEN: 填写自己在EO的创建的API TOKEN

• 在建立一个 .cnb.yml 文件

# 触发器：推送到主分支
main:
  push:
      # 从私有仓库导入环境变量：
      # 参考：https://docs.cnb.cool/en/build/env.html#importing-environment-variables  
      - imports: {这里填之前创建的 envs.yml Raw的地址}
      stages:
        # 构建当前项目
        - name: Build Current Project
          image: node:24
          script: node -v && npm install && npm run build  
        # 将构建输出部署到 EdgeOne Pages
        # ./dist 目录由前一步构建步骤生成
        - name: Deploy to EdgeOne Pages
          script: npx edgeone pages deploy ./dist/ -n {这里填你的仓库名} -t $EDGEONE_API_TOKEN

:::tip[题外话] 自定义域名如果是托管在CF的话是要关闭小黄云的，不然无法解析。 :::

WIN+R 输入 regedit 进入注册表编辑器。

按照以下顺序依次点击:

计算机\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsUpdate\UX\Settings

右边空白处，右击新建一个 DWORD值

重命名为:

FlightSettingsMaxPauseDays

双击 FlightSettingsMaxPauseDays ，基数选择十进制。

左侧填写为你想暂停的整数天数，例如36500天，点确定。

然后 WIN+i 打开系统设置，在Windows更新里就可以选择设置好的最长周期时长。

如果想更新的话，点击继续更新就可以了。

故事背景

战国时期，有一个心地善良的书生叫东郭先生。

故事经过

• 遇狼求救：有一天，东郭先生骑着毛驴外出讲学，走到一个十字路口时，看见一只狼慌慌张张地跑来，后面紧跟着一位手持猎枪的猎人。狼跑到东郭先生面前，跪下来哀求道：“先生，救救我吧！后面有猎人要杀我，您行行好，把我藏起来吧，我日后一定会报答您的！”东郭先生看着狼那可怜的样子，心生怜悯，便把书从袋子里拿出来，让狼钻进袋子里，然后把袋子藏在了书袋里 。 • 猎人离去：猎人追过来，问东郭先生有没有看见一只狼。东郭先生摇摇头说：“没有看见。”猎人四处搜寻了一番，没有发现狼的踪迹，只好离开了。 • 狼欲吃东郭先生：猎人走后，狼从袋子里钻了出来，可它并没有感激东郭先生救命之恩的意思，反而露出了凶狠的本性，恶狠狠地说：“先生，我现在饿了，你就成为我的一顿美餐吧！”说完，就向东郭先生扑了过去。

故事转折

• 老杏和老牛诉说：东郭先生惊恐万分，苦苦哀求狼放过自己，并和狼讲道理，但狼根本不听。就在东郭先生绝望的时候，路边的一棵老杏树开口说话了，它给东郭先生讲述了自己一生奉献果实却最终被砍伐的遭遇；接着，一头老牛也说了自己辛苦耕地到老却被宰杀的故事。它们都借此提醒东郭先生，不能对狼抱有幻想。 • 智斗恶狼：听了老杏和老牛的话，东郭先生意识到不能再心软，于是他和狼一起到前面的一个老人那里去评理。老人了解情况后，设计让狼重新钻进袋子，然后狠狠地教训了它一顿，并最终杀死了这只忘恩负义的狼。

故事寓意

这个故事讽刺了那些像狼一样忘恩负义、恩将仇报的人，同时也赞扬了东郭先生最初的善良，但也提醒人们在善良的同时也要保持一定的警惕，学会保护自己 。

一个 Markdown 示例展示了如何编写 Markdown 文件。本文件整合了核心语法和扩展（GMF）。

• 块级元素
  • 段落和换行
  • 标题
  • 引用
  • 列表
  • 代码块
  • 水平线
  • 表格
• 行内元素
  • 链接
  • 强调
  • 代码
  • 图片
  • 删除线
• 其他
  • 自动链接
  • 反斜杠转义
• 行内 HTML

Block Elements

Paragraphs and Line Breaks

Paragraphs

HTML Tag: <p>

One or more blank lines. (A blank line is a line containing nothing but spaces or tabs is considered blank.)

Code:

This will be
inline.

This is second paragraph.

Preview:

This will be inline.

This is second paragraph.

Line Breaks

HTML Tag: <br />

End a line with two or more spaces.

Code:

This will be not
inline.

Preview:

This will be not
inline.

Headers

Markdown supports two styles of headers, Setext and atx.

Setext

HTML Tags: <h1>, <h2>

"Underlined" using equal signs (=) as <h1> and dashes (-) as <h2> in any number.

Code:

This is an H1
=============
This is an H2
-------------

Preview:

This is an H1

This is an H2

atx

HTML Tags: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>

Uses 1-6 hash characters (#) at the start of the line, corresponding to <h1> - <h6>.

Code:

# This is an H1
## This is an H2
###### This is an H6

Preview:

This is an H1

This is an H2

This is an H6

Optionally, you may "close" atx-style headers. The closing hashes don't need to match the number of hashes used to open the header.

Code:

# This is an H1 #
## This is an H2 ##
### This is an H3 ######

Preview:

This is an H1

This is an H2

This is an H3

Blockquotes

HTML Tag: <blockquote>

Markdown uses email-style > characters for blockquoting. It looks best if you hard wrap the text and put a > before every line.

Code:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

Preview:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown allows you to be lazy and only put the > before the first line of a hard-wrapped paragraph.

Code:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

Preview:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of >.

Code:

> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.

Preview:

This is the first level of quoting.

This is nested blockquote.

Back to the first level.

Blockquotes can contain other Markdown elements, including headers, lists, and code blocks.

Code:

> ## This is a header.
>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

Preview:

This is a header.

1. This is the first list item.
2. This is the second list item.

Here's some example code:

return shell_exec("echo $input | $markdown_script");

Lists

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered

HTML Tag: <ul>

Unordered lists use asterisks (*), pluses (+), and hyphens (-).

Code:

*   Red
*   Green
*   Blue

Preview:

• Red
• Green
• Blue

is equivalent to:

Code:

+   Red
+   Green
+   Blue

and:

Code:

-   Red
-   Green
-   Blue

Ordered

HTML Tag: <ol>

Ordered lists use numbers followed by periods:

Code:

1.  Bird
2.  McHale
3.  Parish

Preview:

1. Bird
2. McHale
3. Parish

It's possible to trigger an ordered list by accident, by writing something like this:

Code:

1986. What a great season.

Preview:

1. What a great season.

You can backslash-escape (\) the period:

Code:

1986\. What a great season.

Preview:

1986. What a great season.

Indented

Blockquote

To put a blockquote within a list item, the blockquote's > delimiters need to be indented:

Code:

*   A list item with a blockquote:

    > This is a blockquote
    > inside a list item.

Preview:

• A list item with a blockquote:

  This is a blockquote inside a list item.

Code Block

To put a code block within a list item, the code block needs to be indented twice — 8 spaces or two tabs:

Code:

*   A list item with a code block:

        <code goes here>

Preview:

• A list item with a code block:

  <code goes here>
  

Nested List

Code:

* A
  * A1
  * A2
* B
* C

Preview:

• A
  • A1
  • A2
• B
• C

Code Blocks

HTML Tag: <pre>

Indent every line of the block by at least 4 spaces or 1 tab.

Code:

This is a normal paragraph:

    This is a code block.

Preview:

This is a normal paragraph:

This is a code block.

A code block continues until it reaches a line that is not indented (or the end of the article).

Within a code block, ampersands (&) and angle brackets (< and >) are automatically converted into HTML entities.

Code:

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

Preview:

<div class="footer">
    &copy; 2004 Foo Corporation
</div>

Following sections Fenced Code Blocks and Syntax Highlighting are extensions, you can use the other way to write the code block.

Fenced Code Blocks

Just wrap your code in ``` (as shown below) and you won't need to indent it by four spaces.

Code:

Here's an example:

```
function test() {
  console.log("notice the blank line before this function?");
}
```

Preview:

Here's an example:

function test() {
  console.log("notice the blank line before this function?");
}

Syntax Highlighting

In your fenced block, add an optional language identifier and we'll run it through syntax highlighting (Support Languages).

Code:

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

Preview:

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

Horizontal Rules

HTML Tag: <hr /> Places three or more hyphens (-), asterisks (*), or underscores (_) on a line by themselves. You may use spaces between the hyphens or asterisks.

Code:

* * *
***
*****
- - -
---------------------------------------
___

Preview:

Table

HTML Tag: <table>

It's an extension.

Separates column by pipe (|) and header by dashes (-), and uses colon (:) for alignment.

The outer pipes (|) and alignment are optional. There are 3 delimiters each cell at least for separating header.

Code:

| Left | Center | Right |
|:-----|:------:|------:|
|aaa   |bbb     |ccc    |
|ddd   |eee     |fff    |

 A | B
---|---
123|456


A |B
--|--
12|45

Preview:

Span Elements

Links

HTML Tag: <a>

Markdown supports two style of links: inline and reference.

Inline

Inline link format like this: [Link Text](URL "Title")

Title is optional.

Code:

This is [an example](http://example.com/ "Title") inline link.

[This link](http://example.net/) has no title attribute.

Preview:

This is an example inline link.

This link has no title attribute.

If you're referring to a local resource on the same server, you can use relative paths:

Code:

See my [About](/about/) page for details.

Preview:

See my About page for details.

Reference

You could predefine link references. Format like this: [id]: URL "Title"

Title is also optional. And the you refer the link, format like this: [Link Text][id]

Code:

[id]: http://example.com/  "Optional Title Here"
This is [an example][id] reference-style link.

Preview:

This is an example reference-style link.

That is:

• Square brackets containing the link identifier (not case sensitive, optionally indented from the left margin using up to three spaces);
• followed by a colon;
• followed by one or more spaces (or tabs);
• followed by the URL for the link;
• The link URL may, optionally, be surrounded by angle brackets.
• optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses.

The following three link definitions are equivalent:

Code:

[foo]: http://example.com/  "Optional Title Here"
[foo]: http://example.com/  'Optional Title Here'
[foo]: http://example.com/  (Optional Title Here)
[foo]: <http://example.com/>  "Optional Title Here"

Uses an empty set of square brackets, the link text itself is used as the name.

Code:

[Google]: http://google.com/
[Google][]

Preview:

Google

Emphasis

HTML Tags: <em>, <strong>

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. One delimiter will be <em>; *double delimiters will be <strong>.

Code:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

Preview:

single asterisks

single underscores

double asterisks

double underscores

But if you surround an * or _ with spaces, it'll be treated as a literal asterisk or underscore.

You can backslash escape it:

Code:

\*this text is surrounded by literal asterisks\*

Preview:

*this text is surrounded by literal asterisks*

Code

HTML Tag: <code>

Wraps it with backtick quotes (`).

Code:

Use the `printf()` function.

Preview:

Use the printf() function.

To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:

Code:

``There is a literal backtick (`) here.``

Preview:

There is a literal backtick (`) here.

The backtick delimiters surrounding a code span may include spaces — one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:

Code:

A single backtick in a code span: `` ` ``

A backtick-delimited string in a code span: `` `foo` ``

Preview:

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

Images

HTML Tag: <img />

Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: inline and reference.

Inline

Inline image syntax looks like this: ![Alt text](URL "Title")

Title is optional.

Code:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

Preview:

That is:

• An exclamation mark: !;
• followed by a set of square brackets, containing the alt attribute text for the image;
• followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in double or single quotes.

Reference

Reference-style image syntax looks like this: ![Alt text][id]

Code:

[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
![Alt text][img id]

Preview:

Strikethrough

HTML Tag: <del>

It's an extension.

GFM adds syntax to strikethrough text.

Code:

~~Mistaken text.~~

Preview:

Mistaken text.

Miscellaneous

Automatic Links

Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets.

Code:

<http://example.com/>

<address@example.com>

Preview:

http://example.com/

address@example.com

GFM will autolink standard URLs.

Code:

https://github.com/emn178/markdown

Preview:

https://github.com/emn178/markdown

Backslash Escapes

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown's formatting syntax.

Code:

\*literal asterisks\*

Preview:

*literal asterisks*

Markdown provides backslash escapes for the following characters:

Code:

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

Inline HTML

For any markup that is not covered by Markdown's syntax, you simply use HTML itself. There's no need to preface it or delimit it to indicate that you're switching from Markdown to HTML; you just use the tags.

Code:

This is a regular paragraph.

<table>
    <tr>
        <td>Foo</td>
    </tr>
</table>

This is another regular paragraph.

Preview:

This is a regular paragraph.

<table> <tr> <td>Foo</td> </tr> </table>

This is another regular paragraph.

Note that Markdown formatting syntax is not processed within block-level HTML tags.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

Code:

<span>**Work**</span>

<div>
    **No Work**
</div>

Preview:

<span>Work</span>

<div> No Work </div>

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:

您可以添加动态卡片，链接到 GitHub 仓库，页面加载时，仓库信息从 GitHub API 中获取。

::github{repo="matsuzaka-yuki/Mizuki"}

创建一个带有代码 ::github{repo="<owner>/<repo>"} 的 GitHub 仓库卡片。

::github{repo="matsuzaka-yuki/Mizuki"}

警告

支持的警告类型如下: note tip important warning caution

:::note 突出显示用户在快速浏览时应注意的信息。 :::

:::tip 可选信息，以帮助用户更成功。 :::

:::important 关键信息，用户成功所需的必要信息。 :::

:::warning 需要立即处理的关键内容，因潜在风险而需立即引起用户注意。 :::

:::caution 行动的负面潜在后果。 :::

基本语法

:::note
突出显示用户即使在浏览时也应考虑的信息。
:::

:::tip
可选信息，以帮助用户取得更大的成功。
:::

自定义标题

警告标题可以自定义。

:::note[我的自定义标题] 这是一个有自定义标题的便签 。 :::

:::note[MY CUSTOM TITLE]
这是一条带有自定义标题的笔记。
:::

GitHub 语法

[!TIP] GitHub 语法 也得到支持

> [!NOTE]
> GitHub 语法也被支持。

> [!TIP]
> GitHub 语法也被支持。

Spoiler

您可以在文本中添加 Spoiler。该文本还支持 Markdown 语法。

The content :spoiler[is hidden ayyy]!

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

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

富有表现力的代码

语法高亮

语法高亮

常规语法突出显示

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

渲染 ANSI 转义序列

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

编辑器和终端框架

编辑器和终端帧

代码编辑器框架

console.log('Title attribute example')

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

终端框架

echo "This terminal frame has no title"

Write-Output "This one has a title!"

覆盖框架类型

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

文本与行标记

文本与行标记

标记整行与行范围

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

选择行标记类型（标记、插入、删除）

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

为行标记添加标签

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

将长标签单独放在一行

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

使用类似 diff 的语法

+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

结合语法高亮与类似差异的语法

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

在行内标记单个文本

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

正则表达式

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

转义前导斜杠

echo "Test" > /home/test.txt

选择内联标记类型（mark、ins、del）

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

自动换行

自动换行

为每个区块配置自动换行

// 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'
}

配置包裹行的缩进

// 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'
}

可折叠部分

可折叠部分

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

行号

行号

每个代码块显示行号

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

更改起始行号

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

文章的前置内容

---
title: 我的第一篇博客文章
published: 2023-09-09
description: 这是我新 Astro 博客的第一篇文章。
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
---

放置文章文件的位置

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录，以更好地组织您的文章和资源。

src/content/posts/
├── post-1.md
└── post-2/
    ├── cover.webp
    └── index.md

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.

本文演示了如何在 Markdown 文档中使用 Mermaid 创建各种复杂的图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例

流程图非常适合表示流程或算法步骤。

graph TD
    A[Start] --> B{Condition Check}
    B -->|Yes| C[Process Step 1]
    B -->|No| D[Process Step 2]
    C --> E[Subprocess]
    D --> E
    subgraph E [Subprocess Details]
        E1[Substep 1] --> E2[Substep 2]
        E2 --> E3[Substep 3]
    end
    E --> F{Another Decision}
    F -->|Option 1| G[Result 1]
    F -->|Option 2| H[Result 2]
    F -->|Option 3| I[Result 3]
    G --> J[End]
    H --> J
    I --> J

时序图示例

序列图显示对象随时间的交互。

sequenceDiagram
    participant User
    participant WebApp
    participant Server
    participant Database

    User->>WebApp: Submit Login Request
    WebApp->>Server: Send Auth Request
    Server->>Database: Query User Credentials
    Database-->>Server: Return User Data
    Server-->>WebApp: Return Auth Result
    
    alt Auth Successful
        WebApp->>User: Show Welcome Page
        WebApp->>Server: Request User Data
        Server->>Database: Get User Preferences
        Database-->>Server: Return Preferences
        Server-->>WebApp: Return User Data
        WebApp->>User: Load Personalized Interface
    else Auth Failed
        WebApp->>User: Show Error Message
        WebApp->>User: Prompt Re-entry
    end

甘特图示例

甘特图非常适合显示项目进度和时间表。

gantt
    title Website Development Project Timeline
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d
    
    section Design Phase
    Requirements Analysis      :a1, 2023-10-01, 7d
    UI Design                 :a2, after a1, 10d
    Prototype Creation        :a3, after a2, 5d
    
    section Development Phase
    Frontend Development      :b1, 2023-10-20, 15d
    Backend Development       :b2, after a2, 18d
    Database Design           :b3, after a1, 12d
    
    section Testing Phase
    Unit Testing              :c1, after b1, 8d
    Integration Testing       :c2, after b2, 10d
    User Acceptance Testing   :c3, after c2, 7d
    
    section Deployment
    Production Deployment     :d1, after c3, 3d
    Launch                    :milestone, after d1, 0d

类图示例

类图显示系统的静态结构，包括类、属性、方法及它们的关系。

classDiagram
    class User {
        +String username
        +String password
        +String email
        +Boolean active
        +login()
        +logout()
        +updateProfile()
    }
    
    class Article {
        +String title
        +String content
        +Date publishDate
        +Boolean published
        +publish()
        +edit()
        +delete()
    }
    
    class Comment {
        +String content
        +Date commentDate
        +addComment()
        +deleteComment()
    }
    
    class Category {
        +String name
        +String description
        +addArticle()
        +removeArticle()
    }
    
    User "1" -- "*" Article : writes
    User "1" -- "*" Comment : posts
    Article "1" -- "*" Comment : has
    Article "1" -- "*" Category : belongs to

状态图示例

状态图显示了对象在其生命周期中经历的状态序列。

stateDiagram-v2
    [*] --> Draft
    
    Draft --> UnderReview : submit
    UnderReview --> Draft : reject
    UnderReview --> Approved : approve
    Approved --> Published : publish
    Published --> Archived : archive
    Published --> Draft : retract
    
    state Published {
        [*] --> Active
        Active --> Hidden : temporarily hide
        Hidden --> Active : restore
        Active --> [*]
        Hidden --> [*]
    }
    
    Archived --> [*]

饼图示例

饼图非常适合显示比例和百分比数据。

pie title Website Traffic Sources Analysis
    "Search Engines" : 45.6
    "Direct Access" : 30.1
    "Social Media" : 15.3
    "Referral Links" : 6.4
    "Other Sources" : 2.6

结论

Mermaid是一个强大的工具，用于在标记文档中创建各种类型的图表。本文演示了如何使用流程图、序列图、甘特图、类图、状态图和饼图。这些图可以帮助您更清楚地表达复杂的概念、流程和数据结构。

要使用Mermaid，只需在代码块中指定Mermaid语言，并使用简洁的文本语法描述图表。Mermaid会自动将这些描述转换成美丽的视觉图表。 尝试在你的下一篇技术博客文章或项目文档中使用Mermaid图表-它们将使你的内容更专业，更容易理解！

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

---
title: 在帖子中包含视频
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>