[Pitch] Experimental absolute hosting URL

Development Swift-DocC
1

Overview

I’d like to pitch an experimental feature/option to let authors provide the absolute hosting URL for documentation. Today, --hosting-base-path allows specifying a path prefix, but not the absolute host path. From the option's doc (p.s., which could be confusing to someone new to DocC, like here):

The base path your documentation website will be hosted at.
For example, if you deploy your site to
'example.com/my_name/my_project/documentation' instead of
'example.com/documentation', pass '/my_name/my_project' as the base path.

As discussed in swiftlang/swift-docc issue #779, the current option does not provide sufficient information for features that depend on canonical absolute URLs.

There are several use cases where DocC knowing the absolute hosting location is useful:

  1. Sitemap requires absolute URLs. Adding this feature would make generating the sitemap (which would be my subsequent pitch) for the DocC website easier.
  2. Social metadata (for example Open Graph canonical URL fields) requires absolute URLs.
  3. Establishing links to external documentation dependencies (that are not part of the developer's package documentation).
    1. …some work in this area has been added via --enable-experimental-external-link-support

My immediate goal is to unblock downstream sitemap generation workflows, but this feature could be useful beyond sitemaps.

Proposed Feature

Add an experimental argument to docc convert:

docc convert ... \
  --enable-experimental-hosting-absolute-path https://docs.example.com/path
  • --enable-experimental-hosting-absolute-path accepts an absolute URL (for example https://docs.example.com/path).
  • DocC validates that the path is absolute (scheme + host provided).
  • If provided, this value is treated as the canonical base for absolute URL needs, that take precedence over --hosting-base-path.
    • When both this experimental flag and --hosting-base-path are provided, the latter is ignored.
    • When both are provided, generate error log diagnostics to indicate that they are mutually exclusive.

Alternatives considered

  • Continue with --hosting-base-path only: insufficient for absolute URL requirements for sitemaps.
  • Add absolute URL support in swift-docc-render: harder to configure per documentation build and less aligned with DocC’s archive-generation context.
  • Pitch this together with the sitemap generation: I think the mutual exclusiveness of this and --hosting-base-path is pretty complex, better to be dealt as its own pitch.
  • *Only for sitemaps, if we cannot have the absolute hosting path, maybe a placeholder can be used for the absolute path. The intermediate sitemap output can be processed more easily with that.

Feedback request

Would like to hear feedback on

  • naming of this experimental argument
  • side effect and conflict with --hosting-base-path
  • other potential usecases and reasons to give an absolute path to DocC

Thanks @ronnqvist for providing initial feedback in swiftlang/swift-docc issue #779 and pointing me to the draft pitch message. This is my first time writing a pitch for DocC so feedback and comments are welcome!

*Human written, AI polished

3 Likes
2

Thanks for posting this pitch. I agree that it would be very useful for DocC to have a way of specifying the absolute location where documentation will be hosted (as opposed to only the path prefix which has some limitations). It also makes sense to me to talk about this addition separate to any of the use cases that it enabled.

I think it could be helpful to consider how we want people to configure the hosting location in the long term and then work backwards to how to reach that point.

One couple key questions that I think helps inform those long term plan are:

  • Do we want support for specifying both absolute urls and path-only values?
  • If there are use cases for both; which of the two do we try to emphasize and primarily steer people towards using?

As far as I know, the only use case for the current (path-only) base path configuration is to enable hosting environments without custom routing to serve pages at a deeper subpath. For example https://example.com/my-name/my-project/documentation/my-module. Hypothetically this path-only configuration makes it possible to deploy the documentation to two different servers at the same relative location (/my-name/my-project/) but I don't know if anyone does that or if that's an common enough or important enough use case to consider. Other than that, it would be possible for this use-case, but slightly less convenient to type out, the absolute https://example.com/my-name/my-project/ base location.

Considering that there are multiple use cases for specifying absolute hosting locations and that absolute hosting locations work for the current use case that only species a path prefix; it makes me think that:

  • in long term we could support only configuring absolute hosting locations
  • if we still want to support configuring only path-prefix hosting locations, the emphasis should be on specifying absolute hosting locations.

Assuming that's what we want to do in the long term; here are a few alternatives for how we could accomplish that:

1: Support absolute urls using the same option name as before

Keep the same --hosting-base-path as before but internally parse the provided value as a URL so that we can verify that it includes a host name component. To encourage developers to specify absolute hosting locations we would update the example in the command line help text. It's slightly unfortunate that the command line option name is called "path" if we expect more than that but it's probably not too confusing.

If we still support specifying path-only values for this flag, DocC would need to warn about those values as soon as the developer enables one of those features.

2: Support absolute urls using a different option name.

Introduce a new option for specifying absolute hosting locations. One direction that we could go with this option name is to be very explicit, for example --absolute-hosting-base-url or --hosting-absolute-base-url, so that the option name is almost self documenting for the type of values that it expects.

If we only support configuring absolute locations then I think either of those names are fine. If we also support path-prefix-only configurations using --hosting-base-path then one could argue that the emphasis is on path-prefix-only configurations because it's the shorter name. Another downside of having two different options is that there's slightly more validation logic and more confusion for developers about which option they should use for which use case. As a potential mitigation we could hide the current path-only option name, keeping it for backwards compatibility but otherwise encouraging that people use the new option instead.

3: Support both absolute urls and path-prefix-only values using a new option name

Introduce a new option for specifying both absolute hosting locations and path-prefix only hosting locations. Because the option would cover both, it probably needs more generic name like --hosting-base or --hosting-location. This ends up being rather similar to the first alternative but we get a chance to revisit the option name to get rid of the explicit "-path" mention. For backwards compatibility we might keep a hidden version of the old option name around and raise a warning anytime it's used.

With the choice of either keeping support for path-only base configuration or not—the alternatives described above can be summarized as these 5 alternatives:

  1. --hosting-base-path is only for absolute url values with no support for path-only values anymore
  2. --hosting-base-path is used for both absolute url values and path-only values
  3. some new option name is only used for absolute url values with no support for path-only values anymore
  4. some new option name is only used for absolute url values and --hosting-base-path continues to be used for path-only values
  5. some new option name is used for both absolute url values and path-only values

Once we know which direction we want to go with, we can figure out the steps necessary to get there and determine if we need to have an "experimental" transition period or not.