@life-and-dev/mdsite 0.5.3 → 0.7.0

package/README.md

@@ -22,32 +22,28 @@ You write Markdown. For example, your content directory with a few pages and a l
 
 ```yaml
 my-docs/
-└── content
-    ├── index.md
-    ├── about.md
-    ├── blog/
-    │   ├── 2026-01-hello.md
-    │   └── 2026-03-release.md
-    └── logo.png
+├── index.md
+├── about.md
+├── blog/
+│   ├── 2026-01-hello.md
+│   └── 2026-03-release.md
+└── logo.png
 ```
 
 Run the `mdsite static` in your repo to generate the static pages:
 
 ```yaml
 my-docs/
-├── content
-│   ├── index.md
-│   ├── about.md
-│   ├── blog/
-│   │   ├── 2026-01-hello.md
-│   │   └── 2026-03-release.md
-│   └── logo.png
+├── index.md
+├── about.md
+├── blog/
+│   ├── 2026-01-hello.md
+│   └── 2026-03-release.md
+├── logo.png
 ├── mdsite.yml                  # site configuration
-├── package.json                # package configuration
-├── package-lock.json           # package lock
 ├── .mdsite/                    # renderer working dir (gitignored)
 │   ├── mdsite.log              # detached webserver logs
-│   └── ...                     # Other Nuxt render files
+│   └── ...                     # Other Node and Nuxt render files
 └── .output/                    # deployable static site
     └── public/
         ├── index.html          
@@ -63,9 +59,6 @@ my-docs/
         └── ...
 ```
 
-> [!NOTE]
-> You can technically mix your content and project files in the same directory, but it's easier to maintain content and generated files separately.
-
 ## Install
 
 Install the CLI globally from the npm registry on any machine with Node.js (>= 24.0.0) and npm:
@@ -82,8 +75,7 @@ The following commands will be available after installation:
 4. `mdsite static` : Start the static website - preview how it would behave on static webserver like Cloudflare Pages.
 5. `mdsite stop` : Stop tracked detached `mdsite live -d` or `mdsite static -d` processes.
 6. `mdsite prepare github` : Generate a Github Pages deployment workflow.
-
-After install, the `mdsite` command is available from any content directory.
+7. `mdsite clean` : Delete the renderer working dir and the generated output (refuses while a tracked process is running).
 
 All commands operate on the **current working directory** as the content/project directory. `-d`/`--detached` to runs a tracked background webserver, and `--host` (or `--host <addr>`) to expose the server on the network — see the start and preview sections below. Run `mdsite help` for more details.
 
@@ -91,20 +83,20 @@ All commands operate on the **current working directory** as the content/project
 
 `mdsite.yml` is the only active content-directory configuration file. `mdsite init` creates it and fills defaults from local markdown files where possible.
 
