mdpack: Markdown Bundler

Common errors

• Error: Cannot find module 'mdpack'

  cause The `mdpack` package is not installed or not resolvable in the current project's `node_modules`.
  fix Run `npm install mdpack` for local installation or `npm install -g mdpack` if intending to use the CLI globally. If using `npx`, ensure it's available and configured correctly.

• mdpack: command not found

  cause The `mdpack` CLI command is not available in your system's PATH, typically because it wasn't installed globally or via a local `node_modules/.bin` entry.
  fix Install `mdpack` globally with `npm install -g mdpack` or use `npx mdpack` if it's a project dependency.

• Error: Unknown plugin: mdpackPluginMyCustomPlugin

  cause Attempting to use a plugin that is not part of the `mdpack.plugins` namespace or has not been correctly provided/loaded.
  fix Ensure the plugin class is correctly imported and instantiated, and that it's a valid `mdpack` plugin. Double-check the spelling and casing of the plugin name. Custom plugins must be developed to the `mdpack` plugin API.

• Syntax Error: Unexpected token ' (or similar related to @@import)

  cause Incorrect syntax used for `@@import` statements in markdown files, such as using single quotes instead of double quotes, or extra spaces.
  fix Ensure all `@@import` statements strictly follow the format `@@import "path/to/file.md"` with double quotes around the file path and no extraneous characters.

Warnings

• gotcha The `@@import "path/to/file"` syntax is custom to mdpack and not standard Markdown. Using standard Markdown includes or common templating syntaxes will not work.
  Fix: Adhere strictly to the `@@import "<path>"` syntax with double quotes for imports. Ensure the path is correct and accessible relative to the entry file.
• gotcha The package (version 0.5.2) was last published in August 2018, indicating it may not be actively maintained. This could lead to compatibility issues with newer Node.js versions, outdated dependencies, or potential security vulnerabilities.
  Fix: Exercise caution when using in production environments. Consider auditing its dependencies for known vulnerabilities and thoroughly testing against your target Node.js version. Be prepared to fork or find alternatives if critical issues arise.
• gotcha The README contains a section titled 'Deprecated' that refers to 'docz'. This phrasing can be ambiguous and lead users to believe `mdpack` itself is deprecated, rather than clarifying its relation to `docz` or its own aspirations. `mdpack` is not explicitly marked as deprecated by its author.
  Fix: Interpret the 'Deprecated' section as a comparison or commentary on `docz`, not as a statement on the status of `mdpack` itself.
• gotcha The project uses CommonJS (`require`) exclusively in its examples and was released before widespread Node.js ESM adoption. Using `import` statements directly might require a build step (like Babel or Webpack) or specific Node.js `--experimental-modules` flags, which might not be supported or stable for this older package.
  Fix: Prefer CommonJS `require()` syntax when importing `mdpack` and its components within Node.js projects, or use a transpiler to handle ESM imports.

Install

• npm install mdpack npm
• yarn add mdpack yarn
• pnpm add mdpack pnpm

Imports

• mdpack
  wrong:

  const { mdpack } = require('mdpack')

  correct:

  import mdpack from 'mdpack'

  While CommonJS `require('mdpack')` directly returns the main function, for future-proofing or in mixed ESM/CJS environments, using `import mdpack from 'mdpack'` is recommended, often needing a build step for older Node.js versions. The package was published prior to widespread ESM adoption in Node.js.
• mdpackPluginHtmlMinifier
  wrong:

  import { mdpackPluginHtmlMinifier } from 'mdpack'

  correct:

  import mdpack from 'mdpack'; new mdpack.plugins.mdpackPluginHtmlMinifier()

  Plugins are exposed via the `plugins` property of the main `mdpack` object, not as direct named exports. Ensure `mdpack` is imported first to access its plugin namespace.
• mdpackPluginBannerFooter
  wrong:

  new mdpackPluginBannerFooter()

  correct:

  import mdpack from 'mdpack'; new mdpack.plugins.mdpackPluginBannerFooter({ banner: '# Banner' })

  Similar to other plugins, `mdpackPluginBannerFooter` is nested under `mdpack.plugins`. It also requires an options object for configuration.

Quickstart

Demonstrates programmatic use of `mdpack` with a full configuration, including output paths, custom CSS resources, HTML templates, and two plugins (HTML minifier and banner/footer). It also includes setup for dummy files to ensure the example is runnable.

const path = require('path');
const mdpack = require('mdpack');

const config = {
  entry: 'index.md',
  output: {
    path: path.resolve(__dirname, 'dist'),
    name: 'mybundle'
  },
  format: ['md', 'html'],
  resources: {
    markdownCss: 'https://unpkg.com/github-markdown-css@2.10.0/github-markdown.css',
    highlightCss: 'https://unpkg.com/highlight.js@9.12.0/styles/github-gist.css'
  },
  template: path.resolve(__dirname, 'mytemplate.html'),
  plugins: [
    new mdpack.plugins.mdpackPluginHtmlMinifier(),
    new mdpack.plugins.mdpackPluginBannerFooter({
      banner: '# My Custom Banner',
      footer: '<footer>Built with mdpack</footer>'
    })
  ],
  watch: false // Set to true for development
};

// Create dummy files for the example to run
require('fs').writeFileSync('index.md', '# Hello World\n\n@@import "./sub.md"');
require('fs').writeFileSync('sub.md', '## Sub-content here');
require('fs').writeFileSync('mytemplate.html', '<!DOCTYPE html><html><head><title>My Bundle</title></head><body><div class="markdown-body">{html}</div></body></html>');

mdpack(config).then(() => console.log('mdpack bundled successfully!')).catch(err => console.error('mdpack error:', err));