ventoy-extras/docs/generate-ventoy-json.md

generate-ventoy-json.ps1

Walks an iso-library directory tree and emits a ventoy.json with per-category submenus. Output is UTF-8, no BOM, ready to drop into \ventoy\ventoy.json on the Ventoy USB.

Parameters

Parameter	Default	Description
-IsoRoot	.\iso-library	Root of the ISO tree to scan (recursively, for *.iso).
-OutFile	.\ventoy.json	Where to write the generated JSON.
-VentoyDrive	E	Cosmetic — currently unused at runtime; kept for forward compat.

Expected input tree

<IsoRoot>\
  <os-slug>\
    <version>\
      <arch>\
        *.iso

This is exactly what organise-isos.ps1 produces. Files that don't fit this layout still get included, but with a best-effort fallback:

• 3 path segments deep → arch defaults to noarch.
• < 3 segments → os and version both default to unknown.

Output structure

Each top-level entry in ventoy.json is a category submenu, containing one entry per ISO:

{
  "menu_alias": [
    {
      "name": "Ubuntu Family",
      "image": [
        { "image": "/ubuntu/24.04/x86_64/ubuntu-24.04.1-desktop-amd64.iso",
          "menu_alias": "Ubuntu 24.04 [x86_64]" },
        { "image": "/lubuntu/24.04/x86_64/lubuntu-24.04-desktop-amd64.iso",
          "menu_alias": "Lubuntu 24.04 [x86_64]" }
      ]
    },
    {
      "name": "Rescue & Tools",
      "image": [
        { "image": "/clonezilla/3.1/x86_64/clonezilla-live-3.1.2-22-amd64.iso",
          "menu_alias": "Clonezilla 3.1 [x86_64]" }
      ]
    }
  ]
}

Menu labels

For each ISO, the label is built as:

<display name> <version>[ [<arch>]]

Where:

• <display name> is looked up in $displayNames (e.g. ubuntu → Ubuntu, proxmox-ve → Proxmox VE). Unmapped slugs are title-cased as a fallback.
• The arch suffix [<arch>] is omitted when arch is noarch.

Examples: Ubuntu 24.04 [x86_64], Proxmox VE 8.2, Memtest86+ 6.20 [x86_64].

Category groupings

Slugs are mapped to category names via $categoryMap:

Category	Slugs included
Windows	windows, windows-server, ms-dos, reactos
RHEL Family	rhel, centos, rocky, almalinux, oraclelinux, scientific, eurolinux, navylinux
Fedora Family	fedora, qubes, coreos
SUSE Family	opensuse*, sles, geckolinux
Debian Family	debian, raspios, armbian, devuan, mx, antix, deepin, pureos, grml, lmde
Ubuntu Family	ubuntu*, lubuntu, kubuntu, xubuntu, linuxmint, pop_os, elementary, zorin
Arch Family	arch, manjaro, endeavouros, garuda, artix, cachyos, arcolinux
Gentoo Family	gentoo, funtoo, calculate
Slackware Family	slackware, salix, porteus
Independent Linux	void, nixos, alpine, solus, clearlinux, flatcar
Security	kali, parrot, backbox, tails, whonix, blackarch
Network & Firewall	pfsense, opnsense, ipfire, vyos, openwrt, ddwrt
Virtualisation	proxmox-*, esxi, vsphere, xcp-ng, xenserver, harvester
BSD Family	freebsd, openbsd, netbsd, dragonflybsd, truenas*, ghostbsd
Solaris & illumos	openindiana, omnios, smartos, solaris
Media	libreelec, osmc
Exotic	haiku, freedos, reactos
Rescue & Tools	clonezilla, systemrescue, gparted, memtest, memtest86, rescuezilla, hirens, winpe, dban, ubcd, vendor rescue disks
Other	anything unmapped — sorted alphabetically at the end

Matching is exact-first, then prefix. So opensuse-leap matches the exact opensuse-leap entry if present, otherwise falls through to the opensuse prefix.

Category order in the output menu is fixed (see $categoryOrder in the script). Unlisted categories — including any new ones you add — append alphabetically after the predefined order.

Adding a category

Edit generate-ventoy-json.ps1:

$categoryMap = [ordered]@{
    # ...existing...
    'mycoolos' = 'Hobbyist OSes'   # new category name appears as-is in the menu
}

# Optional — place it explicitly in the menu order:
$categoryOrder = @(
    'Windows',
    # ...
    'Hobbyist OSes',
    # ...
)

Output details

• Encoding: UTF-8 without BOM. Ventoy accepts this.
• Indentation: ConvertTo-Json -Depth 10 default formatting.
• Path separators: forward slashes, leading /. Ventoy paths are rooted at the Ventoy data partition root, not at filesystem root.

Exit codes

• 0 — always. The script prints to stderr but does not exit non-zero on parsing edge cases; "unknown" categories are silently bucketed into Other.

Idempotency

Pure function of the directory tree. Re-running over the same tree always produces byte-identical output (modulo line endings if you edited the script). Safe to run on every Ventoy refresh.