When building a Swift package framework, a developer might want to host their documentation online together with embedded web analytics or custom SEO metadata, to better understand how their users are using the documentation, or to improve the searchability of the webpages.
Currently there isn't a way to do these with DocC's CLI.
Would DocC team consider adding support to allow us to inject/embed custom sections when the static webpages are generated?
Thanks.
@marcus_ortiz could this be achieved with the current experimental support for custom header/footers?
Potentially the experimental custom header/footer could be used as a workaround for this type of functionality, yes, although I don't think it is necessarily a perfect solution to the larger desire here.
If a custom header.html file was used, it could contain a reference to a custom analytics script for example. One limitation would be that certain scripts like that might necessitate being loaded within the <head> element of the HTML file, which would obviously not be possible in the header, although it could work for a variety of other use cases.
The custom SEO metadata request couldn't be addressed with that same workaround due to that same limitation, so there would have to be some other tool injecting that kind of data into the generated HTML for now until a better system exists. (DocC-Render does provide some basic SEO metadata client-side but this isn't included with the generated static HTML at present)
The issue of not being able to customize <head> content has come up a few times in the docs workgroup too.
Recently, it was about wanting to include something like <meta name="robots" content="noindex"> for 'staging' docs or other cases where you might have duplicate sets of the same docs on the web at the same time. (Where you might not also control robots.txt or similar.)
@krilnon to prevent Google from indexing docs, wouldn't it be possible to add the <meta name="robots" content="noindex"> tag to the index.html file before pushing it to GitHub? This might mess up a CICD pipeline, but it could be a workaround if there's the possibility of doing it manually.
For analytics it could get trickier since AFAIK SPA needs additional setup to track the website correctly, adding a tag in the head will not be enough, and a package like vue-ua it's needed.
If there's interest in the capability of injecting tags to head when generating the docs it might be worth looking at GitHub - ktquez/vue-head: Manager the meta information of the head tag, a simple and easy way and using the theme-settings file to pass along the tags that the developer wants the website to have.
I understand the importance of analytics and custom SEO metadata when it comes to hosting documentation online. It's always helpful to have insights into how users are interacting with your content. Have you tried using a site SEO checker to analyze your documentation webpage? It's a great way to get a quick overview of your page's SEO performance and identify areas for improvement. As for your question about adding custom sections to DocC's CLI-generated webpages, that would be a great feature to have! I'm not on the DocC team, but it might be worth reaching out to them directly and suggesting it as a feature request.
@ethankusters or @marcus_ortiz can you share details (some documentation) on the experimental feature of custom headers/footers? I am unable to find how this works :(
Also, is there any update on adding custom metadata to documentation webpage through other means?
@ethankusters or @marcus_ortiz can you share details (some documentation) on the experimental feature of custom headers/footers? I am unable to find how this works :(
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. There are some potential issues with using a custom footer, as it will replace the default footer which has the color scheme controls. I think it might make sense to update the docs to highlight this though.
Also, is there any update on adding custom metadata to documentation webpage through other means?
There aren't any supported means for doing this at the moment that I'm aware of. Circling back to the original post, I don't think the custom header/footer would be a good way of adding this kind of metadata, since the header/footer would not be part of the <head> element.
To workaround this, I think you would likely need to directly modify the HTML that DocC produces to add this kind of metadata manually until there is a better supported way in the future.
Thank you for the information shared by you. Very helpful!