[Pitch] Adding Support for custom html elements in DocC

[N3v1 (Nevio Hirani)]

Pitch: Adding Support for custom html elements in DocC

• Author: Nevio Hirani (@n3v1)
• Status: Awaiting review
• Related Issue: Simplyfiying the implementation of custom content (Support for Custom HTML) · Issue #1072 · swiftlang/swift-docc · GitHub

Introduction

This proposal seeks to enhance the Swift DocC compiler by allowing the inclusion of custom HTML files, specifically header.html and footer.html, to enrich the customization options available for DocC documentation. The ability to include these custom elements will facilitate a more cohesive and branded documentation experience for developers.

Motivation

The current process for integrating custom headers and footers in DocC documentation is complex and not user-friendly. This complexity can hinder the ability of developers to align their documentation with their project's branding. By enabling users to include their own HTML files, we aim to create a more streamlined and flexible approach that enhances the overall user experience.

Proposed Solution

The DocC compiler will be enhanced to support two methods for including custom HTML files:

1. Automatic Detection: The compiler will automatically identify custom HTML files stored in a specified directory using a wildcard search mechanism. This will allow the detection of files such as header.html and footer.html without requiring manual adjustments to the build process.

2. Custom Scripts Configuration: Additionally, users will have the option to specify custom HTML files in a custom-scripts.json configuration file. This file can be structured as follows:

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

   This configuration allows users to easily integrate their custom HTML files into the generated documentation, streamlining the process of incorporating headers and footers without changing the way how the DocC Compiler works.

Importance

By streamlining the integration of custom HTML elements, we significantly enhance the usability of DocC documentation. This improvement will empower developers to focus on content creation rather than navigating technical hurdles, leading to a more efficient workflow.

A user-friendly approach to documentation customization will promote professional and consistent guidance, strengthening connections with users and enhancing their overall experience.

Conclusion

Incorporating support for custom HTML files in the Swift DocC compiler represents a valuable enhancement that aligns with the needs of developers. By simplifying the documentation process, we can ensure that users can create engaging and professionally branded documentation that accurately reflects their projects.

[Lucca-mito (Lucca de Mello)]

@N3v1

The current process for integrating custom headers and footers in DocC documentation is complex and not user-friendly.
[…]
Proposed solution
Automatic detection: The compiler will automatically identify […] files such as header.html and footer.html without requiring manual adjustments to the build process.

I believe that DocC already does exactly this (header.html, footer.html). Quoting @marcus_ortiz (source),

@marcus_ortiz

If you include the --experimental-enable-custom-templates flag when invoking docc convert, it will utilize the contents of a top-level header.html and/or footer.html file in your documentation catalog and inject it into the appropriate parts of the rendered documentation pages. This is lacking documentation at the moment due to its experimental nature.

Though the mechanism you’re proposing seems to be more general than that.

---

@N3v1

users will have the option to specify custom HTML files in a custom-scripts.json configuration file

If you’re referring to the custom-scripts.json proposed in this pitch, I’m not sure whether that would be the best place to declare custom HTML since that file is intended to declare custom scripts.

[N3v1 (Nevio Hirani)]

Hey @Lucca-mito,

Thanks for the clarification! I see where you're coming from, and I appreciate your reference to @marcus_ortiz ’s post regarding the --experimental-enable-custom-templates flag. You're absolutely right—this flag already allows developers to include header.html and footer.html files in the documentation catalog, which gets automatically injected into the rendered pages.

I think where the complexity lies, though, is in the experimental nature of this feature. Since it lacks clear documentation, many developers might not be fully aware of its availability or how to properly implement it. Making this process more visible and streamlined (outside the experimental flag) could be really beneficial for broader adoption.

@Lucca-mito

If you’re referring to the custom-scripts.json proposed in this pitch, I’m not sure whether that would be the best place to declare custom HTML since that file is intended to declare custom scripts.

Regarding your point about the custom-scripts.json file, I agree—it seems better suited for custom JavaScript configurations rather than HTML. If there’s going to be a way to handle custom headers and footers more generally, it may warrant its own separate configuration file or an explicit setting within DocC that isn’t tied to scripts (or even handled with a wildcard?).

I believe it’s essential to gather feedback from the community regarding their preferences for adding custom HTML files. Options like using --experimental-enable-custom-templates, implementing a wildcard search, or utilizing a configuration file could each offer unique advantages. Understanding the community's thoughts on these approaches will help us determine the most user-friendly and effective solution.

Whishing you a great day!
NH