swift-doc
swift-doc copied to clipboard
SwiftDocOrg
Add the ability to inject HTML into the `<head>`
This can be useful for multiple purposes:
- Adding analytics
- Quickly modifying the docs site with some quick JS/CSS
- Dynamically adding some extra content
Jazzy solves this with a head option: https://github.com/sindresorhus/KeyboardShortcuts/blob/498fcd6cc1562313b5e3aa97b35430cfb2c91292/.jazzy.yml#L13-L19
Personally, I would use a more verbose option name.
I'm sympathetic to wanting to customize the output, and that's something I want to have a good story for. Allowing custom HTML to be injected into the <head> is one option, but I want to see if there are any better options available.
For example, looking at your specific usage:
<script>
window.addEventListener('DOMContentLoaded', () => {
document.querySelector('.header-link[href^=dash-feed]').remove();
});
</script>
It looks like this is removing a link to the Dash feed that's put there by Jazzy. It's never a good sign when one feature of software is used to disable another feature.
Analytics
- Adding analytics
I've seen a hosts like Netlify add this as a feature of their build system, and I suspect that the JavaScript has at least a few utilities that make this easy.
- Quickly modifying the docs site with some quick JS/CSS
For something like this, I'd want to consider support for custom themes / assets wholesale. Or, in the meantime, my recommendation would be to fork and customize directly in source.
- Dynamically adding some extra content
I'd actually be really curious to hear any examples of things someone might want to add. I'd love to get a better understanding of more things the generator could do / what features someone might want to delegate to a static site generator.
Allowing custom HTML to be injected into the
is one option, but I want to see if there are any better options available.
There are probably better specific solutions for many of these use-cases, but the benefit of the head config is that it allows doing almost anything. So it lets us do things SwiftDoc doesn't currently support or will never support.
It looks like this is removing a link to the Dash feed that's put there by Jazzy. It's never a good sign when one feature of software is used to disable another feature.
It's there to work around a Jazzy bug: https://github.com/realm/jazzy/issues/1188
So I guess that's another use-case: Temporarily work around SwiftDoc bugs.
For something like this, I'd want to consider support for custom themes / assets wholesale. Or, in the meantime, my recommendation would be to fork and customize directly in source.
I don't want to maintain a fork of a theme though. I just want to do some minor adjustments. Another solution would be to let me specify additional CSS content/files that are then merged with the default CSS at build time.
I'd actually be really curious to hear any examples of things someone might want to add.
Some things to comes to mind:
- Adding ads (😫, but sometimes necessary)
- Adding sponsor company logos (for GitHub Sponsor supporters)
- Adding some extra navigation buttons, for example, a button to the main website, a button to support forum, etc.
- Injecting a project logo.
- Injecting a runnable code example, for example, something like https://runkit.com/
- Add functionality that SwiftDoc has declined to add.
- GitHub stars badge.
- Link to localized version of the docs (for now, until SwiftDoc supports localizations)
And yes, some of these things could be supported by default, but that will take time, and that's exactly how the head thing is useful. It lets us do things today instead of waiting (possibly forever) for SwiftDoc to add it.
One of the things that some custom HTML injection is usually needed for w/ Jazzy is the ability to have several packages with their relationships cross-linked in their documentation.
For example, SwiftNIO has several repos and packages that they offer, and to link their documentation together they have a plain index "homepage": https://apple.github.io/swift-nio/docs/current/NIO/index.html
Vapor does this with a dedicated page and a dropdown: https://api.vapor.codes/
In addition, multiple API versions might be wanted to be generated, such as for 1.0 & 2.0 with a quick way of knowing which version of the API you're looking at, and how to switch to a different version (this relates to #120 somewhat).
Orthogonally, what I'd love to see is the ability to provide cross-linking / documentation of dependencies, so that our project's documentation feels much more akin to Apple's documentation.
When I type
/// This requires a `NIO.SocketAddress` and a `String`
having hotlinks to NIO's SocketAddress and Swift's String would be very nice - but I know that is a huge undertaking on its own with tons of edge cases and a few ways to solve them.