Support SSG

[pepicrft]

Feature Name

Support SSG

Description

We are migrating Tuist's documentation to Swift DocC to integrate it more closely into the development workflows (we were using Docusuarus previously). To my surprise, Swift DocC renders client-side, and therefore, search engines, which rely on HTML markup, can't index the content of the documentation, which is not ideal because we'd like the project's documentation to be indexed by Google.

Motivation

Projects might want their documentation sites to be indexed by search engines. If I'm not wrong, Vue, the UI technology that's being used by Swift DocC, has SSR APIs to generate the markup and output JavaScript that can hydrate the dynamic elements once the page has been loaded. Alternatively, has the team considered using plain HTML with a templating solution and sprinkles of JavaScript?

Importance

It unlocks making Swift projects' documentation more discoverable, which I think is very desirable for open source maintainers who would love their projects to show up on Google results.

Alternatives Considered

I considered other alternatives like Vite Press, Vue Press, or Astro. However, as I said earlier, Tuist contributors love to stay as close as possible to Xcode and Swift, and using those other technologies adds friction.

[pepicrft]

We'd be happy to contribute this feature with some guidance from the Apple team.

[j-f1]

Hi! I’m actually working on implementing this. My plan is to have a separate script that renders each page in a Node.js environment and then snapshots the HTML once the rendering process is finished (including a few async tasks like syntax highlighting). Ultimately, the output is the same as the transform-for-static-hosting docc command, except that it fills the content into the generated index.html files rather than simply copying a template file.

There are also a couple of improvements that could be made to a few components to better handle the lack of scripting in browsers (for example, the sidebar needs virtual scrolling to work so that would have to be hidden, and the breadcrumbs in the navigation bar would need to be permanently expanded).

I reviewed a bunch of the existing SSR packages for Vue but they seemed to either require upgrading to Vue 3 (which I tried to do but discovered there are a ton of difficult-to-resolve breaking changes, got ~75% of the way through after 10 or so hours) or substantially changing the architecture of how the Vue app works (which I wasn’t comfortable doing).

[pepicrft]

Thanks a lot @j-f1 for the thorough update on this. Can we provide any support to get this to the finish line?
Also, out of curiosity, was it ever considered to have a simpler stack with templates and plain CSS and JS?

[j-f1]

Can we provide any support to get this to the finish line?

Take a look at #766 — it doesn’t have any of the actual prerendering logic but if you spot any issues with the no-js experience there I would love to hear about them :)

One particular area of interest for me is tutorials — right now it works ok, but the right side of the page always shows the first step in the tutorial. I’m trying to constrain any changes made for prerendering/no-js to produce the same HTML as the SPA so that hydration works properly, but maybe there’s a way to get the tutorial to work better with that constraint (or avoid that constraint entirely).

[j-f1]

Also, out of curiosity, was it ever considered to have a simpler stack with templates and plain CSS and JS?

Not sure about this. I will note that there are several interactive features (such as tutorials, tabs, and the whole sidebar/quick navigation UI) that would be difficult to implement without client-side JS, and also that the DocC build process can’t assume the presence of Node.js or a similar JS runtime so right now it basically “staples” the HTML/CSS/JS files for the web frontend to the JSON files derived from the Swift source code. So the stack would need to render the templates in Swift/C++ and then potentially re-render them in the browser.