@limcpf/everything-is-a-markdown 0.6.6 → 0.6.7

package/README.ko.md

@@ -180,6 +180,25 @@ title: Work In Progress
 ---
 ```
 
+## 위키링크 지원
+
+위키링크는 아래 순서로 해석됩니다.
+
+1. 볼트 기준 상대 경로(확장자 `.md` 제외)
+2. `prefix`
+3. `title` 정확히 일치
+4. 파일 stem(유일할 때만)
+
+예시:
+
+- `[[posts/2024/setup-guide]]`
+- `[[BC-VO-02]]`
+- `[[Building a File-System Blog]]`
+- `[[setup-guide]]`
+- `[[Building a File-System Blog|먼저 읽기]]`
+
+대상을 찾지 못하거나 같은 `title`을 가진 게시 문서가 여러 개면 링크로 바꾸지 않고 빌드 warning을 출력합니다.
+
 ## Mermaid 다이어그램 지원
 
 코드 블록의 언어를 `mermaid`로 작성하면 브라우저에서 Mermaid 다이어그램으로 렌더링합니다.
@@ -197,6 +216,34 @@ Mermaid fence는 일반 코드 블록 UI와 분리된 전용 컨테이너(`.merm
 본문 이미지도 동일한 폭 정책을 적용해 글 읽기 흐름을 유지합니다.
 설정에서 Mermaid를 비활성화하거나 CDN 로드가 실패하면, 같은 컨테이너 안에서 소스 코드 텍스트를 유지하고 하단에 경고 메시지를 표시합니다.
 
+## 본문 이미지 레이아웃
+
+본문 이미지는 이제 방향에 따라 표시 폭을 다르게 조정합니다.
+
+- 가로 이미지는 기본 읽기 폭을 유지합니다.
+- 세로 이미지는 더 좁은 최대 폭을 적용해 본문을 과하게 압도하지 않게 합니다.
+- 정사각형에 가까운 이미지는 중간 폭을 사용합니다.
+
+`markdown.images: "keep"`로 로컬 Markdown 이미지를 허용하면, 이미지만 있는 문단은 자동으로 `figure.content-image` 래퍼로 승격됩니다.
+고정 비율이나 자르기 방식을 직접 지정하고 싶을 때는 raw HTML figure 유틸리티를 사용할 수 있습니다.
+
+예시:
+
+```html
+<figure class="image-frame ratio-4x3 fit-cover">
+  <img src="/assets/hero.jpg" alt="Cover-framed image" />
+</figure>
+
+<figure class="image-frame ratio-4x5 fit-contain">
+  <img src="/assets/poster.jpg" alt="Contain-framed image" />
+</figure>
+```
+
+지원 유틸리티:
+
+- 비율: `ratio-16x9`, `ratio-4x3`, `ratio-3x2`, `ratio-4x5`
+- 맞춤 방식: `fit-cover`, `fit-contain`
+
 `blog.config.ts`에서 설정:
 
 ```ts

package/README.md

@@ -2,226 +2,557 @@
 
 Language: **English** | [한국어](README.ko.md)
 
-Everything-Is-A-Markdown is a CLI tool that turns a local Markdown vault into a static website while keeping the folder/file navigation experience.
+Everything-Is-A-Markdown is a Bun-based CLI that turns a local Markdown vault into a static site with a file-explorer UI. It is designed for workflows where most notes stay private and only explicitly published documents are exposed as a browsable website.
 
-## What This App Is For
+The generated site keeps a two-panel experience:
 
-- Build a static docs/blog site from your Markdown vault
-- Publish only documents with `publish: true`
-- Keep private notes and public content separate
+- Left: folder tree, virtual folders, branch filters
+- Right: rendered document viewer with metadata, backlinks, and previous/next navigation
 
-## Works Great with Obsidian
+## What It Does
 
-- You can keep writing in Obsidian and publish selected notes.
-- Obsidian-style wikilinks (`[[...]]`) are supported.
+- Builds a static site from a local Markdown vault
+- Publishes only notes with `publish: true`
+- Requires a `prefix` field for every published note and uses it as the public route
+- Supports Obsidian-style wikilinks such as `[[note]]` and `[[note|label]]`
+- Renders code blocks with Shiki
+- Renders Mermaid blocks in the browser with runtime fallback handling
+- Generates per-route HTML pages for direct access without SPA-only routing
+- Produces a manifest used by the runtime tree/navigation UI
+- Supports a `Recent` virtual folder and an optional pinned virtual folder
+- Supports branch-based filtering in the sidebar
+- Can generate sitemap/robots/canonical metadata when SEO config is provided
+
+## Important Behavior
+
+This project currently uses `prefix`-based public routes, not vault-relative path routes.
+
+Example:
+
+- Source file: `posts/2024/setup-guide.md`
+- Frontmatter: `prefix: BC-VO-02`
+- Public route: `/BC-VO-02/`
+
+If two notes normalize to the same public route, the builder keeps both and automatically appends a suffix to later collisions.
+
+## Who This Fits
+
+- Obsidian users who want selective publishing
+- Personal docs/blog workflows backed by a local vault
+- Static hosting targets such as Cloudflare Pages, GitHub Pages, or any plain file server
+- Projects that want a lightweight runtime instead of a full app framework
+
+## Requirements
+
+- `bun` installed
+- A Markdown vault directory
+
+This repository is authored around Bun. The CLI entry point is `src/cli.ts`, and package scripts assume Bun is available.
 
 ## Install
 
+For local development in this repository:
+
 ```bash
 bun install
 ```
 
-## Usage
+To run the published package without cloning:
 
 ```bash
