Title bar

export const greet = (name: string) => `Hello, ${name}!`;

Line numbers

def fib(n):
    if n < 2:
        return n
    return fib(n - 1) + fib(n - 2)

Highlighted lines

fn main() {
    let x = compute();
    println!("{x}");
    if x > 10 {
        warn();
        recover();
    }
}

Title + line numbers + highlights combined

import { highlightToHast } from '@/lib/shiki';
import { toHtml } from 'hast-util-to-html';
import CodeBlockToolbar from './CodeBlockToolbar';

export default async function CodeBlock({ language, children, title }) {
  const hast = await highlightToHast(children, language, { title });
  const html = toHtml(hast);
  return (
    <div className="cb-root">
      {title && <span className="cb-title">{title}</span>}
      <CodeBlockToolbar code={children} />
      <div dangerouslySetInnerHTML={{ __html: html }} />
    </div>
  );
}

Diff with red/green backgrounds

-export const VERSION = "1.0";
+export const VERSION = "2.0";
 export const NAME = "amytis";
-export const STAGE = "alpha";
+export const STAGE = "beta";

Word-wrap toggle

Long lines in code blocks overflow horizontally by default — the block grows a scrollbar at the bottom. Click the Wrap button in any block's header to soft-wrap long lines onto multiple visual lines instead; click again to restore horizontal scrolling.

curl -X POST "https://api.example.com/v1/items?fields=id,name,description,createdAt,updatedAt&sort=createdAt:desc&limit=100&offset=0&filter[status]=active&filter[category]=blog&include=author,tags" -H "Authorization: Bearer YOUR_API_TOKEN_HERE" -H "Content-Type: application/json" -d '{"name":"example","description":"a sufficiently long single line to demonstrate the wrap toggle"}'

Try the Wrap button in the header above ↑ to see the long line collapse into multiple soft-wrapped lines.

Mermaid still works (regression check)

graph LR
  A[Markdown] --> B[remark]
  B --> C[rehype + Shiki]
  C --> D[Static HTML]

Tabbed code groups

Group adjacent fences into a single tabbed widget by wrapping them in a :::code-group container directive. Tab names come from the [label] token after the language. The mechanism is pure CSS (radio inputs + sibling selectors) — zero JavaScript, zero hydration cost.

When a tab label matches a known package manager, language, or common config filename, an icon appears automatically before the label. Resolution is handled by resolveCodeGroupIcon in src/lib/code-group-icons.ts.

:::code-group

npm install amytis

yarn add amytis

pnpm add amytis

bun add amytis

:::

Filename labels also resolve — e.g. tsconfig.json, vite.config.ts, or Dockerfile:

:::code-group

{ "compilerOptions": { "target": "es2022", "module": "esnext" } }

import { defineConfig } from 'vite';
export default defineConfig({ server: { port: 5173 } });

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build

:::

Tabs work across languages too — handy for showing the same algorithm in multiple implementations:

:::code-group

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

def greet(name: str) -> str:
    return f"Hello, {name}!"

fn greet(name: &str) -> String {
    format!("Hello, {name}!")
}

:::

Notation comments

Annotate individual lines with // [!code …] comments. Six markers are supported — focus, diff, highlight, error, warning — using the language's native comment style (// in C-family, # in Python, -- in SQL, etc.):

function login(user: string) {            // [!code focus]
  const token = oldApi.auth(user)         // [!code --]
  const token = newApi.auth({ user })     // [!code ++]
  validate(token)                         // [!code highlight]
  throwIfExpired(token)                   // [!code error]
  if (!token.refreshable) warn()          // [!code warning]
  return token
}

// [!code focus] dims the rest of the block so the focused subset stands out; hover the block to reveal the dimmed lines. // [!code error] / [!code warning] tint the line with a colored left-border (red / amber). [!code ++] / [!code --] color individual lines without needing a diff-language fence.

Notation comments work in any language — Python:

def fib(n):
    if n < 2: return n          # [!code focus]
    return fib(n-1) + fib(n-2)

GitHub-flavored alerts

Add a [!TYPE] marker on the first line of a blockquote to render it as a GitHub-style callout. Five types are supported, each with its own color, icon, and label:

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

rST equivalents (.. note:: / .. tip:: / .. important:: / .. warning:: / .. caution::) render with matching colors via docutils' admonition directives — same visual treatment across both pipelines.

Explicit plaintext

This block opts out of syntax highlighting entirely. Use `plaintext` (or its
aliases `text`, `txt`, `plain`) for prose-like blocks where token coloring
would be noisy or misleading. Unknown language names will fail the build.

The Client-Side Toggle Approach

The simplest approach stores language preference in client state and resolves translations after hydration:

// Language stored in context, resolved on the client
const { t, language } = useLanguage();
const label = t('about'); // "About" or "关于"

For page content that has locale variants, all versions are server-rendered into the HTML and a thin client wrapper toggles visibility:

