{"id":15699,"library":"mdpack","title":"mdpack: Markdown Bundler","description":"mdpack is a markdown bundler that enables the composition of markdown and HTML files, treating them similarly to how JavaScript modules are imported. It processes custom `@@import` statements to combine content from various files and can output the bundled result in both markdown and HTML formats. The package, currently at version 0.5.2 (last published in August 2018), provides both a Command Line Interface (CLI) and a Node.js API for programmatic use. Key features include a plugin system, allowing extensions for tasks like HTML minification or adding banners and footers to the bundled output. While the project's README mentions alternatives like `docz` and labels its section on it as \"Deprecated\" (referring to `docz` or its own aspiration), `mdpack` differentiates itself through its specific custom import syntax and its dual output capabilities for markdown and HTML. Its release cadence is currently inactive, given the last publish date.","status":"maintenance","version":"0.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/PengJiyuan/mdpack","tags":["javascript","markdown","bundle"],"install":[{"cmd":"npm install mdpack","lang":"bash","label":"npm"},{"cmd":"yarn add mdpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdpack","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { mdpack } = require('mdpack')","symbol":"mdpack","correct":"import mdpack from 'mdpack'"},{"note":"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.","wrong":"import { mdpackPluginHtmlMinifier } from 'mdpack'","symbol":"mdpackPluginHtmlMinifier","correct":"import mdpack from 'mdpack'; new mdpack.plugins.mdpackPluginHtmlMinifier()"},{"note":"Similar to other plugins, `mdpackPluginBannerFooter` is nested under `mdpack.plugins`. It also requires an options object for configuration.","wrong":"new mdpackPluginBannerFooter()","symbol":"mdpackPluginBannerFooter","correct":"import mdpack from 'mdpack'; new mdpack.plugins.mdpackPluginBannerFooter({ banner: '# Banner' })"}],"quickstart":{"code":"const path = require('path');\nconst mdpack = require('mdpack');\n\nconst config = {\n entry: 'index.md',\n output: {\n path: path.resolve(__dirname, 'dist'),\n name: 'mybundle'\n },\n format: ['md', 'html'],\n resources: {\n markdownCss: 'https://unpkg.com/github-markdown-css@2.10.0/github-markdown.css',\n highlightCss: 'https://unpkg.com/highlight.js@9.12.0/styles/github-gist.css'\n },\n template: path.resolve(__dirname, 'mytemplate.html'),\n plugins: [\n new mdpack.plugins.mdpackPluginHtmlMinifier(),\n new mdpack.plugins.mdpackPluginBannerFooter({\n banner: '# My Custom Banner',\n footer: ''\n })\n ],\n watch: false // Set to true for development\n};\n\n// Create dummy files for the example to run\nrequire('fs').writeFileSync('index.md', '# Hello World\\n\\n@@import \"./sub.md\"');\nrequire('fs').writeFileSync('sub.md', '## Sub-content here');\nrequire('fs').writeFileSync('mytemplate.html', 'My Bundle{html}
');\n\nmdpack(config).then(() => console.log('mdpack bundled successfully!')).catch(err => console.error('mdpack error:', err));\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Adhere strictly to the `@@import \"\"` syntax with double quotes for imports. Ensure the path is correct and accessible relative to the entry file.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.5.2"},{"fix":"Interpret the 'Deprecated' section as a comparison or commentary on `docz`, not as a statement on the status of `mdpack` itself.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Prefer CommonJS `require()` syntax when importing `mdpack` and its components within Node.js projects, or use a transpiler to handle ESM imports.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The `mdpack` package is not installed or not resolvable in the current project's `node_modules`.","error":"Error: Cannot find module 'mdpack'"},{"fix":"Install `mdpack` globally with `npm install -g mdpack` or use `npx mdpack` if it's a project dependency.","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.","error":"mdpack: command not found"},{"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.","cause":"Attempting to use a plugin that is not part of the `mdpack.plugins` namespace or has not been correctly provided/loaded.","error":"Error: Unknown plugin: mdpackPluginMyCustomPlugin"},{"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.","cause":"Incorrect syntax used for `@@import` statements in markdown files, such as using single quotes instead of double quotes, or extra spaces.","error":"Syntax Error: Unexpected token ' (or similar related to @@import)"}],"ecosystem":"npm"}