-bun run blog [build|dev|clean] [options]
+bunx @limcpf/everything-is-a-markdown build --vault ./vault --out ./dist
 ```
 
-Commands:
+## Quick Start
+
+1. Prepare a vault with Markdown files.
+2. Add frontmatter to notes you want to publish.
+3. Run a build or start the dev server.
 
-- `bun run build`: Build static files
-- `bun run dev`: Run local dev server (default `http://localhost:3000`)
-- `bun run clean`: Remove `dist` and `.cache`
+Example:
 
-Common options:
+```bash
+bun run dev -- --vault ./test-vault --out ./dist
+```
 
-- `--vault <path>`: Markdown root directory (default `.`)
-- `--out <path>`: Output directory (default `dist`)
-- `--exclude <glob>`: Add exclude pattern (repeatable)
-- `--new-within-days <n>`: NEW badge threshold days (integer `>= 0`, default `7`)
-- `--recent-limit <n>`: Recent folder item limit (integer `>= 1`, default `5`)
-- `--port <n>`: Dev server port (default `3000`)
+Build once:
 
-## Markdown Lint (publish only)
+```bash
+bun run build -- --vault ./test-vault --out ./dist
+```
 
-You can run Markdown lint only for `publish: true` documents and save results as a JSON report.
-Internally, this command uses the `markdownlint` Node API.
+Clean generated artifacts:
 
 ```bash
-bun run lint:md:publish -- --out-dir ./reports
+bun run clean -- --out ./dist
 ```
 
-Add strict mode (`--strict`) to return exit code `1` when violations exist.
+## CLI
 
 ```bash
-bun run lint:md:publish -- --out-dir ./reports --strict
+bun run src/cli.ts [build|dev|clean] [options]
 ```
 
+Package script aliases:
+
+- `bun run build`
+- `bun run dev`
+- `bun run clean`
+- `bun run blog`
+
 Options:
 
-- `--out-dir <path>`: Report output directory (required)
-- `--strict`: Return exit code `1` when violations exist
-- `--vault <path>`: Override Markdown root directory (optional)
-- `--exclude <glob>`: Add exclude pattern (repeatable)
+- `--vault <path>`: vault root directory, default `.`.
+- `--out <path>`: output directory, default `dist`.
+- `--exclude <glob>`: exclude glob pattern, repeatable. `.obsidian/**` is excluded by default.
+- `--new-within-days <n>`: NEW badge threshold, integer `>= 0`, default `7`.
+- `--recent-limit <n>`: number of items in the `Recent` virtual folder, integer `>= 1`, default `5`.
+- `--menu-config <path>`: JSON file that overrides `pinnedMenu`.
+- `--port <n>`: dev server port, default `3000`.
+- `-h`, `--help`: show help.
+
+Notes:
+
+- Unknown CLI options fail fast.
+- Invalid numeric options fail fast.
+- `clean` removes both the output directory and `.cache`.
+
+## Frontmatter
+
+Only documents with `publish: true` are considered for output.
 
-## Config File (`blog.config.ts`)
+### Required for published docs
 