-| Key                      | Default                                  | Description                                                                                                                                                                  |
-| ------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `favicon`                | empty string                             | Source image path relative to the content directory (any format `sharp` supports). The renderer generates derived favicons into the renderer's `public/` dir.                |
-| `features.bibleTooltips` | `true`                                   | Enables renderer Bible tooltip support.                                                                                                                                      |
-| `features.sourceEdit`    | `true`                                   | Enables renderer source-edit support.                                                                                                                                        |
-| `footer`                 | empty array                              | Flat list of markdown file names (no `.md`) that appear in the bottom bar. Files listed here are excluded from `menu`.                                                         |
-| `menu`                   | derived from markdown files              | Menu structure for the sidebar navigation.                                                                                                                                   |
-| `server.output`          | `.output`                                | Static output path under the content directory.                                                                                                                              |
-| `server.path`            | `.mdsite`                                | The renderer working directory, relative to the content directory. End-user runs materialize the bundled renderer here; in the dev repo the bundled submodule runs in place. |
-| `server.repo`            | `https://github.com/life-and-dev/mdsite` | Stored for compatibility and generated renderer config. It is not used for active clone/pull behaviour.                                                                      |
-| `site.canonical`         | empty string                             | Canonical site URL passed to the renderer.                                                                                                                                   |
-| `site.name`              | derived from `index.md` or directory     | Site name passed to the renderer.                                                                                                                                            |
-| `themes.light.colors`    | built-in palette                         | Light theme colour overrides.                                                                                                                                                |
-| `themes.dark.colors`     | built-in palette                         | Dark theme colour overrides.                                                                                                                                                 |
+| Key                       | Default                              | Description                                                                                                                                                                                                                                    |
+| ------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `features.bible-tooltips` | `true`                               | Enables renderer Bible tooltip support.                                                                                                                                                                                                        |
+| `features.source-edit`    | empty string                         | URL prefix for the Edit button. When non-empty, the renderer appends `<page>.md` to this prefix to build the Edit link (e.g. `https://github.com/<owner>/<repo>/blob/main/`). An empty string (the default) disables the Edit button entirely. |
+| `features.footer`         | empty array                          | List of links, separators, and external URLs rendered in the bottom bar. Mirrors the `menu` item shape (string, `null`, or single-key object) without sub-menus.                                                                               |
+| `menu`                    | derived from markdown files          | Menu structure for the sidebar navigation.                                                                                                                                                                                                     |
+| `paths.input`             | directory of `mdsite.yml`            | Path to the directory holding your Markdown files, relative to the directory containing `mdsite.yml`. When omitted, MD-Site uses the directory of `mdsite.yml` as the content directory.                                                       |
+| `paths.build`             | `.mdsite`                            | The renderer working directory, relative to the content directory. End-user runs materialize the bundled renderer here; in the dev repo the bundled submodule runs in place.                                                                   |
+| `paths.output`            | `.output`                            | Static output path under the content directory.                                                                                                                                                                                                |
+| `site.canonical`          | empty string                         | Canonical site URL passed to the renderer.                                                                                                                                                                                                     |
+| `site.favicon`            | empty string                         | Source image path relative to the content directory (any format `sharp` supports). The renderer generates derived favicons into the renderer's `public/` dir.                                                                                  |
+| `site.name`               | derived from `index.md` or directory | Browser title, navbar, breadcrumb root, and web manifest name; overrides `index.md` H1.                                                                                                                                                        |
+| `themes.light.colors`     | built-in palette                     | Light theme colour overrides.                                                                                                                                                                                                                  |
+| `themes.dark.colors`      | built-in palette                     | Dark theme colour overrides.                                                                                                                                                                                                                   |
 
 The full documentation lives at [https://life-and-dev.github.io/mdsite/](https://life-and-dev.github.io/mdsite/).
 
@@ -125,7 +117,7 @@ We have prepared a series of tutorials to guide you through every aspect of work
   Learn the syntax of the `menu` section in `mdsite.yml`.
 
 - **[Footer Configuration](https://life-and-dev.github.io/mdsite/footer)**  
-  Learn how to populate the bottom bar with the `footer` section in `mdsite.yml`.
+  Learn how to populate the bottom bar with links, separators, and external URLs via the `footer` section in `mdsite.yml`.
 
 - **[Generating Favicons](https://life-and-dev.github.io/mdsite/favicon)**  
   Learn how to configure a favicon path in `mdsite.yml`.

package/dist/commands/clean.d.ts

@@ -0,0 +1 @@
+export declare function runCleanCommand(contentDir: string): Promise<string>;

package/dist/commands/clean.js

@@ -0,0 +1,70 @@
+import { access, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { loadMdsiteConfig } from '../config/mdsite-config.js';
+import { isProcessRunning, readRuntimeState } from '../process/runtime-state.js';
+async function pathExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runCleanCommand(contentDir) {
+    const loaded = await loadMdsiteConfig(contentDir);
+    const { config, contentDir: resolvedContentDir } = loaded;
+    // Refuse to wipe state while a tracked process is still pointing at it.
+    // Tracked PIDs live inside <paths.build>, so the clean would orphan them.
+    const trackedStates = await Promise.all([
+        readRuntimeState(resolvedContentDir, config, 'start'),
+        readRuntimeState(resolvedContentDir, config, 'preview')
+    ]);
+    for (const state of trackedStates) {
+        if (state && isProcessRunning(state.pid)) {
+            const alias = state.kind === 'start' ? 'live' : 'static';
+            throw new Error(`mdsite ${alias} is running with PID ${state.pid}. Run \`mdsite stop\` before \`mdsite clean\`.`);
+        }
+    }
+    // Anchor on the resolved content directory (not the config directory or
+    // the cwd passed in), so that `paths.input: <subdir>` setups (where
+    // `mdsite.yml` lives at the repo root and the markdown content lives in
+    // a sub-folder) still resolve <paths.build> and <paths.output> to the
+    // project that was actually built.
+    const rendererPath = path.resolve(resolvedContentDir, config.paths.build);
+    const outputPath = path.resolve(resolvedContentDir, config.paths.output);
+    const [rendererExists, outputExists] = await Promise.all([
+        pathExists(rendererPath),
+        pathExists(outputPath)
+    ]);
+    // `force: true` lets us skip non-existent paths without a separate branch.
+    await Promise.all([
+        rm(rendererPath, { recursive: true, force: true }),
+        rm(outputPath, { recursive: true, force: true })
+    ]);
+    const removed = [];
+    if (rendererExists) {
+        removed.push(config.paths.build);
+    }
+    if (outputExists) {
+        removed.push(config.paths.output);
+    }
+    if (removed.length === 0) {
+        return `Nothing to clean in ${resolvedContentDir}.`;
+    }
+    return `Removed ${joinRemoved(removed)} from ${resolvedContentDir}.`;
+}
+/**
+ * Join the cleaned paths in a single human-readable phrase.
+ * One path: `<a>`. Two: `<a> and <b>`. Three or more: `<a>, <b>, and <c>`.
+ */
+function joinRemoved(parts) {
+    if (parts.length === 1) {
+        return parts[0];
+    }
+    if (parts.length === 2) {
+        return `${parts[0]} and ${parts[1]}`;
+    }
+    return `${parts.slice(0, -1).join(', ')}, and ${parts[parts.length - 1]}`;
+}
+//# sourceMappingURL=clean.js.map

package/dist/commands/clean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean.js","sourceRoot":"","sources":["../../src/commands/clean.ts"],"names":[],"mappings":"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"}