Portable CLI build

You can pack the @diplodoc/cli package into a single executable file for Windows, macOS, or Linux. The file contains both the CLI and the Node.js runtime, so the computer that runs it doesn't need anything installed: no Node.js, no npm. It also works without internet access.

This is handy when documentation is built by people without permission to install software or on machines with no internet connection.

Step 1. Install Node.js

Node.js is only required on the computer where you build the file.

1. Download the Node.js installer, version 24 or newer, from the official website.

2. Run it and complete all steps with the default settings.

3. Open a terminal (on Windows, the PowerShell app) and check the installation:

   node -v
   

   It should print a version number, for example v24.18.0.

Step 2. Build the executable

Pick the tab with the system the file will run on. Copy the entire block into the terminal and press Enter: it creates the yfm-exe folder, downloads the required packages into it, and builds the file.

mkdir yfm-exe
cd yfm-exe
@'
{
  "name": "yfm-portable",
  "version": "1.0.0",
  "bin": "node_modules/@diplodoc/cli/build/index.js",
  "pkg": {
    "scripts": [
      "node_modules/@diplodoc/cli/build/**/*.js",
      "node_modules/@diplodoc/cli/lib/**/*.js",
      "node_modules/@diplodoc/client/build/server/**/*.js"
    ],
    "assets": [
      "node_modules/@diplodoc/cli/assets/**/*",
      "node_modules/@diplodoc/cli/build/manifest.json",
      "node_modules/@diplodoc/cli/package.json",
      "node_modules/highlight.js/styles/**/*"
    ]
  }
}
'@ | Set-Content -Encoding Ascii package.json
npm install @diplodoc/cli @yao-pkg/pkg
npx pkg --compress GZip --public -t node24-win-x64 -o dist/yfm.exe package.json

mkdir yfm-exe && cd yfm-exe
cat > package.json <<'EOF'
{
  "name": "yfm-portable",
  "version": "1.0.0",
  "bin": "node_modules/@diplodoc/cli/build/index.js",
  "pkg": {
    "scripts": [
      "node_modules/@diplodoc/cli/build/**/*.js",
      "node_modules/@diplodoc/cli/lib/**/*.js",
      "node_modules/@diplodoc/client/build/server/**/*.js"
    ],
    "assets": [
      "node_modules/@diplodoc/cli/assets/**/*",
      "node_modules/@diplodoc/cli/build/manifest.json",
      "node_modules/@diplodoc/cli/package.json",
      "node_modules/highlight.js/styles/**/*"
    ]
  }
}
EOF
npm install @diplodoc/cli @yao-pkg/pkg
npx pkg --compress GZip --public -t node24-macos-arm64 -o dist/yfm package.json

mkdir yfm-exe && cd yfm-exe
cat > package.json <<'EOF'
{
  "name": "yfm-portable",
  "version": "1.0.0",
  "bin": "node_modules/@diplodoc/cli/build/index.js",
  "pkg": {
    "scripts": [
      "node_modules/@diplodoc/cli/build/**/*.js",
      "node_modules/@diplodoc/cli/lib/**/*.js",
      "node_modules/@diplodoc/client/build/server/**/*.js"
    ],
    "assets": [
      "node_modules/@diplodoc/cli/assets/**/*",
      "node_modules/@diplodoc/cli/build/manifest.json",
      "node_modules/@diplodoc/cli/package.json",
      "node_modules/highlight.js/styles/**/*"
    ]
  }
}
EOF
npm install @diplodoc/cli @yao-pkg/pkg
npx pkg --compress GZip --public -t node24-linux-x64 -o dist/yfm package.json

On the first run, the last command downloads a base Node.js build for the target system, so it may take a few minutes. Warning messages during the process are normal.

The resulting file is about 150 MB, as it contains a full Node.js runtime.

Step 3. Check the result

Run the built file. On Windows:

dist\yfm.exe --version

On macOS and Linux:

./dist/yfm --version

It should print the CLI version, for example 5.55.3. Then build some documentation project:

dist\yfm.exe -i path-to-sources -o path-to-output

How to use it

• Copy the file anywhere: to another computer, a flash drive, or a network share. No installation is needed, the file is self-contained.
• All commands and options are the same as in the regular yfm from npm: building a project, build parameters.
• The file isn't signed, so security features may ask for confirmation on the first launch:
  • on Windows, click More info and then Run anyway in the SmartScreen window;
  • on macOS, if the file was downloaded from the internet, allow it in System Settings → Privacy & Security, or remove the quarantine attribute with xattr -d com.apple.quarantine path-to-file.

Limitations

• The file only runs on the system it was built for. If you need both Windows and macOS, build two files, see building for another system.

• Custom plugins (a plugins.js file next to the project) don't load in the portable build.

  How to bake plugins into the file

  Plugins can be packed into the file at build time. Before the last command of step 2, copy your plugins file into the CLI package:

  mkdir -p node_modules/@diplodoc/cli/build/plugins
  cp path-to-your-plugins.js node_modules/@diplodoc/cli/build/plugins/index.js
  

  Then rebuild the file - the plugins will work on all machines without any extra files.

• To update the CLI to a new version, rebuild the file: run npm install @diplodoc/cli@latest in the yfm-exe folder and repeat the last command of step 2.

Building for another system

You can build on one system and run on another: for example, build a Windows file on macOS. To do that, change the -t parameter value in the last command of step 2:

For example, building a Windows file on any system:

npx pkg --compress GZip --public -t node24-win-x64 -o dist/yfm.exe package.json