-Use a config file for SEO/UI/static assets.
+- `publish: true`
+- `prefix: "BC-VO-02"`
+
+If `publish: true` is set but `prefix` is missing, the note is skipped and a build warning is emitted.
+
+### Supported fields
+
+- `title`: display title. Falls back to a title derived from the file name.
+- `description`: summary used in UI and SEO metadata.
+- `tags`: string array.
+- `date` or `createdDate`: publish/created date.
+- `updatedDate`, `modifiedDate`, or `lastModified`: update date.
+- `branch`: branch label used by the runtime filter UI.
+- `draft: true`: excludes the note even if `publish: true`.
+
+Example:
+
+```md
+---
+publish: true
+prefix: BC-VO-02
+branch: dev
+title: Setup Guide
+date: "2024-09-15"
+updatedDate: "2024-09-20T09:30:00"
+description: How to set up your development environment
+tags: ["tutorial", "setup"]
+---
+```
+
+## Routing Model
+
+Public routes are derived from `prefix`, not from the file path.
+
+Normalization rules:
+
+- trims whitespace
+- normalizes Unicode
+- converts spaces and `_` to `-`
+- converts `/` to `-`
+- removes unsupported punctuation
+- preserves letter case from the original prefix
+
+Examples:
+
+- `prefix: BC-VO-02` -> `/BC-VO-02/`
+- `prefix: Docs / Intro` -> `/Docs-Intro/`
+
+The root `index.html` opens a default home document. If a document route is `/index/`, that route is preferred as home; otherwise the most recent document in the default branch is used.
+
+## Output Structure
+
+The build writes a static site into `dist/` by default.
+
+Typical output:
+
+```text
+dist/
+  404.html
+  index.html
+  manifest.json
+  robots.txt              # only when seo.siteUrl is configured
+  sitemap.xml             # only when seo.siteUrl is configured
+  _app/index.html
+  assets/
+    app.<hash>.css
+    app.<hash>.js
+  content/
+    <sha1-of-doc-id>.html
+  BC-VO-00/
+    index.html
+  BC-VO-01/
+    index.html
+```
+
+Key points:
+
+- Every published route gets its own `index.html` for direct access.
+- Rendered article bodies are stored separately under `dist/content/`.
+- Runtime assets are content-hashed.
+- Static files declared in config are copied into the same relative paths under `dist/`.
+- Build cache is stored under `.cache/build-index.json`.
+
+## Config File
+
+The builder automatically loads one of these files from the current working directory:
+
+- `blog.config.ts`
+- `blog.config.js`
+- `blog.config.mjs`
+- `blog.config.cjs`
+
+Example:
 
 ```ts
-const config = {
+export default {
   vaultDir: "./vault",
   outDir: "./dist",
+  exclude: [".obsidian/**", "private/**"],
   staticPaths: ["assets", "public/favicon.ico"],
-  seo: {
-    siteUrl: "https://example.com",
-    pathBase: "/blog",
-    defaultOgImage: "/assets/og.png",
+  pinnedMenu: {
+    label: "NOTICE",
+    sourceDir: "announcements",
+  },
+  ui: {
+    newWithinDays: 7,
+    recentLimit: 5,
   },
   markdown: {
+    wikilinks: true,
+    images: "omit-local",
+    gfm: true,
+    highlight: {
+      engine: "shiki",
+      theme: "github-dark",
+    },
     mermaid: {
       enabled: true,
       cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js",
       theme: "default",
     },
   },
+  seo: {
+    siteUrl: "https://example.com",
+    pathBase: "/blog",
+    siteName: "My Vault",
+    defaultTitle: "My Vault",
+    defaultDescription: "Published notes from my vault",
+    locale: "en_US",
+    twitterCard: "summary_large_image",
+    twitterSite: "@example",
+    twitterCreator: "@example",
+    defaultSocialImage: "/assets/social.png",
+    defaultOgImage: "/assets/og.png",
+    defaultTwitterImage: "/assets/twitter.png",
+  },
 };
-
-export default config;
 ```
 
-`staticPaths`:
+### Config fields
 
-- Array of vault-relative paths
-- Supports both folders and files
-- Copies all matched files into the same relative location in `dist`
-- Example: `assets/og.png` in vault becomes `dist/assets/og.png`
+- `vaultDir`: default vault root.
+- `outDir`: default output directory.
+- `exclude`: extra exclude globs.
+- `staticPaths`: vault-relative files or directories copied into output.
+- `pinnedMenu`: optional virtual folder shown above `Recent`.
+- `ui.newWithinDays`: threshold for NEW badge.
+- `ui.recentLimit`: number of items in `Recent`.
+- `markdown.wikilinks`: enable or disable wikilink resolution.
+- `markdown.images`: `"keep"` or `"omit-local"`.
+- `markdown.gfm`: enable or disable GFM table/strikethrough support.
+- `markdown.highlight.theme`: Shiki theme.
+- `markdown.mermaid.*`: Mermaid runtime settings.
+- `seo.*`: canonical URL, social metadata, sitemap, robots, and path-base behavior.
 
-`seo.pathBase`:
+### `staticPaths`
 
-- Deploy under a subpath (for example `/blog`)
-- Internal routing/content fetch links are generated with this base path
-- Keep empty (`""`) for root deployment
+- Must be vault-relative
+- Can point to either a file or a directory
+- Are copied as-is into the output directory
+- Invalid or missing paths are skipped with a warning
 
-Examples:
+### `pinnedMenu`
+
+`pinnedMenu` creates a virtual folder at the top of the sidebar by collecting published docs whose vault-relative path starts with the configured `sourceDir`.
+
+Example:
+
+```ts
+pinnedMenu: {
+  label: "NOTICE",
+  sourceDir: "announcements",
+}
+```
+
+CLI override example:
 
 ```bash
-# Run with the sample vault
-bun run dev -- --vault ./test-vault --out ./dist
+bun run build -- --menu-config ./menu.config.json
+```
 
-# Build
-bun run build -- --vault ./test-vault --out ./dist
+JSON shape:
+
+```json
+{
+  "pinnedMenu": {
+    "label": "NOTICE",
+    "sourceDir": "announcements"
+  }
+}
 ```
 
-## Markdown Frontmatter
+## Markdown Features
 
-The key field for publishing is `publish`.
+### Supported
 
-Required:
+- Common Markdown via `markdown-it`
+- GFM tables and strikethrough when enabled
+- Raw HTML inside Markdown
+- Syntax-highlighted fenced code blocks with Shiki
+- External links opened with `target="_blank"` and `rel="noopener noreferrer"`
+- Obsidian-style wikilinks for document links
 
