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.