fossbook 0.2.11 → 0.2.13

package/README.md

@@ -1,509 +1,573 @@
-# Fossbook
-
-A lightweight static blog site generator for GitHub Pages, similar to Hugo but built with Node.js.
-It was originally part of the [F/OSS Comics blog](https://fosscomics.com) and is now an independent, installable package that anyone can use.
-
-## Features
-
-- **Markdown-based** — Write posts in Markdown with YAML front-matter
-- **Pagination** — Automatic home page pagination
-- **Tags** — Tag-based categorization with tag index and per-tag listing pages
-- **Theming** — Bundled Archie theme with support for custom themes
-- **SEO** — Open Graph and Twitter Card meta tags out of the box
-- **Multilingual sites** — Generate language-specific pages with translation links and `hreflang` metadata
-- **GitHub Pages** — Built-in CNAME support for custom domains
-- **Dev server** — Local preview server with Express
-- **Syntax highlighting** — Code block highlighting via highlight.js
-- **Mermaid diagrams** — ` ```mermaid ` code blocks render as diagrams
-
-## Quick Start
-
-### Install globally
-
-```bash
-npm install -g fossbook
-```
-
-### Create a new site
-
-```bash
-mkdir my-blog && cd my-blog
-fossbook init
-```
-
-This creates the following structure:
-
-```
-my-blog/
-├── content/
-│   ├── about.md
-│   └── posts/
-├── static/
-│   └── images/
-├── fossbook.config.js
-└── package.json
-```
-
-### Create a new post
-
-```bash
-fossbook new "My First Post"
-```
-
-This creates `content/posts/My First Post/index.md` with pre-filled front-matter and an `images/` directory.
-
-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 supports GitHub Flavored Markdown plus extensions for image sizing
-and alignment, captions, comic dialogue, aligned links, Mermaid diagrams, and
-syntax-highlighted code. See [Fossbook Markdown](fossbook_markdown.md) for
-syntax and examples.
-
-### 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: "말글 보이기",
-};
-```
-
-- `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
+```
+
+### 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: "말글 보이기",
+};
+```
+
+- `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).

package/package.json

@@ -1,45 +1,48 @@
-{
-  "name": "fossbook",
-  "version": "0.2.11",
-  "description": "A lightweight static blog site generator for GitHub Pages",
-  "main": "lib/index.js",
-  "scripts": {
-    "build": "node bin/fossbook.js build",
-    "start": "node bin/fossbook.js serve",
-    "test": "mocha test",
-    "prettier": "prettier --write ."
-  },
-  "keywords": [
-    "static-site-generator",
-    "blog",
-    "github-pages",
-    "markdown"
-  ],
-  "author": "Joone Hur",
-  "license": "BSD-3-Clause",
-  "dependencies": {
-    "express": "^4.19.1",
-    "front-matter": "^4.0.2",
-    "highlight.js": "^11.9.0",
-    "marked": "^12.0.1"
-  },
-  "devDependencies": {
-    "mocha": "^10.2.0",
-    "prettier": "^3.2.5"
-  },
-  "bin": {
-    "fossbook": "bin/fossbook.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "files": [
-    "bin/",
-    "lib/",
-    "themes/"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/joone/fossbook"
-  }
-}
+{
+  "name": "fossbook",
+  "version": "0.2.13",
+  "description": "A Markdown-based authoring and web-publishing tool for comics, illustrated stories, and articles",
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "node bin/fossbook.js build",
+    "start": "node bin/fossbook.js serve",
+    "test": "mocha test",
+    "prettier": "prettier --write ."
+  },
+  "keywords": [
+    "comic-authoring",
+    "webcomics",
+    "publishing",
+    "static-site-generator",
+    "github-pages",
+    "markdown"
+  ],
+  "author": "Joone Hur",
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "express": "^4.19.1",
+    "front-matter": "^4.0.2",
+    "highlight.js": "^11.9.0",
+    "marked": "^12.0.1"
+  },
+  "devDependencies": {
+    "mocha": "^10.2.0",
+    "prettier": "^3.2.5"
+  },
+  "bin": {
+    "fossbook": "bin/fossbook.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "docs/images/",
+    "lib/",
+    "themes/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joone/fossbook"
+  }
+}

package/themes/archie/assets/styles/main.css

@@ -461,6 +461,13 @@
     margin-top: 0.75rem;
   }
 
+  ul.pagination {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    padding-left: 0;
+  }
+
   /* navigation */
   h1.assistive-text {
     display: none;
@@ -514,6 +521,10 @@
     color: grey;
   }
 
+  ul.posts .meta {
+    margin-left: 0.50rem;
+  }
+
   /* Posts */
   article .title {
     margin-bottom: 1em;
@@ -553,6 +564,9 @@
   display: flex;
   justify-content: space-between;
   }
+  .site-description + .list-item h1 {
+    margin-top: 1rem;
+  }
   .post-tags ul.tags {
     display: flex;
     flex-wrap: wrap;

package/themes/archie/layouts/all_posts.html

@@ -35,7 +35,7 @@
                   .map(
                     (post) => `<li class="post">
                     <a href="${page.config.basePath}${post.path}">${post.title}</a><span class="meta">
-                        ${new Date(post.date).toDateString()}</span>
+                      ${page.formatDate(new Date(post.date))}</span>
                     </li>`,
                   )
                   .join("")}