-- `publish: true`  
-  Only documents with this value are included in build output.
-- `prefix: "A-01"`  
-  Public identifier for the document route (`/A-01/`).  
-  If `publish: true` but `prefix` is missing, the document is skipped with a build warning.
+### Wikilinks
 
-Optional:
+Resolution order:
 
-- `draft: true`  
-  Excludes the document even if `publish: true`.
-- `title: "..."`  
-  Display title. If missing, file name is used.
-- `branch: dev`  
-  Branch filter label.
-- `description: "..."`  
-  Short summary.
-- `tags: ["tag1", "tag2"]`  
-  String array.
-- `date: "YYYY-MM-DD"` or `createdDate: "..."`  
-  Created date.
-- `updatedDate: "..."` or `modifiedDate: "..."` or `lastModified: "..."`  
-  Updated date.
+1. Vault-relative path without `.md`
+2. `prefix`
+3. `title` (exact match)
+4. File stem if unique
 
-## Frontmatter Examples
+Supported forms:
 
-Published document:
+- `[[posts/2024/setup-guide]]`
+- `[[BC-VO-02]]`
+- `[[Building a File-System Blog]]`
+- `[[setup-guide]]`
+- `[[Building a File-System Blog|Read this first]]`
+- `[[setup-guide|Read this first]]`
 
-```md
----
-publish: true
-prefix: "DEV-01"
-branch: dev
-title: Setup Guide
-date: "2024-09-15"
-updatedDate: "2024-09-20T09:30:00"
-description: How to set up your development environment
-tags: ["tutorial", "setup"]
----
+If a target cannot be resolved, or a `title` matches multiple published docs, the Markdown is emitted as plain text and the build prints a warning.
 
-# Setup Guide
-```
+### Images
 
-Private document (excluded):
+Image behavior is controlled by `markdown.images`.
 
-```md
----
-publish: false
-title: Internal Notes
----
-```
+- `"keep"`: keeps Markdown image output as-is.
+- `"omit-local"`: replaces local images with an italic placeholder and emits a warning.
 
-Draft document:
+Remote URLs are kept even when `"omit-local"` is used.
 
-```md
----
-publish: true
-draft: true
-title: Work In Progress
----
-```
+This rule also applies to Obsidian-style image embeds such as `![[image.png]]`.
+
+### Code Blocks
+
+Regular fenced code blocks are rendered with:
 
-## Mermaid Diagram Support
+- Shiki highlighting
+- a desktop-style code header
+- a copy button
+- optional filename text when fence info contains extra tokens
 
-This project supports Mermaid diagrams written as fenced code blocks:
+Example:
 
+````md
+```ts blog.config.ts
+export default {};
+```
 ````
+
+### Mermaid
+
+Mermaid fences are rendered in the browser:
+
+````md
 ```mermaid
 flowchart LR
   A --> B
 ```
 ````
 
-Rendering happens in the browser on first load and when navigating to another document.
-Mermaid fences are rendered inside a dedicated diagram container (`.mermaid-block`) instead of the regular code block UI, so they do not show code headers, filenames, or copy buttons.
-Rendered SVG output is centered and automatically constrained to `min(100%, 720px)` on both desktop and mobile.
-Regular content images inside the viewer follow the same width policy to keep reading flow stable.
-If Mermaid is disabled in config or CDN loading fails, the source block is shown as-is in the same container and a warning message appears below it.
+Behavior:
 
-Configuration options (`blog.config.ts`):
+- rendered on first load and on document navigation
+- centered and width-constrained in the viewer
+- if rendering fails, source remains visible and an error message is shown
+- invalid Mermaid CDN URLs or invalid theme values are normalized back to safe defaults
 
