fossbook 0.2.14 → 0.2.16

package/README.md

@@ -1,576 +1,755 @@
-# Fossbook
-
-A Markdown-based authoring and web-publishing tool for comics, illustrated
-stories, and articles. Fossbook extends familiar Markdown with comic panels,
-responsive layouts, image-linked dialogue, and reader-controlled transcripts,
-then generates a complete static site that can be published on GitHub Pages.
-
-Fossbook began as the publishing system for
-[F/OSS Comics](https://fosscomics.com). It is now an independent Node.js
-package for creators who want to keep words, artwork, translations, and site
-configuration in portable source files rather than a proprietary editor.
-
-![A cartoonist assembles colorful blocks into a larger structure, representing Fossbook's composable publishing workflow.](docs/images/fossbook-comic-authoring.png)
-
-_Artwork from [F/OSS Comics](https://fosscomics.com)._
-
-## Features
-
-- **Comic authoring in Markdown** — Combine artwork, captions, dialogue,
-  narration, and links in readable text files
-- **Panels and responsive layouts** — Arrange images or mixed-content comic
-  panels in grids that collapse for narrow screens
-- **Accessible transcripts** — Associate dialogue with artwork and let readers
-  show or hide transcript text while keeping it available for printing
-- **Image presentation controls** — Set image size, alignment, captions, panel
-  borders, dividers, backgrounds, and spacing with constrained Markdown syntax
-- **Multilingual publishing** — Keep translations beside the original work and
-  generate language-specific pages, navigation, and `hreflang` metadata
-- **Static web output** — Generate fast, portable HTML with pagination, tags,
-  SEO metadata, syntax highlighting, and Mermaid diagrams
-- **Creator-owned workflow** — Store Markdown and artwork in Git, preview
-  locally, customize themes, and deploy to GitHub Pages
-
-Fossbook also works as a conventional static blog generator. Its comic
-extensions build on GitHub Flavored Markdown instead of replacing it.
-
-## Quick Start
-
-### Install globally
-
-```bash
-npm install -g fossbook
-```
-
-### Create a new publication
-
-```bash
-mkdir my-blog && cd my-blog
-fossbook init
-```
-
-This creates a publication project with the following structure:
-
-```
-my-blog/
-├── content/
-│   ├── about.md
-│   └── posts/
-├── static/
-│   └── images/
-├── fossbook.config.js
-└── package.json
-```
-
-### Create a new work
-
-```bash
-fossbook new "My First Post"
-```
-
-This creates `content/posts/My First Post/index.md` with pre-filled front-matter
-and an `images/` directory for comic panels, illustrations, and other artwork.
-
-To create the default article and one or more configured translations together:
-
-```bash
-fossbook new "My First Post" --lang ko,ja
-```
-
-This also creates `index.ko.md` and `index.ja.md` in the same post directory. Running the command again preserves existing files and creates only missing translations.
-
-### Build the site
-
-```bash
-fossbook build
-```
-
-### Preview locally
-
-```bash
-fossbook serve
-```
-
-Open http://localhost:3000 to view your site.
-
-## Configuration
-
-Create a `fossbook.config.js` in your project root:
-
-```js
-module.exports = {
-  blogName: "My Blog",
-  authorName: "Your Name",
-  authorDescription: "A short bio",
-  authorWebsite: "https://example.com",
-  blogDescription: "A blog about things",
-  blogsite: "https://example.com",
-
-  // Optional
-  githubCNAME: "example.com",
-  googleAnalyticsID: "",
-  authorTwitter: "@you",
-  siteTwitter: "@yourblog",
-  githubRepository: "https://github.com/you/your-blog",
-  image: "https://example.com/default-image.png",
-  theme: "archie",
-
-  // Optional: URL prefix for posts. Defaults to "posts" -> /posts/<slug>/.
-  // Set to "" to serve posts at the site root, /<slug>/.
-  postsPath: "posts",
-
-  // Optional multilingual configuration
-  defaultLanguage: "en",
-  defaultLanguageInSubdir: false,
-  languages: {
-    en: { languageName: "English", locale: "en-US" },
-    ko: { languageName: "한국어", locale: "ko-KR" },
-  },
-
-  // Optional comments (see "Comments" below)
-  comments: {
-    provider: "utterances",
-    repo: "you/your-blog",
-    issueTerm: "pathname",
-    theme: "github-light",
-  },
-
-  // Directory overrides (defaults shown)
-  content: "./content",
-  postsDir: "./content/posts",
-  outputDir: "./public",
-  staticDir: "./static",
-  themesDir: "./themes",
-};
-```
-
-## Content Format
-
-Fossbook source remains readable Markdown. A work combines YAML front-matter,
-prose, and standard GitHub Flavored Markdown with optional publishing
-extensions for visual storytelling.
-
-### Authoring comics
-
-Keep each work and its artwork together. Standard Markdown images become comic
-panels; image titles can control captions, size, and alignment. A blockquote
-placed immediately after an image becomes its dialogue transcript:
-
-```markdown
-![Two programmers talking](images/panel-01.png "size:70% A late-night debugging session")
-
-> "Do you think anyone will notice?" \
-> "They always notice."
-```
-
-Use `:::panel` containers to frame artwork, dialogue, and narration as one
-scene. Use `:::panels` to compose responsive multi-column sequences:
-
-```markdown
-::::panels columns="2" label="Two scenes"
-:::panel
-![The first scene](images/scene-01.png)
-
-> Dialogue for the first scene.
-
-Narration following the first scene.
-:::
-
-:::panel divider="true"
-![The second scene](images/scene-02.png)
-
-> Dialogue for the second scene.
-
-Narration following the dialogue.
-:::
-::::
-```
-
-The bundled theme adapts panel groups and sized images for mobile screens. It
-also adds a transcript visibility control when a work contains image-linked
-dialogue. Alternative text, captions, group labels, and transcript text remain
-part of the authored source rather than being baked into the page layout.
-
-See [Fossbook Markdown](fossbook_markdown.md) for the complete syntax for
-panels, responsive groups, image presentation, dialogue, aligned links,
-Mermaid diagrams, and syntax-highlighted code.
-
-### Post front-matter
-
-```markdown
----
-title: My Post Title
-date: 2026-02-17
-description: "A brief summary of the post"
-image: "feature.png"
-tags: "JavaScript, Node.js, Static Site"
----
-
-Your Markdown content here...
-```
-
-### Directory structure
-
-```
-content/posts/My Post Title/
-├── index.md
-└── images/
-    └── feature.png
-```
-
-### Post URLs
-
-By default, posts are served under `/posts/`, e.g. `/posts/my-post-title/`. To
-change the prefix or move posts to the site root, set `postsPath` in
-`fossbook.config.js`:
-
-```js
-postsPath: "",          // serves the post above at /my-post-title/ (site root)
-// postsPath: "blog",   // or use a different prefix: /blog/my-post-title/
-```
-
-This affects the generated output directory, the post URL, post links on the
-home/all-posts/tag pages, and image paths. The on-disk source layout under
-`content/posts/` does not change.
-
-## Multilingual Sites
-
-Fossbook generates a separate static page for each available language. The
-browser loads only the selected language page; changing languages follows a
-normal link and does not require JavaScript.
-
-When a reader uses the language switcher, Fossbook remembers that choice in
-the browser. A later visit to the default-language homepage redirects to the
-remembered language's homepage. Direct links to posts and other pages are
-never redirected, and language links continue to work when browser storage is
-unavailable.
-
-### Configuration
-
-Add the languages supported by the site to `fossbook.config.js`:
-
-```js
-module.exports = {
-  defaultLanguage: "en",
-  defaultLanguageInSubdir: false,
-  languages: {
-    en: {
-      languageName: "English",
-      locale: "en-US",
-    },
-    ko: {
-      languageName: "한국어",
-      locale: "ko-KR",
-    },
-    ja: {
-      languageName: "日本語",
-      locale: "ja-JP",
-    },
-  },
-};
-```
-
-Put localized blog information in a sibling config file for each language. For
-example, `fossbook.config.en.js` contains:
-
-```js
-module.exports = {
-  blogName: "My Blog",
-  authorName: "Jane Doe",
-  authorDescription: "Open source developer and writer",
-  blogDescription: "An English-language blog",
-};
-```
-
-And `fossbook.config.ko.js` contains:
-
-```js
-module.exports = {
-  blogName: "나의 블로그",
-  authorName: "이수현",
-  authorDescription: "오픈 소스 개발자이자 작가",
-  blogDescription: "한국어 블로그",
-  homeLabel: "처음",
-  allPostsLabel: "모든 글",
-  aboutLabel: "이곳은",
-  tagsLabel: "태그",
-  allTagsLabel: "모든 태그",
-  postedOnLabel: "올린 날:",
-  readMoreLabel: "더 읽기",
-  previousPageLabel: "앞으로",
-  nextPageLabel: "뒤로",
-  transcriptLabel: "말글 보이기",
-  copyLinkLabel: "링크 복사",
-  linkCopiedLabel: "링크를 복사했습니다",
-  copyLinkErrorLabel: "링크를 복사하지 못했습니다",
-};
-```
-
-- `defaultLanguage` identifies the language represented by `index.md` and
-  `about.md`.
-- `defaultLanguageInSubdir: false` keeps the default language at the site root.
-  Other languages are generated below their language code, such as `/ko/`.
-- Set `defaultLanguageInSubdir: true` to generate the default language below
-  its code as well, such as `/en/`.
-- Language config files use the main config filename with the language code
-  inserted before the extension: `fossbook.config.<language>.js`.
-- Values omitted from a language config fall back to `fossbook.config.js`.
-- `locale` controls language-specific date formatting.
-- Language keys should use standard language tags such as `en`, `ko`, `ja`, or
-  `zh-Hant`.
-
-If `languages` is omitted, Fossbook keeps its existing single-language
-behavior and URLs.
-
-### Create translated posts
-
-Create only the default-language article:
-
-```bash
-fossbook new "Charles Babbage and Ada Lovelace"
-```
-
-Create the default article and multiple translations together:
-
-```bash
-fossbook new "Charles Babbage and Ada Lovelace" --lang ko,ja
-```
-
-The languages passed to `--lang` must be present in the `languages`
-configuration. The command always ensures that the default `index.md` exists,
-then creates the requested translation files. Existing Markdown files and
-images are never overwritten, so the command can be run later to add another
-translation:
-
-```bash
-fossbook new "Charles Babbage and Ada Lovelace" --lang ja
-```
-
-### Source structure
-
-Translations live in the same post bundle and share its `images/` directory:
-
-```text
-content/
-├── about.md
-├── about.ko.md
-└── posts/
-    └── Charles Babbage and Ada Lovelace/
-        ├── index.md
-        ├── index.ko.md
-        ├── index.ja.md
-        └── images/
-            └── feature.png
-```
-
-- `index.md` is the default-language article.
-- `index.<language>.md` is a translated article.
-- `about.md` is the default About page.
-- `about.<language>.md` is a translated About page.
-- A translation is generated only when its Markdown source exists. Fossbook
-  does not substitute default-language content for a missing translation.
-
-### Generated output
-
-With `defaultLanguage: "en"` and `defaultLanguageInSubdir: false`, the example
-above generates:
-
-```text
-public/
-├── index.html
-├── about/index.html
-├── posts/Charles Babbage and Ada Lovelace/index.html
-├── ko/
-│   ├── index.html
-│   ├── about/index.html
-│   └── posts/Charles Babbage and Ada Lovelace/index.html
-└── ja/
-    ├── index.html
-    └── posts/Charles Babbage and Ada Lovelace/index.html
-```
-
-Translated article and About pages display ISO language links such as `EN`,
-`KO`, and `JA`. Only translations that exist are shown. These pages also emit
-canonical URLs and `hreflang` alternate links for search engines.
-
-### Mermaid diagrams
-
-Fenced code blocks tagged `mermaid` are rendered as diagrams instead of code.
-The [Mermaid](https://mermaid.js.org) script is loaded from a CDN only on pages
-that contain a diagram.
-
-````markdown
-```mermaid
-sequenceDiagram
-    Alice->>Bob: Hello Bob
-    Bob-->>Alice: Hi Alice
-```
-````
-
-## CLI Reference
-
-```
-Usage: fossbook <command> [options]
-
-Commands:
-  build          Build the static site
-  serve          Build and start a local dev server
-  new <title>    Create a new post
-  init           Create a new fossbook site project
-
-Options:
-  -c, --config   Path to config file (default: ./fossbook.config.js)
-  -o, --output   Output directory (default: ./public)
-  -p, --port     Dev server port (default: 3000)
-  --lang         (new) Comma-separated translation languages, e.g. ko,ja
-  -v, --version  Show version number
-  -h, --help     Show help
-```
-
-## Theming
-
-Fossbook ships with the Archie theme by default. To use a custom theme:
-
-1. Create a `themes/<your-theme>/` directory in your project
-2. Add `layouts/` (HTML templates) and `assets/` (CSS, fonts, images)
-3. Set `theme: "your-theme"` in `fossbook.config.js`
-
-Theme resolution order: user project `themes/` → built-in `themes/`.
-
-## Comments
-
-Fossbook supports [utterances](https://utteranc.es) — a commenting widget that
-stores comments as GitHub issues. When enabled, a comment box is rendered at the
-bottom of every post page.
-
-### Setup
-
-1. Make the repository that backs the comments **public**.
-2. Install the [utterances GitHub App](https://github.com/apps/utterances) on
-   that repository so the bot can create issues.
-3. Add a `comments` block to `fossbook.config.js`:
-
-```js
-comments: {
-  provider: "utterances",        // currently the only supported provider
-  repo: "you/your-blog",         // owner/repo that stores the comment issues
-  issueTerm: "pathname",         // how a post maps to an issue (see below)
-  theme: "github-light",         // any utterances theme, e.g. "github-dark"
-},
-```
-
-Omit the `comments` block (or set it to `null`) to disable comments.
-
-### Options
-
-| Field       | Required | Default          | Description                                                                   |
-| ----------- | -------- | ---------------- | ----------------------------------------------------------------------------- |
-| `provider`  | yes      | —                | Must be `"utterances"`.                                                       |
-| `repo`      | yes      | —                | `owner/repo` whose issues store the comments.                                 |
-| `issueTerm` | no       | `"pathname"`     | Mapping between a page and its issue: `pathname`, `url`, `title`, `og:title`. |
-| `theme`     | no       | `"github-light"` | Any [utterances theme](https://utteranc.es/#configuration).                   |
-
-### Mapping notes
-
-With `issueTerm: "pathname"`, each post is matched to a GitHub issue whose title
-equals the page's pathname (with the leading slash stripped). If you change a
-post's URL, the existing comment thread no longer matches — rename the issue
-title to the new pathname to keep the old comments.
-
-### Required layout files
-
-```
-layouts/
-├── home.html        # Home page with pagination
-├── post.html        # Individual post page
-├── page.html        # Static pages (e.g., about)
-├── all_posts.html   # All posts listing
-├── tag.html         # Per-tag listing
-├── tag_list.html    # Tag index page
-└── partials/
-    └── footer.html  # Footer partial
-```
-
-## Deploying to GitHub Pages
-
-Fossbook can automatically deploy your blog to GitHub Pages using GitHub Actions.
-
-### Prerequisites: Install GitHub CLI (`gh`)
-
-The `fossbook deploy` command uses the GitHub CLI to create repositories and monitor deployments.
-
-**Linux (Debian/Ubuntu):**
-
-```bash
-sudo apt install gh
-```
-
-**macOS:**
-
-```bash
-brew install gh
-```
-
-**Windows:**
-
-```bash
-winget install GitHub.cli
-```
-
-Then authenticate with your GitHub account:
-
-```bash
-gh auth login
-```
-
-Follow the prompts to log in via browser or token.
-
-### Initialize with GitHub
-
-```bash
-mkdir my-blog && cd my-blog
-fossbook init --github
-```
-
-This will:
-
-1. Scaffold the site project (config, content directories)
-2. Create a GitHub repository for your blog
-3. Generate `.github/workflows/deploy.yml` for automatic deployments
-4. Push the initial commit to GitHub
-
-### Publish a post
-
-```bash
-fossbook new "My New Article"
-# ... edit content/posts/My New Article/index.md ...
-fossbook deploy
-```
-
-Fossbook will build the site, commit, push to GitHub, wait for the CI/CD pipeline to finish, and display the live URL:
-
-```
-Building site... done.
-Committing: "Publish: My New Article"
-Pushing to origin/main...
-Waiting for GitHub Pages deployment... ✓
-
-✅ Published! View your article at:
-   https://username.github.io/my-blog/My%20New%20Article/
-```
-
-**Deploy options:**
-
-```bash
-fossbook deploy --message "Update homepage"   # Custom commit message
-fossbook deploy --no-wait                     # Push without waiting for CI
-```
-
-## License
-
-- Generator code: [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
-- Archie theme: [MIT License](https://github.com/athul/archie?tab=MIT-1-ov-file#readme)
-
-## Credits
-
-Adapted from [kartiknair's blog](https://github.com/kartiknair/blog) and styled using the [Archie theme](https://github.com/athul/archie).
+# Fossbook
+
+A Markdown-based authoring and web-publishing tool for comics, illustrated
+stories, and articles. Fossbook extends familiar Markdown with comic panels,
+responsive layouts, image-linked dialogue, and reader-controlled transcripts,
+then generates a complete static site that can be published on GitHub Pages.
+
+Fossbook began as the publishing system for
+[F/OSS Comics](https://fosscomics.com). It is now an independent Node.js
+package for creators who want to keep words, artwork, translations, and site
+configuration in portable source files rather than a proprietary editor.
+
+![A cartoonist assembles colorful blocks into a larger structure, representing Fossbook's composable publishing workflow.](docs/images/fossbook-comic-authoring.png)
+
+_Artwork from [F/OSS Comics](https://fosscomics.com)._
+
+## Features
+
+- **Comic authoring in Markdown** — Combine artwork, captions, dialogue,
+  narration, and links in readable text files
+- **Panels and responsive layouts** — Arrange images or mixed-content comic
+  panels in grids that collapse for narrow screens
+- **Accessible transcripts** — Associate dialogue with artwork and let readers
+  show or hide transcript text while keeping it available for printing
+- **Image presentation controls** — Set image size, alignment, captions, panel
+  borders, dividers, backgrounds, and spacing with constrained Markdown syntax
+- **Multilingual publishing** — Keep translations beside the original work and
+  generate language-specific pages, navigation, and `hreflang` metadata
+- **Static web output** — Generate fast, portable HTML with pagination, tags,
+  SEO metadata, syntax highlighting, and Mermaid diagrams
+- **Creator-owned workflow** — Store Markdown and artwork in Git, preview
+  locally, customize themes, and deploy to GitHub Pages
+
+Fossbook also works as a conventional static blog generator. Its comic
+extensions build on GitHub Flavored Markdown instead of replacing it.
+
+## Quick Start
+
+### Install globally
+
+```bash
+npm install -g fossbook
+```
+
+### Create a new publication
+
+```bash
+mkdir my-blog && cd my-blog
+fossbook init
+```
+
+This creates a publication project with the following structure:
+
+```
+my-blog/
+├── content/
+│   ├── about.md
+│   └── posts/
+├── static/
+│   └── images/
+├── fossbook.config.js
+└── package.json
+```
+
+### Create a new work
+
+```bash
+fossbook new "My First Post"
+```
+
+This creates `content/posts/My First Post/index.md` with pre-filled front-matter
+and an `images/` directory for comic panels, illustrations, and other artwork.
+
+To create the default article and one or more configured translations together:
+
+```bash
+fossbook new "My First Post" --lang ko,ja
+```
+
+This also creates `index.ko.md` and `index.ja.md` in the same post directory. Running the command again preserves existing files and creates only missing translations.
+
+### Build the site
+
+```bash
+fossbook build
+```
+
+Posts with `draft: true` in their front matter are excluded from generated
+post pages, home pages, archives, and tags. To include them in a local build:
+
+```bash
+fossbook build --include-drafts
+```
+
+### Preview locally
+
+```bash
+fossbook serve --include-drafts
+```
+
+Open http://localhost:3000 to view your site.
+
+## Configuration
+
+Create a `fossbook.config.js` in your project root:
+
+```js
+module.exports = {
+  blogName: "My Blog",
+  authorName: "Your Name",
+  authorDescription: "A short bio",
+  authorWebsite: "https://example.com",
+  blogDescription: "A blog about things",
+  blogsite: "https://example.com",
+
+  // Optional
+  githubCNAME: "example.com",
+  googleAnalyticsID: "",
+  authorTwitter: "@you",
+  siteTwitter: "@yourblog",
+  githubRepository: "https://github.com/you/your-blog",
+  image: "https://example.com/default-image.png",
+  theme: "archie",
+
+  // PNG publishing optimization (defaults shown)
+  imageOptimization: true,
+  imageMaxWidth: 1400,
+  imageMaxWidthOverride: 1200,
+  imageWebP: true,
+  imageResponsiveWidths: [600, 800, 1000],
+  cacheDir: "./.fossbook-cache",
+
+  // Optional: URL prefix for posts. Defaults to "posts" -> /posts/<slug>/.
+  // Set to "" to serve posts at the site root, /<slug>/.
+  postsPath: "posts",
+
+  // Optional multilingual configuration
+  defaultLanguage: "en",
+  defaultLanguageInSubdir: false,
+  languages: {
+    en: { languageName: "English", locale: "en-US" },
+    ko: { languageName: "한국어", locale: "ko-KR" },
+  },
+
+  // Optional comments (see "Comments" below)
+  comments: {
+    provider: "utterances",
+    repo: "you/your-blog",
+    issueTerm: "pathname",
+    theme: "github-light",
+  },
+
+  // Directory overrides (defaults shown)
+  content: "./content",
+  postsDir: "./content/posts",
+  outputDir: "./public",
+  staticDir: "./static",
+  themesDir: "./themes",
+};
+```
+
+During a build, Fossbook resizes PNGs from post and static image directories to
+`imageMaxWidth` while preserving their aspect ratio. Source images are never
+changed, images are never enlarged or cropped, and images already within the
+limit retain their original published bytes when lossless optimization would
+increase the file size. Processed images are cached by source content and
+settings in `cacheDir`, so unchanged images do not need to be processed again
+after `public` is rebuilt. Set `imageOptimization` to `false` to copy PNGs
+unchanged.
+
+The default cache is `.fossbook-cache/images/`, separate from both source
+artwork and `public/`. Each entry is keyed by the source bytes, transformation
+settings, Fossbook cache schema, and Sharp/libvips encoder versions. Fossbook
+validates cached image format and dimensions before use, regenerates missing or
+corrupt entries atomically, and prints cache hits, misses, and regenerated image
+counts at the end of each build. It also writes
+`.fossbook-cache/image-cache-status.json` for CI save decisions.
+
+New projects ignore `.fossbook-cache/` automatically. Existing sites should add
+this rule to `.gitignore`:
+
+```gitignore
+.fossbook-cache/
+```
+
+For post images, Fossbook also generates lossless WebP copies at the configured
+responsive widths. Generated HTML uses WebP when supported and retains the PNG
+as a fallback. Candidate widths larger than the source or publication limit are
+skipped, and duplicate widths produce only one file. Set `imageWebP` to `false`
+to publish only PNG copies.
+
+For small lettering or detailed diagrams, add `publish-width:1200` to the
+existing Markdown image title. Overrides are capped by
+`imageMaxWidthOverride`:
+
+```markdown
+![Detailed diagram](images/diagram.png "publish-width:1200 Detailed diagram")
+```
+
+### GitHub Actions image cache
+
+`fossbook init` generates a deployment workflow with the image cache
+configuration below. Existing consumer sites can use this complete workflow.
+The resolve step reads the site's effective Fossbook configuration, so custom
+`cacheDir`, `postsDir`, `staticDir`, and theme paths are handled automatically.
+With the defaults, the exact archived path is `.fossbook-cache/images`.
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Resolve Fossbook image cache
+        id: image-cache-config
+        run: node -e "require('fossbook/lib/mod/github_cache').writeGitHubCacheOutputs()"
+
+      - name: Restore Fossbook image cache
+        id: image-cache-restore
+        uses: actions/cache/restore@v4
+        continue-on-error: true
+        with:
+          path: ${{ steps.image-cache-config.outputs.cache-path }}/images
+          key: ${{ runner.os }}-${{ runner.arch }}-fossbook-images-v4-${{ steps.image-cache-config.outputs.input-hash }}-${{ github.run_id }}-${{ github.run_attempt }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-fossbook-images-v4-${{ steps.image-cache-config.outputs.input-hash }}-
+            ${{ runner.os }}-${{ runner.arch }}-fossbook-images-v4-
+
+      - name: Build site
+        run: npx fossbook build
+
+      - name: Read Fossbook image cache status
+        id: image-cache-status
+        continue-on-error: true
+        shell: bash
+        env:
+          FOSSBOOK_CACHE_STATUS: ${{ steps.image-cache-config.outputs.status-path }}
+        run: |
+          node -e "const fs=require('fs');let writes=0;try{writes=JSON.parse(fs.readFileSync(process.env.FOSSBOOK_CACHE_STATUS,'utf8')).writes||0}catch(error){console.warn(error.message)}fs.appendFileSync(process.env.GITHUB_OUTPUT, 'new-entries='+(writes>0)+'\n')"
+
+      - name: Save Fossbook image cache
+        if: ${{ steps.image-cache-restore.outputs.cache-hit != 'true' && steps.image-cache-status.outputs.new-entries == 'true' }}
+        uses: actions/cache/save@v4
+        continue-on-error: true
+        with:
+          path: ${{ steps.image-cache-config.outputs.cache-path }}/images
+          key: ${{ runner.os }}-${{ runner.arch }}-fossbook-images-v4-${{ steps.image-cache-config.outputs.input-hash }}-${{ github.run_id }}-${{ github.run_attempt }}
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+        with:
+          enablement: true
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "./public"
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+GitHub cache archives are immutable. The resolve helper computes an input hash
+from dependencies, effective image settings, Markdown image metadata, source
+artwork, and custom theme PNGs. The save key adds the unique workflow run and
+attempt, while restore first searches the matching input-hash prefix and then
+the broader OS/architecture/schema prefix. This lets a regenerated corrupt
+entry be saved as a newer archive instead of repeatedly selecting an immutable
+damaged archive. Fossbook's per-image keys remain authoritative, so changing
+one image or one output setting regenerates only affected results. Markdown
+prose is excluded from the input hash and does not create redundant archives.
+
+An exact cache hit is never saved again. A partial or cold restore is saved only
+when Fossbook reports newly generated entries. Cache restore, status, and save
+steps use `continue-on-error`, so expiration, eviction, quota failures, and
+service outages fall back to a normal cold build. To reset manually, delete the
+repository cache in GitHub's Actions cache settings or increment
+`fossbook-images-v4` in both key locations; the next build recreates it.
+
+The example runs only for trusted pushes. GitHub may allow pull requests and
+forks to read caches accessible from their base branch. Because processed
+artwork can still disclose source content, do not enable these cache steps in
+untrusted workflows when the artwork is private. Do not use
+`pull_request_target` for publication builds. Only
+`.fossbook-cache/images` is archived, so source PDFs, secrets, `public/`, and
+unrelated build files are excluded.
+
+Fossbook's own [CI workflow](./.github/workflows/build.yml) tests the generator
+and cache behavior; it is distinct from this consumer-site publication
+workflow and does not archive production artwork.
+
+## Content Format
+
+Fossbook source remains readable Markdown. A work combines YAML front-matter,
+prose, and standard GitHub Flavored Markdown with optional publishing
+extensions for visual storytelling.
+
+### Authoring comics
+
+Keep each work and its artwork together. Standard Markdown images become comic
+panels; image titles can control captions, size, and alignment. A blockquote
+placed immediately after an image becomes its dialogue transcript:
+
+```markdown
+![Two programmers talking](images/panel-01.png "size:70% A late-night debugging session")
+
+> "Do you think anyone will notice?" \
+> "They always notice."
+```
+
+Use `:::panel` containers to frame artwork, dialogue, and narration as one
+scene. Use `:::panels` to compose responsive multi-column sequences:
+
+```markdown
+::::panels columns="2" label="Two scenes"
+:::panel
+![The first scene](images/scene-01.png)
+
+> Dialogue for the first scene.
+
+Narration following the first scene.
+:::
+
+:::panel divider="true"
+![The second scene](images/scene-02.png)
+
+> Dialogue for the second scene.
+
+Narration following the dialogue.
+:::
+::::
+```
+
+The bundled theme adapts panel groups and sized images for mobile screens. It
+also adds a transcript visibility control when a work contains image-linked
+dialogue. Alternative text, captions, group labels, and transcript text remain
+part of the authored source rather than being baked into the page layout.
+
+See [Fossbook Markdown](fossbook_markdown.md) for the complete syntax for
+panels, responsive groups, image presentation, dialogue, aligned links,
+Mermaid diagrams, and syntax-highlighted code.
+
+### Post front-matter
+
+```markdown
+---
+title: My Post Title
+date: 2026-02-17
+description: "A brief summary of the post"
+image: "feature.png"
+tags: "JavaScript, Node.js, Static Site"
+draft: false
+---
+
+Your Markdown content here...
+```
+
+Set `draft: true` while a post is in progress. Normal builds and deployments
+exclude it. Use `fossbook serve --include-drafts` to preview drafts locally,
+then remove the field or set it to `false` before publishing.
+
+### Directory structure
+
+```
+content/posts/My Post Title/
+├── index.md
+└── images/
+    └── feature.png
+```
+
+### Post URLs
+
+By default, posts are served under `/posts/`, e.g. `/posts/my-post-title/`. To
+change the prefix or move posts to the site root, set `postsPath` in
+`fossbook.config.js`:
+
+```js
+postsPath: "",          // serves the post above at /my-post-title/ (site root)
+// postsPath: "blog",   // or use a different prefix: /blog/my-post-title/
+```
+
+This affects the generated output directory, the post URL, post links on the
+home/all-posts/tag pages, and image paths. The on-disk source layout under
+`content/posts/` does not change.
+
+## Multilingual Sites
+
+Fossbook generates a separate static page for each available language. The
+browser loads only the selected language page; changing languages follows a
+normal link and does not require JavaScript.
+
+When a reader uses the language switcher, Fossbook remembers that choice in
+the browser. A later visit to the default-language homepage redirects to the
+remembered language's homepage. Direct links to posts and other pages are
+never redirected, and language links continue to work when browser storage is
+unavailable.
+
+### Configuration
+
+Add the languages supported by the site to `fossbook.config.js`:
+
+```js
+module.exports = {
+  defaultLanguage: "en",
+  defaultLanguageInSubdir: false,
+  languages: {
+    en: {
+      languageName: "English",
+      locale: "en-US",
+    },
+    ko: {
+      languageName: "한국어",
+      locale: "ko-KR",
+    },
+    ja: {
+      languageName: "日本語",
+      locale: "ja-JP",
+    },
+  },
+};
+```
+
+Put localized blog information in a sibling config file for each language. For
+example, `fossbook.config.en.js` contains:
+
+```js
+module.exports = {
+  blogName: "My Blog",
+  authorName: "Jane Doe",
+  authorDescription: "Open source developer and writer",
+  blogDescription: "An English-language blog",
+};
+```
+
+And `fossbook.config.ko.js` contains:
+
+```js
+module.exports = {
+  blogName: "나의 블로그",
+  authorName: "이수현",
+  authorDescription: "오픈 소스 개발자이자 작가",
+  blogDescription: "한국어 블로그",
+  homeLabel: "처음",
+  allPostsLabel: "모든 글",
+  aboutLabel: "이곳은",
+  tagsLabel: "태그",
+  allTagsLabel: "모든 태그",
+  postedOnLabel: "올린 날:",
+  readMoreLabel: "더 읽기",
+  previousPageLabel: "앞으로",
+  nextPageLabel: "뒤로",
+  transcriptLabel: "말글 보이기",
+  copyLinkLabel: "링크 복사",
+  linkCopiedLabel: "링크를 복사했습니다",
+  copyLinkErrorLabel: "링크를 복사하지 못했습니다",
+};
+```
+
+- `defaultLanguage` identifies the language represented by `index.md` and
+  `about.md`.
+- `defaultLanguageInSubdir: false` keeps the default language at the site root.
+  Other languages are generated below their language code, such as `/ko/`.
+- Set `defaultLanguageInSubdir: true` to generate the default language below
+  its code as well, such as `/en/`.
+- Language config files use the main config filename with the language code
+  inserted before the extension: `fossbook.config.<language>.js`.
+- Values omitted from a language config fall back to `fossbook.config.js`.
+- `locale` controls language-specific date formatting.
+- Language keys should use standard language tags such as `en`, `ko`, `ja`, or
+  `zh-Hant`.
+
+If `languages` is omitted, Fossbook keeps its existing single-language
+behavior and URLs.
+
+### Create translated posts
+
+Create only the default-language article:
+
+```bash
+fossbook new "Charles Babbage and Ada Lovelace"
+```
+
+Create the default article and multiple translations together:
+
+```bash
+fossbook new "Charles Babbage and Ada Lovelace" --lang ko,ja
+```
+
+The languages passed to `--lang` must be present in the `languages`
+configuration. The command always ensures that the default `index.md` exists,
+then creates the requested translation files. Existing Markdown files and
+images are never overwritten, so the command can be run later to add another
+translation:
+
+```bash
+fossbook new "Charles Babbage and Ada Lovelace" --lang ja
+```
+
+### Source structure
+
+Translations live in the same post bundle and share its `images/` directory:
+
+```text
+content/
+├── about.md
+├── about.ko.md
+└── posts/
+    └── Charles Babbage and Ada Lovelace/
+        ├── index.md
+        ├── index.ko.md
+        ├── index.ja.md
+        └── images/
+            └── feature.png
+```
+
+- `index.md` is the default-language article.
+- `index.<language>.md` is a translated article.
+- `about.md` is the default About page.
+- `about.<language>.md` is a translated About page.
+- A translation is generated only when its Markdown source exists. Fossbook
+  does not substitute default-language content for a missing translation.
+
+### Generated output
+
+With `defaultLanguage: "en"` and `defaultLanguageInSubdir: false`, the example
+above generates:
+
+```text
+public/
+├── index.html
+├── about/index.html
+├── posts/Charles Babbage and Ada Lovelace/index.html
+├── ko/
+│   ├── index.html
+│   ├── about/index.html
+│   └── posts/Charles Babbage and Ada Lovelace/index.html
+└── ja/
+    ├── index.html
+    └── posts/Charles Babbage and Ada Lovelace/index.html
+```
+
+Translated article and About pages display ISO language links such as `EN`,
+`KO`, and `JA`. Only translations that exist are shown. These pages also emit
+canonical URLs and `hreflang` alternate links for search engines.
+
+### Mermaid diagrams
+
+Fenced code blocks tagged `mermaid` are rendered as diagrams instead of code.
+The [Mermaid](https://mermaid.js.org) script is loaded from a CDN only on pages
+that contain a diagram.
+
+````markdown
+```mermaid
+sequenceDiagram
+    Alice->>Bob: Hello Bob
+    Bob-->>Alice: Hi Alice
+```
+````
+
+## CLI Reference
+
+```
+Usage: fossbook <command> [options]
+
+Commands:
+  build          Build the static site
+  serve          Build and start a local dev server
+  new <title>    Create a new post
+  init           Create a new fossbook site project
+
+Options:
+  -c, --config   Path to config file (default: ./fossbook.config.js)
+  -o, --output   Output directory (default: ./public)
+  -p, --port     Dev server port (default: 3000)
+  --lang         (new) Comma-separated translation languages, e.g. ko,ja
+  -v, --version  Show version number
+  -h, --help     Show help
+```
+
+## Theming
+
+Fossbook ships with the Archie theme by default. To use a custom theme:
+
+1. Create a `themes/<your-theme>/` directory in your project
+2. Add `layouts/` (HTML templates) and `assets/` (CSS, fonts, images)
+3. Set `theme: "your-theme"` in `fossbook.config.js`
+
+Theme resolution order: user project `themes/` → built-in `themes/`.
+
+## Comments
+
+Fossbook supports [utterances](https://utteranc.es) — a commenting widget that
+stores comments as GitHub issues. When enabled, a comment box is rendered at the
+bottom of every post page.
+
+### Setup
+
+1. Make the repository that backs the comments **public**.
+2. Install the [utterances GitHub App](https://github.com/apps/utterances) on
+   that repository so the bot can create issues.
+3. Add a `comments` block to `fossbook.config.js`:
+
+```js
+comments: {
+  provider: "utterances",        // currently the only supported provider
+  repo: "you/your-blog",         // owner/repo that stores the comment issues
+  issueTerm: "pathname",         // how a post maps to an issue (see below)
+  theme: "github-light",         // any utterances theme, e.g. "github-dark"
+},
+```
+
+Omit the `comments` block (or set it to `null`) to disable comments.
+
+### Options
+
+| Field       | Required | Default          | Description                                                                   |
+| ----------- | -------- | ---------------- | ----------------------------------------------------------------------------- |
+| `provider`  | yes      | —                | Must be `"utterances"`.                                                       |
+| `repo`      | yes      | —                | `owner/repo` whose issues store the comments.                                 |
+| `issueTerm` | no       | `"pathname"`     | Mapping between a page and its issue: `pathname`, `url`, `title`, `og:title`. |
+| `theme`     | no       | `"github-light"` | Any [utterances theme](https://utteranc.es/#configuration).                   |
+
+### Mapping notes
+
+With `issueTerm: "pathname"`, each post is matched to a GitHub issue whose title
+equals the page's pathname (with the leading slash stripped). If you change a
+post's URL, the existing comment thread no longer matches — rename the issue
+title to the new pathname to keep the old comments.
+
+### Required layout files
+
+```
+layouts/
+├── home.html        # Home page with pagination
+├── post.html        # Individual post page
+├── page.html        # Static pages (e.g., about)
+├── all_posts.html   # All posts listing
+├── tag.html         # Per-tag listing
+├── tag_list.html    # Tag index page
+└── partials/
+    └── footer.html  # Footer partial
+```
+
+## Deploying to GitHub Pages
+
+Fossbook can automatically deploy your blog to GitHub Pages using GitHub Actions.
+
+### Prerequisites: Install GitHub CLI (`gh`)
+
+The `fossbook deploy` command uses the GitHub CLI to create repositories and monitor deployments.
+
+**Linux (Debian/Ubuntu):**
+
+```bash
+sudo apt install gh
+```
+
+**macOS:**
+
+```bash
+brew install gh
+```
+
+**Windows:**
+
+```bash
+winget install GitHub.cli
+```
+
+Then authenticate with your GitHub account:
+
+```bash
+gh auth login
+```
+
+Follow the prompts to log in via browser or token.
+
+### Initialize with GitHub
+
+```bash
+mkdir my-blog && cd my-blog
+fossbook init --github
+```
+
+This will:
+
+1. Scaffold the site project (config, content directories)
+2. Create a GitHub repository for your blog
+3. Generate `.github/workflows/deploy.yml` for automatic deployments
+4. Push the initial commit to GitHub
+
+### Publish a post
+
+```bash
+fossbook new "My New Article"
+# ... edit content/posts/My New Article/index.md ...
+fossbook deploy
+```
+
+Fossbook will build the site, commit, push to GitHub, wait for the CI/CD pipeline to finish, and display the live URL:
+
+```
+Building site... done.
+Committing: "Publish: My New Article"
+Pushing to origin/main...
+Waiting for GitHub Pages deployment... ✓
+
+✅ Published! View your article at:
+   https://username.github.io/my-blog/My%20New%20Article/
+```
+
+**Deploy options:**
+
+```bash
+fossbook deploy --message "Update homepage"   # Custom commit message
+fossbook deploy --no-wait                     # Push without waiting for CI
+```
+
+## License
+
+- Generator code: [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
+- Archie theme: [MIT License](https://github.com/athul/archie?tab=MIT-1-ov-file#readme)
+
+## Credits
+
+Adapted from [kartiknair's blog](https://github.com/kartiknair/blog) and styled using the [Archie theme](https://github.com/athul/archie).