Sitemap for DocC Hosted Website

game-swoosh commented 10 months ago

Feature Name

Description

It seems that DocC does not generate a sitemap. When I navigate to a hosted DocC on a website, I would expect to see sitemap with a list of all the individual links.

I also tried searching for the sitemap at Apple's Documentation site which is made with DocC at this URL: https://developer.apple.com/documentation/technologies

I can't seem to find it at Apple's Documentation site either. If it does exist, apologies for not seeing it.

Does this exist and if not, is it something that will be added?

Motivation

No response

Importance

No response

Alternatives Considered

No response

natikgadzhi commented 10 months ago

I think that swift-docc-render should be responsible for the sitemap, as it's a web artifact, and docc itself just generates the inputs for it, right?

adam-rocska commented 10 months ago

@natikgadzhi && @game-swoosh : Definitely, this is for the renderer.

mportiz08 commented 9 months ago

Does this exist and if not, is it something that will be added?

This is not something that exists today.

I think a sitemap could potentially be a useful addition, but there are a couple of interesting quirks that may make it difficult to implement in the renderer itself:

while the .doccarchive artifact produced by DocC can be hosted as a standalone website, it can also be integrated into an existing website, so there could be some conflict with any sitemap generated for the docs and an existing website that it is being integrated into on the hosting side (probably not the common case though, so maybe not a big issue)
DocC-Render purposefully doesn't have any build process so that a single prebuilt version of it can be shared with n number of built documentation artifacts. This means that you don't need to have node installed (etc) on your system or as part of the doc compiler to actually build your documentation catalog, which is nice, however it means that DocC-Render doesn't really have any logic that can run as part of generating the website artifact, which would be needed to create something like a sitemap tailored to an individual documentation catalog
I think absolute URLs are usually expected in a sitemap and DocC-Render doesn't necessarily know where it's going to be hosted (could be multiple places even), so there would also need to be some build logic to configure the endpoint where the content will actually be hosted

If someone were to look into supporting this as a new feature/enhancement, I imagine that it may be much easier to implement in DocC itself—the logic used to generate the RenderIndex JSON file (which powers the sidebar navigation) would likely be very similar and maybe even tweaked to also generate a sitemap, since the data would be pretty similar.

d-ronnqvist commented 9 months ago

@mportiz08 Sounds good. I'll transfer this issue back to DocC.

Jeehut commented 2 months ago

Hey 👋, would like to add to the discussion that a sitemap could help a lot with SEO. In particular, I'm using DocC for the new design of the wwdcnotes.com website, but Google doesn't seem to find a sitemap. Not sure if it'll be able to find all notes, the Search Console seems to struggle. So I'd love to see this feature as well. 👍

adam-rocska commented 2 months ago

@Jeehut Aren't we yet used to having bad SEO for anything Swift related? I thought it's our style 😅

before anyone would take it seriously: it's just a joke I couldn't resist

swiftlang / swift-docc