// LocaleSwitch: shows/hides [data-locale] divs via useEffect
<LocaleSwitch>
  <div data-locale="en"><MarkdownRenderer content={enContent} /></div>
  <div data-locale="zh" style={{ display: 'none' }}><MarkdownRenderer content={zhContent} /></div>
</LocaleSwitch>

This works and is zero-config — no routing changes needed. But it has real limitations.

SEO Problems

• Crawlers always see the default language. Googlebot doesn't execute localStorage reads, so it always indexes the default locale's content.
• display:none content is risky. Google may partially index hidden locale variants, or ignore them entirely.
• No hreflang signals. Search engines can't discover alternate language versions of a page.
• <html lang> not updated. Accessibility and search engine tooling rely on this attribute.

URL-Based Locale Routing

The proper solution gives each language variant its own URL:

/about        → English (default, no prefix)
/zh/about     → Chinese

With Next.js App Router, this means moving all routes under an app/[locale]/ segment and using generateStaticParams to pre-render each route for each locale at build time.

Since Amytis uses output: "export", this is pure Static Site Generation — the HTML is fully pre-built per locale. Crawlers get complete HTML with no JavaScript required, and each locale is independently indexable.

The Default Locale Prefix Problem

Most sites want the default locale to have a clean URL (/about, not /en/about). With a runtime server, middleware handles this transparently. With static export, you need your hosting layer to do the rewrite.

Netlify / Cloudflare Pages

Drop a _redirects file in public/:

/en              /            301
/en/*            /:splat      301
/*               /en/:splat   200

The 200 status is a silent rewrite — the user sees /about in the URL bar, but the server serves out/en/about/index.html.

Vercel

{
  "redirects": [
    { "source": "/en/:path*", "destination": "/:path*", "permanent": true }
  ],
  "rewrites": [
    { "source": "/((?!zh/).*)", "destination": "/en/$1" }
  ]
}

Nginx

location ~ ^/en(/.*)?$ { return 301 ${1:-/}; }
location /zh/ { try_files $uri $uri/index.html =404; }
location / { try_files /en$uri /en$uri/index.html =404; }

GitHub Pages

GitHub Pages has no native rewrite support. The simplest workaround is a root index.html with a JS language detector:

<script>
  const lang = navigator.language.startsWith('zh') ? 'zh' : 'en';
  window.location.replace('/' + lang + '/');
</script>

Or just accept the /en/ prefix for all locales.

Content Strategy

URL-based routing changes more than just URLs — it changes how you think about content.

For a personal digital garden, most content is written in one language and won't be fully translated. The realistic scope is:

The .{locale}.mdx convention — already used for static pages in Amytis — extends naturally to posts and series:

content/posts/my-post.mdx           # default locale
content/posts/my-post.zh.mdx        # optional Chinese translation
content/series/my-series/index.zh.mdx

At build time, generateStaticParams generates /en/my-post and /zh/my-post. If the .zh.mdx file doesn't exist, the Chinese URL falls back to the English content with a small "not available in this language" banner.

Trade-offs at a Glance

Conclusion

For a personal blog where SEO in a second language isn't critical, the client-side toggle approach is pragmatic and gets the job done. UI strings translate, page content can optionally have locale variants, and there's no hosting complexity.

For a project where bilingual SEO matters — where you genuinely want Chinese content indexed under Chinese URLs — URL-based routing is the right architecture. The CDN configuration is a one-time setup, and the .{locale}.mdx convention for content is already half-implemented.

The good news: both approaches share the same content file convention. Migrating from client-side toggle to URL-based routing is a routing and build change, not a content restructure.

YouTube Video

Responsive 16:9 YouTube embed using a padded wrapper:

"Me at the zoo" — the very first video uploaded to YouTube (April 23, 2005).

Vimeo Video

Vimeo also supports responsive 16:9 embedding:

Big Buck Bunny (2008) — open-source animated short by the Blender Foundation.

Podcast Embeds

Spotify Podcast

Spotify provides a fixed-height iframe embed for individual episodes:

You can also embed the full show player at a taller height (352px) to show the episode list:

Apple Podcasts

Apple Podcasts uses a similar iframe embed pattern:

Livestream Embeds

YouTube Live

A YouTube Live channel or active live video can be embedded exactly like a regular video. Use the channel's live URL (/live) or a live event ID:

<!-- Replace CHANNEL_ID with the YouTube channel ID -->
<iframe
  src="https://www.youtube.com/embed/live_stream?channel=CHANNEL_ID"
  ...
></iframe>

Below is NASA's public live stream:

Twitch Stream

Twitch requires your site's hostname in the parent query parameter (so the embed works in production):

<!-- Replace CHANNEL_NAME with a Twitch channel, and your-domain.com with your domain -->
<iframe
  src="https://player.twitch.tv/?channel=CHANNEL_NAME&parent=your-domain.com"
  height="378"
  width="100%"
  allow="fullscreen"
  title="Twitch Stream"
></iframe>

Twitch also supports embedding past broadcasts (VODs) and clips:

<!-- VOD -->
<iframe src="https://player.twitch.tv/?video=VOD_ID&parent=your-domain.com" ...></iframe>
<!-- Clip -->
<iframe src="https://clips.twitch.tv/embed?clip=CLIP_SLUG&parent=your-domain.com" ...></iframe>

HTML5 Native Media

Native <video> and <audio> elements work without any third-party embeds.

HTML5 Video

<video controls style="width: 100%; border-radius: 12px; margin: 1rem 0; background: #000;" poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg"

Elephants Dream (2006) — first open-source animated film by the Blender Foundation.

Attributes you can use:

HTML5 Audio

<audio controls style="width: 100%; margin: 1rem 0;"

SoundHelix royalty-free sample track.

Multiple formats improve cross-browser support:

<audio controls>
  <source src="https://amytis.vercel.app/posts/multimedia-showcase/audio.ogg" type="audio/ogg" />
  <source src="https://amytis.vercel.app/posts/multimedia-showcase/audio.mp3" type="audio/mpeg" />
  Your browser does not support the HTML5 audio element.
</audio>

Audio Platforms

SoundCloud

SoundCloud exposes an iframe embed from any track's "Share → Embed" menu:

The full visual player (300px height) shows the waveform:

<iframe
  width="100%"
  height="300"
  src="https://w.soundcloud.com/player/?url=TRACK_URL&visual=true"
  ...
></iframe>

Bandcamp

Bandcamp provides both album and track embed codes:

<!-- Album embed -->
<iframe
  style="border: 0; width: 100%; height: 120px;"
  src="https://bandcamp.com/EmbeddedPlayer/album=ALBUM_ID/size=large/bgcol=ffffff/linkcol=0687f5/"
  seamless
></iframe>

Embed Best Practices

When embedding third-party media, keep these in mind:

• Responsive sizing: Wrap iframes in a padding-bottom: 56.25%; position: relative container to maintain 16:9 ratio.
• loading="lazy": Add this to below-the-fold embeds to defer loading and improve page speed.
• title attribute: Always provide a descriptive title for screen reader accessibility.
• Privacy-enhanced mode: YouTube supports youtube-nocookie.com to reduce tracking when embeds don't auto-play.
• allow over allowfullscreen: Use allow="fullscreen" instead of the deprecated allowfullscreen boolean attribute. Note that bare allow="fullscreen" restricts fullscreen to the iframe's own origin (more secure), whereas the legacy allowfullscreen was equivalent to allow="fullscreen *" (any origin). For third-party embeds like YouTube or Vimeo, allow="fullscreen" is the correct and preferred form. When both attributes are present the browser warns that allow takes precedence.
• sandbox attribute: Use for untrusted embeds to restrict what the iframe can do.
• Twitch parent parameter: Twitch requires your site's hostname in parent for embeds to work outside localhost.

<!-- YouTube privacy-enhanced embed -->
<iframe
  src="https://www.youtube-nocookie.com/embed/VIDEO_ID?rel=0"
  ...
></iframe>

For a comprehensive showcase covering 11+ languages, see the standalone Syntax Highlighting Showcase post.

TypeScript

interface Post {
  title: string;
  date: string;
  featured: boolean;
}

function getFeatured(posts: Post[]): Post[] {
  return posts.filter(p => p.featured);
}

Python

from pathlib import Path
from dataclasses import dataclass

@dataclass
class Post:
    title: str
    slug: str
    featured: bool = False

    @property
    def url(self) -> str:
        return f"/posts/{self.slug}"

def load_posts(directory: Path) -> list[Post]:
    return [
        Post(title=f.stem.replace("-", " ").title(), slug=f.stem)
        for f in directory.glob("*.md")
    ]

Rust

use std::fs;

struct Post {
    title: String,
    slug: String,
    featured: bool,
}

fn load_posts(dir: &str) -> Vec<Post> {
    fs::read_dir(dir)
        .expect("Failed to read directory")
        .filter_map(|entry| {
            let path = entry.ok()?.path();
            let slug = path.file_stem()?.to_str()?.to_string();
            Some(Post {
                title: slug.replace('-', " "),
                slug,
                featured: false,
            })
        })
        .collect()
}

Go

package blog

import (
	"os"
	"path/filepath"
	"strings"
)

type Post struct {
	Title    string
	Slug     string
	Featured bool
}

func LoadPosts(dir string) ([]Post, error) {
	entries, err := os.ReadDir(dir)
	if err != nil {
		return nil, err
	}

	var posts []Post
	for _, e := range entries {
		if filepath.Ext(e.Name()) == ".md" {
			slug := strings.TrimSuffix(e.Name(), ".md")
			posts = append(posts, Post{
				Title: strings.ReplaceAll(slug, "-", " "),
				Slug:  slug,
			})
		}
	}
	return posts, nil
}

CSS / Tailwind

.card-base {
  @apply relative overflow-hidden rounded-2xl border border-muted/20 bg-muted/5 p-8 transition-all hover:border-accent/30;
}

Inline Math

The Pythagorean theorem is $a^2 + b^2 = c^2$. We can also express complex numbers like $e^{i\pi} + 1 = 0$.

Block Math

For more complex equations, use block math:

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

Or Maxwell's equations:

$$ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \ \nabla \cdot \mathbf{B} &= 0 \ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \ \nabla \times \mathbf{B} &= \mu_0\left(\mathbf{J} + \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t}\right) \end{aligned} $$

Mermaid Diagrams

You can write diagrams directly in your markdown:

graph TD
    A[Idea] --> B{Is it good?}
    B -- Yes --> C[Plant it]
    B -- No --> D[Discard]
    C --> E[Grow]
    E --> F[Evergreen]

Images

Standard markdown images are supported, including relative paths:

The Stack

• Next.js 16: The backbone of our routing and static generation.
• Tailwind CSS v4: For austere, elegant styling.
• Unified/Remark/Rehype: The engine that transforms MDX into interactive content.

Asset Pipeline

Our custom copy-assets.ts script ensures that images located next to your markdown files are correctly mapped to the public directory during the build process. This allows for a clean developer experience where images and text live together.

async function fetchUserData(userId) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.json();
  return { ...data, fetchedAt: Date.now() };
}

// Destructuring, template literals, arrow functions
const formatUser = ({ name, email, roles = [] }) =>
  `${name} <${email}> [${roles.join(', ')}]`;

class EventEmitter {
  #listeners = new Map();

  on(event, callback) {
    if (!this.#listeners.has(event)) {
      this.#listeners.set(event, []);
    }
    this.#listeners.get(event).push(callback);
    return this;
  }

  emit(event, ...args) {
    for (const cb of this.#listeners.get(event) ?? []) {
      cb(...args);
    }
  }
}

TypeScript

interface Repository<T extends { id: string }> {
  findById(id: string): Promise<T | null>;
  findAll(filter?: Partial<T>): Promise<T[]>;
  create(data: Omit<T, 'id'>): Promise<T>;
  update(id: string, data: Partial<T>): Promise<T>;
  delete(id: string): Promise<void>;
}

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

async function tryCatch<T>(fn: () => Promise<T>): Promise<Result<T>> {
  try {
    return { ok: true, value: await fn() };
  } catch (error) {
    return { ok: false, error: error as Error };
  }
}

// Mapped type with conditional
type ReadonlyDeep<T> = {
  readonly [K in keyof T]: T[K] extends object ? ReadonlyDeep<T[K]> : T[K];
};

Python

from dataclasses import dataclass, field
from typing import Generator
import asyncio

@dataclass
class TreeNode:
    value: int
    left: "TreeNode | None" = None
    right: "TreeNode | None" = None

    def inorder(self) -> Generator[int, None, None]:
        if self.left:
            yield from self.left.inorder()
        yield self.value
        if self.right:
            yield from self.right.inorder()

async def fetch_all(urls: list[str]) -> list[dict]:
    async with aiohttp.ClientSession() as session:
        tasks = [session.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [await r.json() for r in responses]

# List comprehension with walrus operator
results = [
    cleaned
    for raw in data
    if (cleaned := raw.strip().lower()) and len(cleaned) > 3
]

Rust

use std::collections::HashMap;

#[derive(Debug, Clone)]
struct LRUCache<K: Eq + std::hash::Hash + Clone, V: Clone> {
    capacity: usize,
    map: HashMap<K, (V, usize)>,
    counter: usize,
}

impl<K: Eq + std::hash::Hash + Clone, V: Clone> LRUCache<K, V> {
    fn new(capacity: usize) -> Self {
        Self {
            capacity,
            map: HashMap::with_capacity(capacity),
            counter: 0,
        }
    }

    fn get(&mut self, key: &K) -> Option<&V> {
        self.counter += 1;
        if let Some(entry) = self.map.get_mut(key) {
            entry.1 = self.counter;
            Some(&entry.0)
        } else {
            None
        }
    }

    fn put(&mut self, key: K, value: V) {
        if self.map.len() >= self.capacity && !self.map.contains_key(&key) {
            let oldest = self.map.iter()
                .min_by_key(|(_, (_, ts))| ts)
                .map(|(k, _)| k.clone());
            if let Some(k) = oldest {
                self.map.remove(&k);
            }
        }
        self.counter += 1;
        self.map.insert(key, (value, self.counter));
    }
}

Go

package main

import (
	"context"
	"fmt"
	"sync"
	"time"
)

type WorkerPool struct {
	workers int
	jobs    chan func() error
	wg      sync.WaitGroup
}

func NewWorkerPool(workers int) *WorkerPool {
	return &WorkerPool{
		workers: workers,
		jobs:    make(chan func() error, workers*2),
	}
}

func (p *WorkerPool) Start(ctx context.Context) <-chan error {
	errs := make(chan error, p.workers)

	for i := 0; i < p.workers; i++ {
		p.wg.Add(1)
		go func(id int) {
			defer p.wg.Done()
			for {
				select {
				case <-ctx.Done():
					return
				case job, ok := <-p.jobs:
					if !ok {
						return
					}
					if err := job(); err != nil {
						errs <- fmt.Errorf("worker %d: %w", id, err)
					}
				}
			}
		}(i)
	}

	go func() {
		p.wg.Wait()
		close(errs)
	}()

	return errs
}

Java

import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Function;

public sealed interface Either<L, R> permits Either.Left, Either.Right {

    record Left<L, R>(L value) implements Either<L, R> {}
    record Right<L, R>(R value) implements Either<L, R> {}

    static <L, R> Either<L, R> left(L value) {
        return new Left<>(value);
    }

    static <L, R> Either<L, R> right(R value) {
        return new Right<>(value);
    }

    default <T> T fold(Function<L, T> onLeft, Function<R, T> onRight) {
        return switch (this) {
            case Left<L, R> l -> onLeft.apply(l.value());
            case Right<L, R> r -> onRight.apply(r.value());
        };
    }

    default <T> Either<L, T> map(Function<R, T> f) {
        return switch (this) {
            case Left<L, R> l -> Either.left(l.value());
            case Right<L, R> r -> Either.right(f.apply(r.value()));
        };
    }
}

C / C++

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

typedef struct Node {
    void *data;
    struct Node *next;
} Node;

typedef struct {
    Node *head;
    size_t size;
    size_t elem_size;
} LinkedList;

LinkedList *list_create(size_t elem_size) {
    LinkedList *list = malloc(sizeof(LinkedList));
    list->head = NULL;
    list->size = 0;
    list->elem_size = elem_size;
    return list;
}

void list_push(LinkedList *list, const void *data) {
    Node *node = malloc(sizeof(Node));
    node->data = malloc(list->elem_size);
    memcpy(node->data, data, list->elem_size);
    node->next = list->head;
    list->head = node;
    list->size++;
}

Ruby

module Enumerable
  def lazy_map(&block)
    Enumerator::Lazy.new(self) do |yielder, value|
      yielder << block.call(value)
    end
  end
end

class Router
  attr_reader :routes

  def initialize(&block)
    @routes = []
    instance_eval(&block) if block_given?
  end

  %i[get post put patch delete].each do |method|
    define_method(method) do |path, **opts, &handler|
      @routes << {
        method: method.upcase,
        pattern: compile_pattern(path),
        handler: handler,
        **opts
      }
    end
  end

  private

  def compile_pattern(path)
    regex = path.gsub(/:(\w+)/) { "(?<#{$1}>[^/]+)" }
    Regexp.new("\\A#{regex}\\z")
  end
end

SQL

WITH monthly_revenue AS (
    SELECT
        date_trunc('month', o.created_at) AS month,
        p.category,
        SUM(oi.quantity * oi.unit_price) AS revenue,
        COUNT(DISTINCT o.customer_id) AS unique_customers
    FROM orders o
    JOIN order_items oi ON o.id = oi.order_id
    JOIN products p ON oi.product_id = p.id
    WHERE o.status = 'completed'
        AND o.created_at >= NOW() - INTERVAL '12 months'
    GROUP BY 1, 2
),
ranked AS (
    SELECT *,
        ROW_NUMBER() OVER (
            PARTITION BY month ORDER BY revenue DESC
        ) AS rank,
        LAG(revenue) OVER (
            PARTITION BY category ORDER BY month
        ) AS prev_month_revenue
    FROM monthly_revenue
)
SELECT
    month,
    category,
    revenue,
    unique_customers,
    ROUND(
        (revenue - prev_month_revenue) / NULLIF(prev_month_revenue, 0) * 100,
        2
    ) AS growth_pct
FROM ranked
WHERE rank <= 5
ORDER BY month DESC, revenue DESC;

Shell / Bash

#!/usr/bin/env bash
set -euo pipefail

readonly LOG_FILE="/var/log/deploy.log"
readonly LOCK_FILE="/tmp/deploy.lock"

log() {
  local level="$1"; shift
  printf "[%s] [%s] %s\n" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$level" "$*" \
    | tee -a "$LOG_FILE"
}

cleanup() {
  rm -f "$LOCK_FILE"
  log INFO "Lock released"
}
trap cleanup EXIT

deploy() {
  local env="${1:?Environment required}"
  local version="${2:-latest}"

  if [[ -f "$LOCK_FILE" ]]; then
    log ERROR "Deployment already in progress"
    return 1
  fi
  echo $$ > "$LOCK_FILE"

  log INFO "Deploying version=$version to env=$env"

  docker pull "app:${version}" \
    && docker compose -f "docker-compose.${env}.yml" up -d \
    && log INFO "Deployment successful" \
    || { log ERROR "Deployment failed"; return 1; }
}

deploy "$@"

HTML / CSS

<dialog id="modal" class="backdrop:bg-black/50">
  <form method="dialog">
    <header>
      <h2>Confirm Action</h2>
      <button type="submit" value="cancel" aria-label="Close">
        &times;
      </button>
    </header>
    <p>Are you sure you want to proceed?</p>
    <footer>
      <button type="submit" value="cancel">Cancel</button>
      <button type="submit" value="confirm" autofocus>Confirm</button>
    </footer>
  </form>
</dialog>

@layer components {
  .card {
    --card-padding: clamp(1rem, 3vw, 2rem);

    display: grid;
    grid-template-rows: auto 1fr auto;
    padding: var(--card-padding);
    border-radius: 0.75rem;
    background: light-dark(white, oklch(0.25 0.01 260));
    box-shadow: 0 1px 3px oklch(0 0 0 / 0.12);
    transition: box-shadow 0.2s ease;

    &:hover {
      box-shadow: 0 8px 24px oklch(0 0 0 / 0.15);
    }

    & > img {
      aspect-ratio: 16 / 9;
      object-fit: cover;
      border-radius: 0.5rem;
    }
  }
}

JSON / YAML

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "strict": true,
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    },
    "plugins": [{ "name": "next" }]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules"]
}

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      retries: 3

  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass

volumes:
  pgdata:

Diff

--- a/src/config.ts
+++ b/src/config.ts
@@ -12,8 +12,10 @@ export const config = {
   pagination: {
     posts: 10,
-    series: 5,
+    series: 12,
   },
+  features: {
+    darkMode: true,
+    search: true,
+  },
 };

Inline Code

Inline code also renders with highlighting: const x: number = 42, a CSS property like background-color: oklch(0.5 0.2 240), or a shell command git rebase -i HEAD~3.

功能测试

中文标签与分类

本文使用了中文标签（中文、测试、i18n）和中文分类（测试），确保它们在标签页和归档页中正确显示。

中文内容渲染

Markdown 渲染引擎应当正确处理中文段落、粗体、斜体、以及行内代码等格式。

这是一段中文引用，用于测试引用块的渲染效果。

代码块

# 中文注释测试
def 问候(名字: str) -> str:
    return f"你好，{名字}！欢迎来到 Amytis。"

print(问候("世界"))

列表

1. 第一项：验证中文文件名在 URL 中的正确编码
2. 第二项：验证中文标签页的链接跳转
3. 第三项：验证搜索功能对中文内容的支持

• 无序列表项一
• 无序列表项二
• 无序列表项三

表格

File-Based Routing

Every folder inside app/ becomes a URL segment. A page.tsx file inside that folder makes it publicly accessible:

app/
├── page.tsx            → /
├── about/
│   └── page.tsx        → /about
├── posts/
│   ├── page.tsx        → /posts
│   └── [slug]/
│       └── page.tsx    → /posts/my-first-post
└── series/
    └── [slug]/
        └── page/
            └── [page]/
                └── page.tsx  → /series/my-series/page/2

Dynamic Routes

Square brackets denote dynamic segments. The parameter value is passed to your component:

// app/posts/[slug]/page.tsx
interface Props {
  params: Promise<{ slug: string }>;
}

export default async function PostPage({ params }: Props) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);

  return <article>{post.title}</article>;
}

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

The generateStaticParams function tells Next.js which pages to pre-render at build time, enabling fully static output.

Layouts

Layouts wrap pages and persist across navigation. They're defined with layout.tsx and receive children as a prop:

// app/layout.tsx — Root layout (required)
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Nested layouts compose naturally. A posts/layout.tsx wraps all post pages without affecting the rest of the site.

Parallel Routes

Parallel routes let you render multiple pages in the same layout simultaneously, using named slots:

app/
└── dashboard/
    ├── layout.tsx
    ├── page.tsx
    ├── @analytics/
    │   └── page.tsx
    └── @activity/
        └── page.tsx

The layout receives each slot as a prop:

export default function DashboardLayout({
  children,
  analytics,
  activity,
}: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  activity: React.ReactNode;
}) {
  return (
    <div className="grid grid-cols-2 gap-4">
      <main>{children}</main>
      <aside>{analytics}</aside>
      <aside>{activity}</aside>
    </div>
  );
}

Intercepted Routes

Intercepted routes display a route within the context of another route — perfect for modals. The (.) convention intercepts a sibling route:

app/
└── posts/
    ├── page.tsx
    ├── [slug]/
    │   └── page.tsx        → Full post page
    └── (.)  [slug]/
        └── page.tsx        → Modal overlay when navigating from /posts

When a user clicks a post link from the listing page, the intercepted route renders as a modal. If they navigate directly to the URL or refresh, they see the full page.

M-P-Model

Summary

Next.js routing is built on a few simple conventions that scale from a single-page site to a complex application. The file system does the heavy lifting — no router configuration, no route registration, just folders and files.

Setting Up with Bun

Bun is a fast JavaScript runtime and package manager that pairs well with Next.js 15. Creating a new project takes a single command:

bunx create-next-app@latest my-app
cd my-app
bun dev

Bun's install speed is noticeably faster than npm or yarn, and its built-in bundler means fewer dependencies in your toolchain.

The App Router

Next.js 15 uses the App Router by default, replacing the legacy Pages Router. The key difference is that every component is a Server Component unless you explicitly opt in to client-side rendering with "use client".

// app/page.tsx — This is a Server Component by default
export default function HomePage() {
  return (
    <main>
      <h1>Welcome to Next.js 15</h1>
      <p>This component renders on the server.</p>
    </main>
  );
}

Server Components unlock several benefits:

• Smaller client bundles — Server-only code never ships to the browser
• Direct data access — Query databases or read files without an API layer
• Streaming — The server can send HTML progressively as components render

Static Export

For sites that don't need a running server (blogs, documentation, landing pages), Next.js supports full static export:

// next.config.ts
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

export default nextConfig;

Running bun run build with this configuration generates a out/ directory containing plain HTML, CSS, and JavaScript files. You can deploy this to any static hosting service — GitHub Pages, Netlify, Cloudflare Pages, or an S3 bucket.

What's Next

In Part 2, we'll explore the file-based routing system in depth: dynamic routes, route groups, layouts, and how Next.js turns your folder structure into a fully-featured application.

核心特性 (Core Features)

1. 自动生成目录 (TOC)

该部分用于测试中文标题是否能正确生成 ID 并在侧边栏中点击跳转。

2. 代码高亮 (Syntax Highlighting)

支持多种编程语言的高亮显示。

// 这是一个 TypeScript 示例
function greet(name: string): string {
  return `你好, ${name}! Welcome to Amytis.`;
}

// 这是一个 Rust 示例
fn main() {
    println!("你好，世界！");
}

深入探讨 (Deep Dive)

3. 排版展示 (Typography)

中文排版需要考虑字符间距和行高。在 Tailwind v4 中，我们通过 prose-emerald 插件来优化视觉效果。

这是一段较长的中文测试文本： 数字花园不仅仅是一个博客，它是一个不断生长的知识库。在这里，每一个节点都可能触发新的思考。我们支持 加粗、斜体、删除线 以及 行内代码。

4. 国际化支持 (I18n)

Amytis 旨在支持多种语言的无缝切换（虽然目前主要展示中文支持）。对于 CJK 字符，由于没有空格作为天然的分隔符，目录生成逻辑（slugify）需要特别处理。我们现在使用 github-slugger 来确保 ID 生成的一致性。

复杂图表 (Mermaid)

测试 Mermaid 图表中的中文标签是否正常显示。

flowchart LR
    A[开始] --> B{是否成功?}
    B -- 是 --> C[庆祝]
    B -- 否 --> D[调试代码]
    D --> B

技术实现 (Technical Implementation)

5. Next.js App Router

我们利用 Next.js 15 的强力特性，如静态生成 (SSG) 和 服务器组件 (Server Components)。

6. Tailwind CSS v4

采用最新的 Tailwind CSS v4，利用其高性能的引擎和更简洁的配置。

7. 静态站点导出 (Static Export)

由于我们需要将站点部署在 GitHub Pages 或类似的静态托管服务上，我们使用了 output: 'export'。

数学公式 (LaTeX)

支持行内公式 $E=mc^2$ 以及块级公式：

$$ \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$

更多测试章节 (Extended Sections)

8. 列表测试 (Lists)

• 无序列表项一 (Unordered Item 1)
• 无序列表项二 (Unordered Item 2)
  • 嵌套项 (Nested Item)
  • 嵌套项二 (Nested Item 2)

1. 有序列表项一 (Ordered Item 1)
2. 有序列表项二 (Ordered Item 2)

9. 引用块 (Blockquotes)

这是一个带有作者信息的引用块。数字花园的概念最早由 Mike Caulfield 提出，强调知识的非线性和持续演进。

10. 脚注测试

我们可以为某些词汇添加脚注¹。

未来展望 (Future Roadmap)

11. 搜索功能增强

我们将集成模糊搜索，支持中文分词，提升搜索体验。

12. 更多主题色

除了现在的翡翠色 (Emerald)，我们还计划支持琥珀色 (Amber) 和 玫瑰色 (Rose)。

总结

多语言支持对于数字花园至关重要。

"语言的边界就是世界的边界。" — 维特根斯坦

Heading Level 2

Here is a blockquote:

"The digital garden is not just a collection of posts, but a web of interconnected thoughts."

— Unknown Gardener

Heading Level 3

Heading Level 4

Heading Level 5

Heading Level 6

Lists

Unordered

• Item 1
• Item 2
  • Nested Item 2.1
  • Nested Item 2.2
• Item 3

Ordered

1. Step One
2. Step Two
3. Step Three

Task List

• Implement Markdown
• Add Syntax Highlighting
• Write Documentation

Code

Inline

The useState hook is essential. You can install via bun install.

Code Blocks

TypeScript:

interface User {
  id: number;
  name: string;
}

function getUser(id: number): User {
  return { id, name: "Alice" };
}

Bash:

echo "Hello World" > hello.txt
ls -la

JSON:

{
  "project": "Amytis",
  "version": "1.4.0"
}

Math (LaTeX)

Inline math: $E = mc^2$ and $e^{iπ} + 1 = 0$.

Block math:

$$ \frac{1}{\sigma\sqrt{2\pi}} \exp\left( -\frac{1}{2} \left( \frac{x-\mu}{\sigma} \right)^2 \right) $$

Diagrams (Mermaid)

Flowchart

flowchart LR
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Great!]
    B -- No --> D[Debug]
    D --> B

Sequence Diagram

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!

Images

Standard Markdown

Raw HTML (Quoted)

Photos from Public Directory

Vibrant Waves (JPG format)

Side by Side (Raw HTML)

Tables

Links

• Internal Link to Home
• External Link (Google)
• Reference Link

HTML Components

Footnotes

Here is a footnote reference¹. And another one².

Tables

Footnotes

Here is a simple footnote¹.

Wide Table Test

Testing horizontal scrolling for very wide tables with extensive content.

Links

Standard inline link: Next.js Website

Reference-style link: Amytis GitHub

Autolinks (GFM): https://google.com and www.github.com

More Reference Links

Here are some search engines: Google, Yahoo, and Bing.

Footnotes(big)

And here is a longer one².

Task List

• Install remark-gfm
• Configure ReactMarkdown
• Verify rendering

Strikethrough

This text is struck through.

Autolink literals

inline html pic

测试一下 (Quoted - Recommended):

测试一下 (Unquoted - Testing): <img src=./images/test.svg width="100" style="display: inline-block;" alt="Unquoted Image" />

Simple Unquoted: <img src=./images/test.svg />

Note on HTML Attributes

HTML5 allows omitting quotes for simple values. This should work.

Why support both?

Migration from other systems (Jekyll, Hugo) often involves thousands of .md files. Supporting them natively makes migration easier.

Footnotes

Footnote test¹.

One of the main benefits of .md support is seamless migration. If you're moving from Jekyll, Hugo, or another static site generator, your existing posts can be dropped into the content/posts/ directory without any changes. Frontmatter fields like title, date, and tags are parsed identically for both formats.

The key difference is that .mdx files allow embedding React components directly in your content, while .md files stick to standard Markdown. For most blog posts, standard Markdown is more than sufficient — and keeping your content in .md means it stays portable across any Markdown-compatible system.

Code Block Test

console.log("Hello from .md file!");

• Item 1
• Item 2

References

This is a [link to markdown guide][md-guide].

Internal links: Home and Archives.

More Reference Links

Reference links test: Markdown Guide, CommonMark.

markdown table

The Evolution

1. Callbacks (Callback Hell)
2. Promises
3. Async/Await

Code Comparison

Using Promises:

fetchData()
  .then(data => process(data))
  .catch(err => console.error(err));

Using Async/Await:

async function getData() {
  try {
    const data = await fetchData();
    return process(data);
  } catch (err) {
    console.error(err);
  }
}

Promise State Machine

stateDiagram-v2
    [*] --> Pending
    Pending --> Fulfilled : resolve()
    Pending --> Rejected : reject()
    Fulfilled --> [*]
    Rejected --> [*]

Implementation

function quickSort(arr: number[]): number[] {
  if (arr.length <= 1) {
    return arr;
  }

  const pivot = arr[arr.length - 1];
  const left = [];
  const right = [];

  for (let i = 0; i < arr.length - 1; i++) {
    if (arr[i] < pivot) {
      left.push(arr[i]);
    } else {
      right.push(arr[i]);
    }
  }

  return [...quickSort(left), pivot, ...quickSort(right)];
}

Logic Flow

graph TD
    Start([Start]) --> Check{"Length <= 1?"}
    Check -- Yes --> Return["Return Array"]
    Check -- No --> Pivot["Choose Pivot"]
    Pivot --> Partition["Partition Array"]
    Partition --> RecurseL["Recurse Left"]
    Partition --> RecurseR["Recurse Right"]
    RecurseL --> Combine["Combine Results"]
    RecurseR --> Combine
    Combine --> End([End])

Images

.. image:: ./images/test.svg :alt: Test image