Add documentation export to single HTML and PDF files

[Copilot]

Enables exporting Bnd documentation to offline formats (single HTML or PDF) for archival, distribution, and offline access across different versions.

Implementation

Export scripts:

• export-single-html.sh - Combines all Jekyll-generated pages into single HTML with embedded TOC and print-friendly CSS
• export-pdf.sh - Converts to PDF using auto-detected tools (wkhtmltopdf > weasyprint > chromium), falls back to HTML with manual conversion instructions
• export-release.sh - Exports from releases/ directory without requiring Jekyll rebuild

Content extraction:

• Python HTMLParser extracts main content from both _site structure (<main data-pagefind-body>) and release structure (<div class="notes-margin">)
• Preserves document order: index, introduction, chapters, instructions, macros, commands, headers, tools, plugins
• Handles nested HTML structures with depth tracking

Documentation:

• EXPORT_README.md - User guide with installation, usage, troubleshooting
• USAGE_EXAMPLES.md - 10 practical examples covering all workflows
• IMPLEMENTATION_SUMMARY.md - Technical details

Usage

# Export archived release (no build required)
./export-release.sh 7.0.0      # → bnd-docs-7.0.0.html (1.7 MB)
./export-release.sh 7.0.0 pdf  # → bnd-docs-7.0.0.pdf (995 KB)

# Export current development version
./build.sh
./export-single-html.sh master
./export-pdf.sh master

Tested with 7.0.0 release: 443 pages → 1.7MB HTML / 995KB PDF in <30s.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• accounts.google.com
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=4875 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.K6VpLd --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,17307914444301684977,14927625795285684904,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0 -I as (dns block)
  • Triggering command: /usr/bin/chromium-browser chromium-browser --headless --disable-gpu --no-sandbox --print-to-pdf=test-output.pdf --no-pdf-header-footer file:///home/REDACTED/work/bnd/bnd/docs/bnd-docs-temp-test.html kward -I y-3.2.0/ruby/bac-I -I y-3.2.0 -I. u/13/liblto_plug-I .3-1ubuntu0.24.0/usr/include/ruby-3.2.0/ruby/backward u/13/cc1 -I. s -D_FORTIFY_SOURC/var/log u/13/cc1 (dns block)
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=5688 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.OMNz3c --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,2703216554289212490,11620668788907996914,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0/ruby/bac-50 -I y-3.2.0 (dns block)
• clients2.google.com
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=4875 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.K6VpLd --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,17307914444301684977,14927625795285684904,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0 -I as (dns block)
  • Triggering command: /usr/bin/chromium-browser chromium-browser --headless --disable-gpu --no-sandbox --print-to-pdf=test-output.pdf --no-pdf-header-footer file:///home/REDACTED/work/bnd/bnd/docs/bnd-docs-temp-test.html kward -I y-3.2.0/ruby/bac-I -I y-3.2.0 -I. u/13/liblto_plug-I .3-1ubuntu0.24.0/usr/include/ruby-3.2.0/ruby/backward u/13/cc1 -I. s -D_FORTIFY_SOURC/var/log u/13/cc1 (dns block)
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=5688 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.OMNz3c --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,2703216554289212490,11620668788907996914,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0/ruby/bac-50 -I y-3.2.0 (dns block)
• https://api.github.com/repos/bndtools/bnd
  • Triggering command: /usr/bin/ruby3.2 ruby3.2 /home/REDACTED/work/bnd/bnd/docs/vendor/bundle/ruby/3.2.0/bin/jekyll build --gdwarf-5 --64 -o pipe.o /tmp/cciTsmQ2.s y-3.2.0/ruby/bacas kward y-3.2.0 /usr/libexec/gcc-I -qui�� by-3.2.0 (http block)
• redirector.gvt1.com
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=4875 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.K6VpLd --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,17307914444301684977,14927625795285684904,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0 -I as (dns block)
  • Triggering command: /usr/bin/chromium-browser chromium-browser --headless --disable-gpu --no-sandbox --print-to-pdf=test-output.pdf --no-pdf-header-footer file:///home/REDACTED/work/bnd/bnd/docs/bnd-docs-temp-test.html kward -I y-3.2.0/ruby/bac-I -I y-3.2.0 -I. u/13/liblto_plug-I .3-1ubuntu0.24.0/usr/include/ruby-3.2.0/ruby/backward u/13/cc1 -I. s -D_FORTIFY_SOURC/var/log u/13/cc1 (dns block)
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=5688 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.OMNz3c --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,2703216554289212490,11620668788907996914,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0/ruby/bac-50 -I y-3.2.0 (dns block)
• www.google.com
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=4875 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.K6VpLd --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,17307914444301684977,14927625795285684904,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0 -I as (dns block)
  • Triggering command: /usr/bin/chromium-browser chromium-browser --headless --disable-gpu --no-sandbox --print-to-pdf=test-output.pdf --no-pdf-header-footer file:///home/REDACTED/work/bnd/bnd/docs/bnd-docs-temp-test.html kward -I y-3.2.0/ruby/bac-I -I y-3.2.0 -I. u/13/liblto_plug-I .3-1ubuntu0.24.0/usr/include/ruby-3.2.0/ruby/backward u/13/cc1 -I. s -D_FORTIFY_SOURC/var/log u/13/cc1 (dns block)
  • Triggering command: /proc/self/exe /proc/self/exe --type=utility --utility-sub-type=network.mojom.NetworkService --lang=en-US --service-sandbox-type=network --no-sandbox --use-angle=swiftshader-webgl --crashpad-handler-pid=5688 --enable-crash-reporter=, --noerrdialogs --user-data-dir=/tmp/org.chromium.Chromium.scoped_dir.OMNz3c --change-stack-guard-on-fork=enable --shared-files=network_parent_dirs_pipe:100,v8_context_snapshot_data:101 --field-trial-handle=3,i,2703216554289212490,11620668788907996914,262144 --disable-features=PaintHolding --variations-seed-version --trace-process-track-uuid=3190708989122997041 y-3.2.0/ruby/bac-50 -I y-3.2.0 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.