Skip to content
This repository has been archived by the owner on Jun 1, 2023. It is now read-only.

Add the ability to inject HTML into the <head> #118

Open
sindresorhus opened this issue May 21, 2020 · 4 comments
Open

Add the ability to inject HTML into the <head> #118

sindresorhus opened this issue May 21, 2020 · 4 comments
Labels
design Functionality with a design component question Further information is requested

Comments

@sindresorhus
Copy link

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.
@mattt
Copy link
Contributor

mattt commented May 23, 2020

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.

@mattt mattt added design Functionality with a design component question Further information is requested labels May 23, 2020
@sindresorhus
Copy link
Author

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: realm/jazzy#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.

@Mordil
Copy link

Mordil commented Nov 26, 2020

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).

@Mordil
Copy link

Mordil commented Nov 26, 2020

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.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
design Functionality with a design component question Further information is requested
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@mattt @sindresorhus @Mordil