fossbook 0.0.7 → 0.0.9

package/README.md

@@ -13,6 +13,7 @@ It was originally part of the [F/OSS Comics blog](https://fosscomics.com) and is
 - **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
 
@@ -86,6 +87,18 @@ module.exports = {
   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 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",
@@ -120,6 +133,35 @@ content/posts/My Post Title/
     └── 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.
+
+### 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
 
 ```
@@ -149,6 +191,46 @@ Fossbook ships with the Archie theme by default. To use a custom theme:
 
 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
 
 ```

package/lib/mod/config.js

@@ -17,6 +17,7 @@ const defaults = {
   image: "",
   theme: "archie",
   basePath: "",  // auto-detected for GitHub Pages project sites, e.g. "/repo-name/"
+  postsPath: "posts",  // URL prefix for posts: "posts" serves articles at /posts/<slug>/; set "" for root
   comments: null,  // { provider: "utterances", repo: "user/repo", issueTerm: "pathname", theme: "github-light" }
   content: "./content",
   postsDir: "./content/posts",
@@ -91,6 +92,9 @@ function loadConfig(configPath) {
     merged.basePath += "/";
   }
 
+  // Normalize postsPath into a bare segment without surrounding slashes
+  merged.postsPath = (merged.postsPath || "").replace(/^\/+|\/+$/g, "");
+
   return merged;
 }
 

package/lib/mod/marked.js

@@ -18,6 +18,27 @@ marked.setOptions({
 
 // Override function
 const renderer = {
+  code(code, infostring) {
+    // marked >=15 passes a token object; older versions pass positional args.
+    let text = code;
+    let lang = infostring;
+    if (code && typeof code === "object") {
+      text = code.text;
+      lang = code.lang;
+    }
+    const language = (lang || "").trim().split(/\s+/)[0];
+    // Emit mermaid fenced blocks as <pre class="mermaid"> so the mermaid
+    // client script can render them as diagrams instead of code.
+    if (language === "mermaid") {
+      const escaped = text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+      return `<pre class="mermaid">${escaped}</pre>`;
+    }
+    // Fall back to marked's default code rendering for everything else.
+    return false;
+  },
   image(href, title, text) {
     let size = null;
     // Check if the title contains a size specification

package/lib/mod/page.js

@@ -26,6 +26,9 @@ module.exports = class Page extends PageBase {
       // If there's no .md extension, just get the last part of the path
       this.path = path.basename(filePath);
     }
+    // The source folder name, used to locate the post's images on disk.
+    // this.path may later be prefixed (e.g. "posts/<slug>") for output/URLs.
+    this.slug = this.path;
     // parsed content by fields and body
     const content = fm(mdContent);
 
@@ -75,7 +78,7 @@ module.exports = class Page extends PageBase {
           recursive: true,
         });
 
-      fs.mkdirSync(outPath);
+      fs.mkdirSync(outPath, { recursive: true });
     } else {
       // remove the outputPath file if it exists
       const outPath = path.join(this.config.dev.outdir, this.path);
@@ -96,7 +99,7 @@ module.exports = class Page extends PageBase {
     );
 
     // if there is the images folder in the output directory.
-    const srcImagesDir = path.join(this.config.dev.postsdir, this.path, "images");
+    const srcImagesDir = path.join(this.config.dev.postsdir, this.slug, "images");
     if (
       fs.existsSync(srcImagesDir) &&
       this.path !== ""
@@ -104,7 +107,7 @@ module.exports = class Page extends PageBase {
       // Copy images folder from postsdir to outdir
       const destImagesDir = path.join(this.config.dev.outdir, this.path, "images");
       if (!fs.existsSync(destImagesDir))
-        fs.mkdirSync(destImagesDir);
+        fs.mkdirSync(destImagesDir, { recursive: true });
 
       fs.readdirSync(srcImagesDir).forEach(
         (image) => {

package/lib/posts.js

@@ -23,6 +23,10 @@ module.exports = class Posts {
       }
       const post = new Page(this.config);
       post.readSource(path.join(this.config.dev.postsdir, postPath));
+      // Optionally nest posts under a URL prefix (e.g. "posts" -> /posts/<slug>/).
+      // post.slug stays the source folder name so image lookups remain correct.
+      const prefix = this.config.postsPath ? `${this.config.postsPath}/` : "";
+      post.path = `${prefix}${post.slug}`;
       post.url = `${this.config.blogsite}/${post.path}/`;
       post.imageURL = `${this.config.blogsite}/${post.path}/images/${post.image}`;
       this.posts.push(post);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fossbook",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A lightweight static blog site generator for GitHub Pages",
   "main": "lib/index.js",
   "scripts": {

package/themes/archie/layouts/post.html

@@ -78,5 +78,9 @@
               ${page.footer()}
             </footer>
         </div>
+        ${page.body.includes('class="mermaid"') ? `<script type="module">
+            import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+            mermaid.initialize({ startOnLoad: true });
+        </script>` : ""}
     </body>
 </html>