-```ts
-markdown: {
-  mermaid: {
-    enabled: true, // false to keep only source blocks
-    cdnUrl: "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js", // CDN URL (http/https or /, ./, ../)
-    theme: "default", // passed to mermaid.initialize({ theme })
-  },
-},
+## Body Image Layout
+
+Body images now use orientation-aware sizing inside the viewer:
+
+- Landscape images keep the standard reading width.
+- Portrait images are automatically constrained to a narrower max width so they do not dominate the article.
+- Near-square images get an intermediate width.
+
+When local Markdown images are enabled with `markdown.images: "keep"`, standalone image paragraphs are promoted into a dedicated `figure.content-image` wrapper automatically.
+Raw HTML remains available for manual framing when you want a fixed ratio or a specific crop mode.
+
+Example frame utilities:
+
+```html
+<figure class="image-frame ratio-4x3 fit-cover">
+  <img src="/assets/hero.jpg" alt="Cover-framed image" />
+</figure>
+
+<figure class="image-frame ratio-4x5 fit-contain">
+  <img src="/assets/poster.jpg" alt="Contain-framed image" />
+</figure>
+```
+
+Supported frame utilities:
+
+- Ratios: `ratio-16x9`, `ratio-4x3`, `ratio-3x2`, `ratio-4x5`
+- Fit modes: `fit-cover`, `fit-contain`
+
+## UI and Runtime Behavior
+
+The generated site includes a client-side runtime that powers navigation without requiring a framework.
+
+Main behaviors:
+
+- folder tree with expand/collapse state in `localStorage`
+- `Recent` virtual folder
+- optional pinned virtual folder
+- branch pills in the sidebar
+- active document syncing with browser history
+- direct-link loading from route HTML
+- previous/next document navigation
+- backlink list for notes referenced by other notes
+- mobile sidebar with accessibility handling and focus trap behavior
+- theme mode persistence: `light`, `dark`, `system`
+- sidebar width persistence on desktop
+
+Branch behavior:
+
+- the default branch is `dev`
+- notes without `branch` belong to the default branch view
+- notes with `branch: main` or another value appear only in that branch
+
+## SEO Support
+
+SEO artifacts are generated only when `seo.siteUrl` is configured.
+
+With SEO enabled, the build writes:
+
+- canonical URLs
+- Open Graph metadata
+- Twitter metadata
+- JSON-LD structured data
+- `robots.txt`
+- `sitemap.xml`
+
+`seo.pathBase` is supported for subpath deployments such as `/blog`.
+
+Example:
+
+- public site root: `https://example.com`
+- path base: `/blog`
+- route: `/BC-VO-02/`
+- canonical URL: `https://example.com/blog/BC-VO-02/`
+
+## Incremental Build and Caching
+
+The build caches source metadata and output hashes in `.cache/build-index.json`.
+
+This allows it to:
+
+- skip unchanged rendered content
+- restore missing generated content files on a later build
+- restore missing hashed runtime assets on a later build
+- remove stale route pages and content files when documents are removed or routes change
+
+## Markdown Lint for Published Docs
+
+This repository includes a publish-only Markdown lint command:
+
+```bash
+bun run lint:md:publish -- --out-dir ./reports
+```
+
+Strict mode:
+
+```bash
+bun run lint:md:publish -- --out-dir ./reports --strict
 ```
 
-Validation and runtime guardrails:
+Options:
 
-- Invalid `markdown.mermaid.cdnUrl` values (for example `javascript:`) automatically fall back to the default CDN URL at build time.
-- Invalid `markdown.mermaid.theme` values automatically fall back to `default` at build time.
-- Runtime loader removes stale Mermaid script tags after failures, avoids duplicate injection, and retries cleanly on the next render.
+- `--out-dir <path>`: required report directory
+- `--strict`: exits with status `1` when issues exist
+- `--vault <path>`: override vault root
+- `--exclude <glob>`: extra exclude patterns
 
-## bunx (Optional)
+What it checks:
+
+- only notes with `publish: true`
+- skips docs missing `prefix`
+- runs `markdownlint`
+- adds a custom rule that forbids H1 in the Markdown body after frontmatter
+- writes a JSON report file
+
+## Example Vault
+
+This repository includes `test-vault/` as a working sample.
+
+Example files:
+
+- `test-vault/about.md`
+- `test-vault/posts/2024/setup-guide.md`
+- `test-vault/posts/2024/file-system-blog.md`
+- `test-vault/posts/2024/mermaid-example.md`
+
+Try it with:
 
 ```bash
-bunx @limcpf/everything-is-a-markdown build --vault ./vault --out ./dist
-bunx @limcpf/everything-is-a-markdown dev --port 3000
+bun run dev -- --vault ./test-vault --out ./dist
+```
+
+## Development
+
+Scripts from `package.json`:
+
+```bash
+bun install
+bun run build -- --vault ./test-vault --out ./dist
+bun run dev -- --vault ./test-vault --out ./dist
+bun run test:e2e
 ```
 
+E2E coverage in `tests/e2e/` includes:
+
+- build regression around incremental outputs
+- subpath routing with `seo.pathBase`
+- prefix routing, backlinks, and branch switching
+- Mermaid runtime behavior
+- mobile sidebar accessibility and focus trap behavior
+- runtime XSS/path-base guardrails
+
+## Known Limitations
+
+- Bun is required; this is not a generic Node-only CLI.
+- Public routing depends on `prefix`, not on file path.
+- Published docs without `prefix` are skipped.
+- Local images may be omitted depending on config.
+- Wikilinks resolve only to published docs.
+- Mermaid rendering depends on runtime script loading in the browser.
+- SEO files are not generated unless `seo.siteUrl` is configured.
+
 ## License
 
