| [dash-dev] GSoC 2026: Technical Recommendation for Handbook Restructuring |
Hi Wayne and the Dash team,
Following our recent discussion, I have spent time analyzing the current build and prototyping an Antora-based solution. Here is my formal recommendation for the handbook restructuring:
1. Migration to Antora:
I recommend migrating the handbook source to the Antora framework. This will allow us to move away from the "massive single-page" model and provide a modern, searchable, multi-page UI. I have already successfully tested a local prototype using the Antora directory structure (modules/ROOT/pages).
2. Handling the Build System:
While Antora is Node-based, we can wrap the Antora execution inside the existing Maven lifecycle using the frontend-maven-plugin. This keeps the project "Maven-friendly" for existing maintainers while gaining Antora’s benefits.
3. Single-File PDF Requirement:
I propose a "Single-Source, Dual-Build" approach. We keep the .adoc files in the Antora structure but maintain a secondary Maven-Asciidoctor execution specifically to generate the "printable" single-file PDF. This ensures we don't lose the high-quality PDF output currently maintained by Wayne.
4. Automation of Document History:
I plan to incorporate the logic from the build.sh script into the Maven build (using a plugin like exec-maven-plugin) so that commits.adoc is generated automatically during the build, removing the need for manual shell scripts.
I would love to hear the team's thoughts on this approach.
Best regards,
Sakshi Chavan