Skip to content

[6.3] Add CLI flag to enable DocC adding minimal per-page HTML content to each index.html file #1409

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
d-ronnqvist merged 2 commits into from
Dec 19, 2025
Merged

[6.3] Add CLI flag to enable DocC adding minimal per-page HTML content to each index.html file #1409

d-ronnqvist merged 2 commits into from
Dec 19, 2025

Conversation

@d-ronnqvist
Copy link
Contributor

@d-ronnqvist d-ronnqvist commented Dec 19, 2025

  • Explanation: This adds a new CLI feature flag so that developers can opt-in to an enhancement to the per-page "static hosting" index.html files (to include very minimal representation of the page's documentation content as semantic HTML inside of the <noscript> tag in order to make the pages more accessible to tools that don't evaluate JavaScript).
  • Scope: Feature flag for an off-by-default enhancement to the per-page "index.html" files in the output .doccarchive.
  • Issue: rdar://163326857
  • Risk: Low.
  • Testing: Added tests to verify the "index.html" files with content work well with the experimental custom header and footer support. Added tests that verify the CLI validation and its user facing warnings. Manually verified the behavior on DocC's library documentation (live demo here). Manually measured the archive size and performance impact. Existing automated tests continue to pass.
  • Reviewer: @anferbui
  • Original PRs:

d-ronnqvist and others added 2 commits December 19, 2025 09:42
@d-ronnqvist
Make a tiny simplification to the parameters HTML output (swiftlang#1387
9d0b830 
)
@d-ronnqvist @anferbui
Add CLI flag to enable DocC adding minimal per-page HTML content to e…
5a13f10 
…ach index.html file (swiftlang#1396)

* Add CLI flag to insert minimal HTML content in each "index.html" file

rdar://163326857

* Support index.html files that are missing the expected HTML elements

* Test that index.html files with content includes the hosting base path

* Support custom header/footer templates alongside the per-page content

* Remove properties that are never read

* Avoid HTML encoding difference between platforms in new test

* Add code comments about confusing test behaviors

* Apply suggestions from code review

Co-authored-by: Andrea Fernandez Buitrago <15234535+anferbui@users.noreply.github.com>

* Fix typo in test data

---------

Co-authored-by: Andrea Fernandez Buitrago <15234535+anferbui@users.noreply.github.com>
@d-ronnqvist d-ronnqvist changed the title Output html integrate 6.3 [6.3] Add CLI flag to enable DocC adding minimal per-page HTML content to each index.html file Dec 19, 2025
@d-ronnqvist
Copy link
Contributor Author

d-ronnqvist commented Dec 19, 2025

@swift-ci please test

@d-ronnqvist d-ronnqvist merged commit a497dee into swiftlang:release/6.3 Dec 19, 2025
2 checks passed
@d-ronnqvist d-ronnqvist deleted the output-html-integrate-6.3 branch December 19, 2025 12:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@franklinsch franklinsch franklinsch approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@d-ronnqvist @franklinsch