marp-dev-preview 0.3.1 → 0.3.3

package/README.md

@@ -27,7 +27,7 @@ Originally built as a dependency for the [marp-dev-preview.nvim](https://github.
 The simplest way to run the previewer:  
 
 ```bash
-npx marp-dev-preview --theme-dir <themes-dir> <presentation.md>
+npx marp-dev-preview --markdown-file <presentation.md> --theme-set <themes-dir>
 ```
 
 ---
@@ -53,19 +53,59 @@ npm install marp-dev-preview
 Start the preview server with:  
 
 ```bash
-mdp <path-to-markdown-file> [options]
+mdp [options]
 ```
 
 **Example:**  
 
 ```bash
-mdp my-slides/presentation.md --port 3000 --theme-dir my-themes
+mdp --markdown-file my-slides/presentation.md --port 3000 --theme-set my-themes
 ```
 
 ### Options
 
-- `-t, --theme-dir <path>` — Path to custom Marp themes (CSS files)  
+- `-m, --markdown-file <path>` — Path to the markdown file to preview
+- `-t, --theme-set <path...>` — One or more directories containing custom Marp themes (CSS files)
+- `--theme-dir <path...>` — Alias for `--theme-set`
 - `-p, --port <number>` — Port for the preview server (default: `8080`)  
+- `-c, --containers <name...>` — Container names to register for `markdown-it-container`
+- `-v, --verbose` — Enable verbose logging
+- `--config <path>` — Path to a JSON config file (default: `.mp-config.json`)
+- `--example-config` — Print an example JSON config file and exit
+
+### Configuration File
+
+Options can be loaded from a JSON config file. If `.mp-config.json` is present in the current working directory, it is read automatically without passing `--config`. Command-line flags override values from that file.
+
+Example `.mp-config.json`:
+
+```json
+{
+  "markdown-file": "my-slides/presentation.md",
+  "theme-set": ["my-themes"],
+  "port": 3000,
+  "verbose": true,
+  "containers": ["note", "info", "warn", "important"]
+}
+```
+
+Run and auto-load `.mp-config.json` if it exists:
+
+```bash
+mdp
+```
+
+Or point to a different file:
+
+```bash
+mdp --config ./preview-config.json
+```
+
+Print an example config file:
+
+```bash
+mdp --example-config
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marp-dev-preview",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A CLI tool to preview Marp markdown files.",
   "main": "src/marp-dev-preview.mjs",
   "type": "module",

package/src/args.mjs

@@ -1,9 +1,28 @@
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
+export const exampleConfig = {
+  'markdown-file': 'my-slides/presentation.md',
+  'theme-set': ['my-themes'],
+  port: 3000,
+  verbose: true,
+  containers: ['note', 'info', 'warn', 'important']
+};
+
+function toCamelCase(name) {
+  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
 export function parseArgs() {
   return yargs(hideBin(process.argv))
     .usage('Usage: $0 [options]')
+    .parserConfiguration({
+      'strip-aliased': true,
+    })
+    .example('$0 --markdown-file slides.md --theme-set themes', 'Preview a markdown deck with custom themes')
+    .example('$0', 'Automatically load .mp-config.json when it is present')
+    .example('$0 --config preview-config.json', 'Load options from a specific JSON config file')
+    .example('$0 --example-config', 'Print an example .mp-config.json and exit')
     .option('markdown-file', {
       alias: 'm',
       describe: 'Path to the markdown file to preview',
@@ -16,7 +35,7 @@ export function parseArgs() {
       default: ["note", "info", "warn", "important"]
     })
     .option('theme-set', {
-      alias: 't',
+      alias: ['t', 'theme-dir'],
       describe: 'Directories for custom themes',
       type: 'array'
     })
@@ -32,7 +51,19 @@ export function parseArgs() {
       type: 'boolean',
       default: false
     })
-    .config('config', 'Path to a JSON config file')
+    .option('example-config', {
+      describe: 'Print an example JSON config file and exit',
+      type: 'boolean',
+      default: false
+    })
+    .config('config', 'Path to a JSON config file. .mp-config.json is loaded automatically when present')
     .default('config', '.mp-config.json')
+    .middleware(argv => {
+      if (!argv.markdownFile && Array.isArray(argv._) && argv._.length > 0) {
+        [argv.markdownFile] = argv._;
+      }
+
+      argv.exampleConfig = argv.exampleConfig ?? argv[toCamelCase('example-config')] ?? argv['example-config'] ?? false;
+    }, true)
     .argv;
 }

package/src/marp-dev-preview.mjs

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'url';
 /* Sub-modules */
 import { createServer } from './server.mjs';
 import { initializeMarp, getMarp } from './marp-utils.mjs';
-import { parseArgs } from './args.mjs';
+import { exampleConfig, parseArgs } from './args.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -28,6 +28,11 @@ if (argv.version) {
   process.exit(0);
 }
 
+if (argv.exampleConfig) {
+  console.log(JSON.stringify(exampleConfig, null, 2));
+  process.exit(0);
+}
+
 if (verbose) {
   console.debug = console.log;
 } else {
@@ -168,7 +173,7 @@ if (themeSet) {
 }
 
 initializeMarp(themeSet, containers).then(() => {
-  const app = createServer(markdownDir, renderMarp, reload, wss, __dirname);
+  const app = createServer(markdownDir, themeSet ?? [], renderMarp, reload, wss, __dirname);
   const server = http.createServer(app);
 
   server.on('upgrade', (request, socket, head) => {

package/src/marp-utils.mjs

@@ -13,7 +13,7 @@ export function getMarp() {
 }
 
 
-export async function initializeMarp(themeSet, containers) {
+export async function initializeMarp(themeSet, containers = []) {
   const options = { html: true, linkify: true, };
   marp = new Marp(options)
     .use(markdownItFootnote)

package/src/server.mjs

@@ -2,9 +2,12 @@ import express from 'express';
 import path from 'path';
 import { promises as fs } from 'fs';
 
-export function createServer(markdownDir, renderMarp, reload, wss, __dirname) {
+export function createServer(markdownDir, themeDirs, renderMarp, reload, wss, __dirname) {
   const app = express();
 
+  for (const themeDir of themeDirs) {
+    app.use(express.static(themeDir));
+  }
   app.use(express.static(markdownDir));
   app.use(express.text({ type: 'text/markdown' }));
   app.use(express.json());

package/test/args.test.mjs

@@ -3,13 +3,20 @@ import { parseArgs } from '../src/args.mjs';
 const mockArgv = {};
 const defaultValues = {};
 
+function mockToCamelCase(name) {
+  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
 jest.mock('yargs', () => {
   const yargsMock = jest.fn(() => yargsMock);
   yargsMock.usage = jest.fn().mockReturnThis();
+  yargsMock.parserConfiguration = jest.fn().mockReturnThis();
+  yargsMock.example = jest.fn().mockReturnThis();
   yargsMock.positional = jest.fn().mockReturnThis();
   yargsMock.option = jest.fn().mockImplementation((name, options) => {
     if (options.default !== undefined) {
       defaultValues[name] = options.default;
+      defaultValues[mockToCamelCase(name)] = options.default;
     }
     return yargsMock;
   });
@@ -18,12 +25,25 @@ jest.mock('yargs', () => {
     defaultValues[name] = value;
     return yargsMock;
   });
+  yargsMock.middleware = jest.fn().mockImplementation((fn) => {
+    yargsMock.__middleware = fn;
+    return yargsMock;
+  });
   yargsMock.demandCommand = jest.fn().mockReturnThis();
   Object.defineProperty(yargsMock, 'argv', {
-    get: () => ({
-      ...defaultValues,
-      ...mockArgv,
-    }),
+    get: () => {
+      const argv = {
+        ...defaultValues,
+        ...mockArgv,
+      };
+      if (!Array.isArray(argv._)) {
+        argv._ = [];
+      }
+      if (yargsMock.__middleware) {
+        yargsMock.__middleware(argv);
+      }
+      return argv;
+    },
   });
   return yargsMock;
 });
@@ -71,14 +91,21 @@ describe('Args', () => {
   it('should capture markdown file positional argument', () => {
     mockArgv._ = ['my-presentation.md'];
     const argv = parseArgs();
-    expect(argv._[0]).toBe('my-presentation.md');
+    expect(argv.markdownFile).toBe('my-presentation.md');
   });
 
-  it('should return theme-dir if specified', () => {
+  it('should return theme-set if specified', () => {
     mockArgv._ = ['test.md'];
-    mockArgv.themeDir = '/path/to/themes';
+    mockArgv.themeSet = ['/path/to/themes'];
     const argv = parseArgs();
-    expect(argv.themeDir).toBe('/path/to/themes');
+    expect(argv.themeSet).toEqual(['/path/to/themes']);
+  });
+
+  it('should support the theme-dir alias', () => {
+    mockArgv._ = ['test.md'];
+    mockArgv.themeSet = ['/path/to/themes'];
+    const argv = parseArgs();
+    expect(argv.themeSet).toEqual(['/path/to/themes']);
   });
 
   it('should handle config file path', () => {
@@ -87,4 +114,23 @@ describe('Args', () => {
     const argv = parseArgs();
     expect(argv.config).toBe('./my-config.json');
   });
+
+  it('should keep an explicit markdown-file option over the positional argument', () => {
+    mockArgv._ = ['positional.md'];
+    mockArgv.markdownFile = 'flag.md';
+    const argv = parseArgs();
+    expect(argv.markdownFile).toBe('flag.md');
+  });
+
+  it('should return example-config as false by default', () => {
+    mockArgv._ = ['test.md'];
+    const argv = parseArgs();
+    expect(argv.exampleConfig).toBe(false);
+  });
+
+  it('should return example-config as true if specified', () => {
+    mockArgv.exampleConfig = true;
+    const argv = parseArgs();
+    expect(argv.exampleConfig).toBe(true);
+  });
 });

package/test/marp-dev-preview.test.mjs

@@ -3,20 +3,41 @@
 // This is necessary because jest has issues with importing express, which is a CJS module,
 // in a project that uses ES modules ("type": "module" in package.json).
 import { createServer } from '../src/server.mjs';
+import express from 'express';
 
 describe('Server', () => {
+  beforeEach(() => {
+    express.static.mockClear();
+  });
+
   it('should create a server', () => {
     const markdownDir = '.';
+    const themeDirs = [];
     const renderMarp = jest.fn();
     const reload = jest.fn();
     const wss = { clients: [] };
     const __dirname = '.';
 
-    const app = createServer(markdownDir, renderMarp, reload, wss, __dirname);
+    const app = createServer(markdownDir, themeDirs, renderMarp, reload, wss, __dirname);
 
     expect(app).toBeDefined();
     expect(typeof app.use).toBe('function');
     expect(typeof app.get).toBe('function');
     expect(typeof app.post).toBe('function');
   });
+
+  it('should mount theme directories before the markdown directory', () => {
+    const markdownDir = '/slides';
+    const themeDirs = ['/themes/a', '/themes/b'];
+    const renderMarp = jest.fn();
+    const reload = jest.fn();
+    const wss = { clients: [] };
+    const __dirname = '.';
+
+    createServer(markdownDir, themeDirs, renderMarp, reload, wss, __dirname);
+
+    expect(express.static).toHaveBeenNthCalledWith(1, '/themes/a');
+    expect(express.static).toHaveBeenNthCalledWith(2, '/themes/b');
+    expect(express.static).toHaveBeenNthCalledWith(3, '/slides');
+  });
 });