-MIT. See `LICENSE`.
+MIT. See [LICENSE](/home/lim/code/Everything-Is-A-Markdown/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@limcpf/everything-is-a-markdown",
-	"version": "0.6.6",
+	"version": "0.6.7",
 	"license": "MIT",
 	"private": false,
 	"type": "module",

package/src/build.ts

@@ -44,6 +44,7 @@ interface RuntimeAssets {
 interface WikiLookup {
   byPath: Map<string, DocRecord>;
   byPrefix: Map<string, DocRecord[]>;
+  byTitle: Map<string, DocRecord[]>;
   byStem: Map<string, DocRecord[]>;
 }
 
@@ -573,6 +574,7 @@ async function readPublishedDocs(options: BuildOptions, previousSources: BuildCa
 function createWikiLookup(docs: DocRecord[]): WikiLookup {
   const byPath = new Map<string, DocRecord>();
   const byPrefix = new Map<string, DocRecord[]>();
+  const byTitle = new Map<string, DocRecord[]>();
   const byStem = new Map<string, DocRecord[]>();
 
   for (const doc of docs) {
@@ -583,13 +585,19 @@ function createWikiLookup(docs: DocRecord[]): WikiLookup {
       prefixBucket.push(doc);
       byPrefix.set(prefixKey, prefixBucket);
     }
+    const titleKey = normalizeWikiTarget(doc.title);
+    if (titleKey) {
+      const titleBucket = byTitle.get(titleKey) ?? [];
+      titleBucket.push(doc);
+      byTitle.set(titleKey, titleBucket);
+    }
     const stem = path.basename(doc.relNoExt).toLowerCase();
     const bucket = byStem.get(stem) ?? [];
     bucket.push(doc);
     byStem.set(stem, bucket);
   }
 
-  return { byPath, byPrefix, byStem };
+  return { byPath, byPrefix, byTitle, byStem };
 }
 
 function resolveWikiTargetDoc(
@@ -622,6 +630,20 @@ function resolveWikiTargetDoc(
     return null;
   }
 
+  const titleMatches = lookup.byTitle.get(normalized) ?? [];
+  if (titleMatches.length === 1) {
+    return titleMatches[0];
+  }
+
+  if (warnOnDuplicate && titleMatches.length > 1) {
+    console.warn(
+      `[wikilink] Duplicate title target "${input}" in ${currentDoc.relPath}. Candidates: ${titleMatches
+        .map((item) => item.relPath)
+        .join(", ")}`,
+    );
+    return null;
+  }
+
   if (normalized.includes("/")) {
     return null;
   }

package/src/markdown.ts

@@ -24,6 +24,8 @@ type RuleOptions = RenderRuleArgs[2];
 type RuleEnv = RenderRuleArgs[3];
 type RuleSelf = RenderRuleArgs[4];
 type LinkOpenRule = NonNullable<MarkdownIt["renderer"]["rules"]["link_open"]>;
+type ImageRule = NonNullable<MarkdownIt["renderer"]["rules"]["image"]>;
+type ParagraphRule = NonNullable<MarkdownIt["renderer"]["rules"]["paragraph_open"]>;
 
 function escapeMarkdownLabel(input: string): string {
   return input.replace(/[\[\]]/g, "");
@@ -141,6 +143,22 @@ function escapeHtmlAttr(input: string): string {
   return input.replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+function isStandaloneImageParagraph(tokens: RuleTokens, idx: number): boolean {
+  const open = tokens[idx];
+  const inline = tokens[idx + 1];
+  const close = tokens[idx + 2];
+
+  if (open?.type !== "paragraph_open" || inline?.type !== "inline" || close?.type !== "paragraph_close") {
+    return false;
+  }
+
+  const children = (inline.children ?? []).filter((child) => {
+    return !(child.type === "text" && !child.content.trim());
+  });
+
+  return children.length === 1 && children[0]?.type === "image";
+}
+
 function createMarkdownIt<L extends string, T extends string>(
   highlighter: HighlighterGeneric<L, T>,
   theme: string,
@@ -201,6 +219,57 @@ function createMarkdownIt<L extends string, T extends string>(
   };
   md.renderer.rules.fence = fenceRule;
 
+  const defaultImage = md.renderer.rules.image as ImageRule | undefined;
+  const imageRule: ImageRule = (
+    tokens: RuleTokens,
+    idx: number,
+    options: RuleOptions,
+    env: RuleEnv,
+    self: RuleSelf,
+  ) => {
+    tokens[idx].attrJoin("class", "content-media");
+    if (defaultImage) {
+      return defaultImage(tokens, idx, options, env, self);
+    }
+    return self.renderToken(tokens, idx, options);
+  };
+  md.renderer.rules.image = imageRule;
+
+  const defaultParagraphOpen = md.renderer.rules.paragraph_open as ParagraphRule | undefined;
+  const defaultParagraphClose = md.renderer.rules.paragraph_close as ParagraphRule | undefined;
+  const paragraphOpenRule: ParagraphRule = (
+    tokens: RuleTokens,
+    idx: number,
+    options: RuleOptions,
+    env: RuleEnv,
+    self: RuleSelf,
+  ) => {
+    if (isStandaloneImageParagraph(tokens, idx)) {
+      return `<figure class="content-image">`;
+    }
+    if (defaultParagraphOpen) {
+      return defaultParagraphOpen(tokens, idx, options, env, self);
+    }
+    return self.renderToken(tokens, idx, options);
+  };
+  const paragraphCloseRule: ParagraphRule = (
+    tokens: RuleTokens,
+    idx: number,
+    options: RuleOptions,
+    env: RuleEnv,
+    self: RuleSelf,
+  ) => {
+    if (isStandaloneImageParagraph(tokens, idx - 2)) {
+      return `</figure>`;
+    }
+    if (defaultParagraphClose) {
+      return defaultParagraphClose(tokens, idx, options, env, self);
+    }
+    return self.renderToken(tokens, idx, options);
+  };
+  md.renderer.rules.paragraph_open = paragraphOpenRule;
+  md.renderer.rules.paragraph_close = paragraphCloseRule;
+
   const defaultLinkOpen = md.renderer.rules.link_open as LinkOpenRule | undefined;
   const linkOpenRule: LinkOpenRule = (
     tokens: RuleTokens,

package/src/runtime/app.css

@@ -67,6 +67,11 @@
   --content-heading-accent-soft: rgba(136, 57, 239, 0.32);
   --content-heading-subtle: var(--latte-subtext1);
   --content-visual-max-width: 720px;
+  --content-image-landscape-max-width: 720px;
+  --content-image-square-max-width: 640px;
+  --content-image-portrait-max-width: 560px;
+  --content-image-radius: 8px;
+  --content-image-frame-bg: linear-gradient(180deg, var(--latte-base), var(--latte-mantle));
   --mermaid-wide-max-width: 640px;
   --mermaid-tall-max-height: 560px;
   --desktop-sidebar-default: 420px;
@@ -1212,14 +1217,91 @@ body.mobile-toggle-left .mobile-menu-toggle {
 }
 
 /* Images */
+.viewer-content .content-image,
+.viewer-content .image-frame {
+  margin: 1.5rem auto;
+}
+
+.viewer-content .content-image {
+  width: fit-content;
+  max-width: min(100%, var(--content-image-landscape-max-width));
+}
+
+.viewer-content .content-image.is-square {
+  max-width: min(100%, var(--content-image-square-max-width));
+}
+
+.viewer-content .content-image.is-portrait {
+  max-width: min(100%, var(--content-image-portrait-max-width));
+}
+
 .viewer-content img {
   display: block;
   width: auto;
-  max-width: min(100%, var(--content-visual-max-width));
+  max-width: min(100%, var(--content-image-landscape-max-width));
   height: auto;
   margin: 0 auto;
-  border-radius: 8px;
+  border-radius: var(--content-image-radius);
+  border: 1px solid var(--latte-surface0);
+  background: var(--content-image-frame-bg);
+}
+
+.viewer-content img.is-square {
+  max-width: min(100%, var(--content-image-square-max-width));
+}
+
+.viewer-content img.is-portrait {
+  max-width: min(100%, var(--content-image-portrait-max-width));
+}
+
+.viewer-content .image-frame {
+  width: min(100%, var(--content-image-landscape-max-width));
+  overflow: hidden;
+  border-radius: 12px;
   border: 1px solid var(--latte-surface0);
+  background: var(--content-image-frame-bg);
+}
+
+.viewer-content .image-frame.is-square {
+  width: min(100%, var(--content-image-square-max-width));
+}
+
+.viewer-content .image-frame.is-portrait {
+  width: min(100%, var(--content-image-portrait-max-width));
+}
+
+.viewer-content .image-frame > img {
+  width: 100%;
+  max-width: none;
+  height: 100%;
+  margin: 0;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+}
+
+.viewer-content .image-frame.fit-cover > img {
+  object-fit: cover;
+}
+
+.viewer-content .image-frame.fit-contain > img {
+  object-fit: contain;
+}
+
+.viewer-content .image-frame.ratio-16x9 {
+  aspect-ratio: 16 / 9;
+}
+
+.viewer-content .image-frame.ratio-4x3 {
+  aspect-ratio: 4 / 3;
+}
+
+.viewer-content .image-frame.ratio-3x2 {
+  aspect-ratio: 3 / 2;
+}
+
+.viewer-content .image-frame.ratio-4x5 {
+  aspect-ratio: 4 / 5;
 }
 
 /* Horizontal rule */

package/src/runtime/app.js

@@ -26,6 +26,12 @@ const MERMAID_WIDE_RATIO = 2.4;
 const MERMAID_TALL_RATIO = 0.85;
 const MERMAID_BLOCK_WIDE_CLASS = "is-wide";
 const MERMAID_BLOCK_TALL_CLASS = "is-tall";
+const CONTENT_IMAGE_LANDSCAPE_CLASS = "is-landscape";
+const CONTENT_IMAGE_PORTRAIT_CLASS = "is-portrait";
+const CONTENT_IMAGE_SQUARE_CLASS = "is-square";
+const CONTENT_IMAGE_LANDSCAPE_THRESHOLD = 1.1;
+const CONTENT_IMAGE_PORTRAIT_THRESHOLD = 0.9;
+const contentImageDimensionCache = new Map();
 const mermaidRuntime = {
   initialized: false,
   loadingPromise: null,
@@ -156,6 +162,170 @@ function normalizeRenderedMermaidSvg(block) {
   }
 }
 
+function clearContentImageClasses(target) {
+  if (!(target instanceof Element)) {
+    return;
+  }
+
+  target.classList.remove(
+    CONTENT_IMAGE_LANDSCAPE_CLASS,
+    CONTENT_IMAGE_PORTRAIT_CLASS,
+    CONTENT_IMAGE_SQUARE_CLASS,
+  );
+}
+
+function syncContentImageClasses(image, className) {
+  if (!(image instanceof HTMLImageElement)) {
+    return;
+  }
+
+  clearContentImageClasses(image);
+  image.classList.add(className);
+
+  const figure = image.closest("figure");
+  if (
+    figure instanceof HTMLElement &&
+    (figure.classList.contains("content-image") || figure.classList.contains("image-frame"))
+  ) {
+    clearContentImageClasses(figure);
+    figure.classList.add(className);
+  }
+}
+
+function readIntrinsicImageDimensions(imageLike) {
+  if (!(imageLike instanceof HTMLImageElement)) {
+    return null;
+  }
+
+  const width =
+    imageLike.naturalWidth > 0
+      ? imageLike.naturalWidth
+      : Number.parseFloat(imageLike.getAttribute("width") ?? "");
+  const height =
+    imageLike.naturalHeight > 0
+      ? imageLike.naturalHeight
+      : Number.parseFloat(imageLike.getAttribute("height") ?? "");
+
+  if (!(width > 0) || !(height > 0)) {
+    return null;
+  }
+
+  return { width, height };
+}
+
+function classifyContentImageByDimensions(image, dimensions) {
+  if (!(image instanceof HTMLImageElement) || !dimensions) {
+    return;
+  }
+
+  const aspectRatio = dimensions.width / dimensions.height;
+  if (aspectRatio >= CONTENT_IMAGE_LANDSCAPE_THRESHOLD) {
+    syncContentImageClasses(image, CONTENT_IMAGE_LANDSCAPE_CLASS);
+    return;
+  }
+
+  if (aspectRatio <= CONTENT_IMAGE_PORTRAIT_THRESHOLD) {
+    syncContentImageClasses(image, CONTENT_IMAGE_PORTRAIT_CLASS);
+    return;
+  }
+
+  syncContentImageClasses(image, CONTENT_IMAGE_SQUARE_CLASS);
+}
+
+function resolveContentImageDimensions(image) {
+  const immediate = readIntrinsicImageDimensions(image);
+  if (immediate) {
+    return Promise.resolve(immediate);
+  }
+
+  const source = image.currentSrc || image.getAttribute("src") || "";
+  if (!source) {
+    return Promise.resolve(null);
+  }
+
+  const cached = contentImageDimensionCache.get(source);
+  if (cached) {
+    return cached;
+  }
+
+  const pending = new Promise((resolve) => {
+    const probe = new Image();
+    const finalize = () => {
+      resolve(readIntrinsicImageDimensions(probe));
+    };
+
+    probe.addEventListener("load", finalize, { once: true });
+    probe.addEventListener("error", () => resolve(null), { once: true });
+    probe.src = source;
+
+    if (probe.complete) {
+      if (typeof probe.decode === "function") {
+        probe.decode().then(finalize).catch(finalize);
+      } else {
+        finalize();
+      }
+    }
+  });
+
+  contentImageDimensionCache.set(source, pending);
+  return pending;
+}
+
+function prepareContentImage(image) {
+  if (!(image instanceof HTMLImageElement) || image.closest(".mermaid-block")) {
+    return;
+  }
+
+  const figure = image.closest("figure");
+  if (
+    figure instanceof HTMLElement &&
+    (figure.classList.contains("content-image") || figure.classList.contains("image-frame"))
+  ) {
+    clearContentImageClasses(figure);
+  }
+  clearContentImageClasses(image);
+
+  const handleLoad = () => {
+    resolveContentImageDimensions(image)
+      .then((dimensions) => {
+        if (!dimensions) {
+          handleError();
+          return;
+        }
+        classifyContentImageByDimensions(image, dimensions);
+      })
+      .catch(() => {
+        handleError();
+      });
+  };
+  const handleError = () => {
+    clearContentImageClasses(image);
+    if (
+      figure instanceof HTMLElement &&
+      (figure.classList.contains("content-image") || figure.classList.contains("image-frame"))
+    ) {
+      clearContentImageClasses(figure);
+    }
+  };
+
+  image.addEventListener("load", handleLoad, { once: true });
+  image.addEventListener("error", handleError, { once: true });
+
+  if (image.complete) {
+    handleLoad();
+  }
+}
+
+function enhanceContentImages(root) {
+  if (!(root instanceof HTMLElement)) {
+    return;
+  }
+
+  for (const image of root.querySelectorAll("img")) {
+    prepareContentImage(image);
+  }
+}
+
 function parseMermaidNodes() {
   const contentEl = document.getElementById("viewer-content");
   if (!(contentEl instanceof HTMLElement)) {
@@ -1769,6 +1939,7 @@ async function start() {
         metaEl.innerHTML = renderMeta(doc);
         updateBacklinks(doc);
         navEl.innerHTML = renderNav(view.docs, view.docIndexById, id, pathBase);
+        enhanceContentImages(contentEl);
         await renderMermaidBlocks(mermaidConfig);
         document.title = composeDocumentTitle(doc.title, siteTitle);
         if (viewerEl instanceof HTMLElement) {
@@ -1795,6 +1966,7 @@ async function start() {
 
       updateBacklinks(doc);
       navEl.innerHTML = renderNav(view.docs, view.docIndexById, id, pathBase);
+      enhanceContentImages(contentEl);
       await renderMermaidBlocks(mermaidConfig);
 
       document.title = composeDocumentTitle(doc.title, siteTitle);