Skip to content

Add documentation export to single HTML and PDF files#7081

Draft
Copilot wants to merge 8 commits intomasterfrom
copilot/add-html-pdf-generation-options
Draft

Add documentation export to single HTML and PDF files#7081
Copilot wants to merge 8 commits intomasterfrom
copilot/add-html-pdf-generation-options

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Feb 3, 2026 •
edited
Loading

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 multiple documentation structures:
    • Just-the-docs theme: <main id="main-content">
    • Legacy _site structure: <main data-pagefind-body>
    • Release structure: <div class="notes-margin">
  • Priority-based selection ensures accurate content extraction
  • Preserves document order: index, introduction, chapters, instructions, macros, commands, headers, tools, plugins
  • Handles nested HTML structures with depth tracking
  • Properly excludes navigation bars and sidebars in all structures

Documentation:

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

Compatibility:

  • ✅ Just-the-docs Jekyll theme (current documentation)
  • ✅ Legacy custom Jekyll templates
  • ✅ Archived release documentation

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.

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

Copilot AI and others added 5 commits February 3, 2026 08:45
@peterkir
Add HTML and PDF export scripts for documentation
ae74a72 
Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
@peterkir
Add .gitignore entries for generated documentation exports
93c1bfd 
Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
@peterkir
Fix HTML parser and add release export script
df61944 
Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
@peterkir
Add implementation summary and update export documentation
6d8dfc8 
Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
@peterkir
Add comprehensive usage examples for documentation export
c8a40e5 
Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
Copilot AI changed the title [WIP] Add options for creating HTML or PDF from docs Add documentation export to single HTML and PDF files Feb 3, 2026
Copilot AI requested a review from peterkir February 3, 2026 08:56
@peterkir
Copy link
Copy Markdown
Contributor

peterkir commented Mar 30, 2026

@copilot
Review the doc updates to Just-the-docs templates and assure that export still works and nav bar is considered in html and pdf exports.

Copilot AI and others added 2 commits March 30, 2026 07:07
Merge remote-tracking branch 'origin/master' into copilot/add-html-pd…
f26a395 
…f-generation-options

Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
@peterkir
Update export scripts for Just-the-docs theme compatibility
fe3f10c 
Agent-Logs-Url: https://github.com/bndtools/bnd/sessions/f984c310-80ca-4eb0-ab37-9e7d2186d4ed

Co-authored-by: peterkir <250545+peterkir@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Mar 30, 2026

@copilot
Review the doc updates to Just-the-docs templates and assure that export still works and nav bar is considered in html and pdf exports.

I've updated the export scripts to support the Just-the-docs theme migration (commit fe3f10c).

Changes made:

  • Enhanced HTML parser to recognize Just-the-docs structure (<main id="main-content">)
  • Maintained backward compatibility with legacy templates and release documentation
  • Added priority-based content extraction for accurate parsing

Tested compatibility:
✅ Just-the-docs theme (current): <main id="main-content">
✅ Legacy _site structure: <main data-pagefind-body>
✅ Release documentation: <div class="notes-margin">

The navigation bar is properly excluded from exports in all structures - the parser specifically targets main content areas and ignores nav/sidebar elements.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@peterkir peterkir Awaiting requested review from peterkir

Assignees

@peterkir peterkir

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@peterkir