Simplyfiying the implementation of custom content (Support for Custom HTML)

[N3v1]

Feature Name

Support for Custom HTML

Description

I would like to propose a feature enhancement for the Swift DocC compiler to support the inclusion of custom HTML files, specifically header.html and footer.html, with the ability to apply custom elements to DocC documentations. This feature would greatly enhance the customization options for generated documentation.

The DocC compiler should be designed to automatically identify custom HTML files—such as header.html and footer.html—that are stored in a specified directory. By employing a wildcard search, the compiler can efficiently detect these files without requiring users to make manual adjustments to the build process. This approach simplifies management and integration for users who wish to incorporate multiple custom HTML files into their documentation seamlessly.

Furthermore, this enhanced functionality allows users not only to include these customized elements easily but also to style them using CSS. By leveraging CSS, users can ensure a cohesive and visually appealing presentation consistent with their branding across all documentation. This capability plays a vital role in creating a professional and unified look and feel, making the documentation more effective and engaging for its intended audience.

Motivation

Currently, the process of adding custom headers and footers to DocC documentation is not straightforward, which limits the ability to align documentation with project branding. By allowing users to include their own HTML files, we can create a more cohesive and branded documentation experience.

Importance

By streamlining this process, we could significantly enhance the overall usability of DocC documentation. Simplification would not only make it easier for developers to implement these features, but it would also open up greater flexibility and customization options. This would empower teams to align the documentation's visual aesthetics with their project branding more effectively.

A more user-friendly approach would allow developers to devote more time to content creation rather than getting lost in technical hurdles. Ultimately, investing in a streamlined process is vital for ensuring that documentation serves its purpose—providing clear, professional, and consistent guidance that reflects the essence of the project it represents. The potential benefits of such enhancements could lead to more engaging documentation experiences and stronger connections with users.

Alternatives Considered

No response

---

[Update 23/10/24 19:23]: While reviewing the pull requests, I found #1056, which introduces a custom-scripts.json file for managing custom scripts. This file can also be utilized to include HTML elements, allowing for greater flexibility in documentation customization. For instance, users could easily add their own header and footer HTML files through this configuration, streamlining the process of integrating custom elements into the generated documentation. For example, users can specify their custom HTML files, such as headers and footers, within the configuration like this:

{
   "htmlElements": {
       "header": "path/to/header.html",
       "footer": "path/to/footer.html"
   }
}

This approach can serve as an alternative to the previously mentioned wildcard detection method.

See the full pitch on forums.swift.org ...

[d-ronnqvist]

As has already been pointed out in the Swift Forums thread that you linked to: DocC already supports including custom header and footer HTML files gated by the --experimental-enable-custom-templates feature flag.