# DocC render with a static HTML generator?

**URL:** <https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866>\
**Category:** Swift-DocC\
**Tags:** question\
**Created:** [August 9, 2024, 2:53pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866 "2024-08-09T14:53:22Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![featherless](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/featherless/32/36808_2.png) [@featherless](https://forums.swift.org/u/featherless)\
**Post date:** [August 9, 2024, 2:53pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/1 "2024-08-09T14:53:22Z")

</div>

Hello! I've been following along with DocC's development since it was announced publicly and I love so many things about it, thank you for making such a great tool for the technical writing community! I've been especially loving how easy it is to make interactive tutorials ([Introducing Slipstream](https://jverkoey.github.io/slipstream/tutorials/introducingslipstream)).

I saw that [DocC-render](https://github.com/swiftlang/swift-docc-render) is built in Vue.js, which I suspect is particularly helpful for some of the interactive aspects of the site (tutorials).

It's gotten me wondering though, especially as I've been working on [Slipstream](http://github.com/jverkoey/slipstream/), whether DocC might be more accessible to the Apple dev community if the renderer were built in something closer to SwiftUI that would emit static HTML with less reliance on JavaScript as a nice side-effect.

Before I dive too deep into this though (my nerd-snipe senses are tingling on this one), I wanted to post the idea/question here and get a sense of whether I'm completely off the mark! Happy to poke at this with others and see if there's something here.

---

<div class="post-metadata">

**Author:** ![featherless](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/featherless/32/36808_2.png) [@featherless](https://forums.swift.org/u/featherless)\
**Post date:** [August 9, 2024, 3:20pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/2 "2024-08-09T15:20:52Z")

</div>

Looks like the starting place might be to manually generate the symbol graphs, which emits json files that I can then read into a Slipstream site generator: [swift-docc/CONTRIBUTING.md at main · swiftlang/swift-docc · GitHub](https://github.com/swiftlang/swift-docc/blob/main/CONTRIBUTING.md#assembling-symbol-graphs-and-building-with-docc-directly)

What an enticing rabbit hole this is 😅😅😅

---

<div class="post-metadata">

**Author:** ![featherless](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/featherless/32/36808_2.png) [@featherless](https://forums.swift.org/u/featherless)\
**Post date:** [August 9, 2024, 3:21pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/3 "2024-08-09T15:21:38Z")

</div>

[GitHub - swiftlang/swift-docc-symbolkit: A Swift package for encoding and decoding Swift Symbol Graph files.](https://github.com/swiftlang/swift-docc-symbolkit) also seems handy for parsing the json output.

---

<div class="post-metadata">

**Author:** ![QuietMisdreavus](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/quietmisdreavus/32/18057_2.png) [@QuietMisdreavus](https://forums.swift.org/u/QuietMisdreavus)\
**Post date:** [August 9, 2024, 3:47pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/4 "2024-08-09T15:47:16Z")

</div>

The symbol graph is a compiler output that reflects the available symbols in a package or framework target. If you want to handle DocC's output to convert it into something else, you'll probably want to inspect the Render JSON it outputs, as reflected by the [RenderNode](https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/Model/Rendering/RenderNode.swift) type and in the [OpenAPI specification](https://github.com/swiftlang/swift-docc/blob/main/Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json) we maintain for it. This is what Swift-DocC-Render consumes to display a documentation site.

If you want to bypass Swift-DocC and generate documentation output yourself, you might also be interested in @taylorswift's [swiftinit](https://swiftinit.org/) and [swift-unidoc](https://github.com/tayloraswift/swift-unidoc) projects, which do this to host documentation infrastructure.

---

<div class="post-metadata">

**Author:** ![featherless](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/featherless/32/36808_2.png) [@featherless](https://forums.swift.org/u/featherless)\
**Post date:** [August 9, 2024, 4:41pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/5 "2024-08-09T16:41:38Z")

</div>

Thanks for sharing those links! @taylorswift: your projects are similarly rendering HTML it looks like; do you think something like Slipstream could make it easier to iterate on the generated HTML? Wondering if there's a way to consolidate all of these site renderers onto a common Swift-friendly community solution 🤔

---

<div class="post-metadata">

**Author:** ![taylorswift](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/taylorswift/32/43413_2.png) [@taylorswift](https://forums.swift.org/u/taylorswift)\
**Post date:** [August 9, 2024, 10:32pm UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/6 "2024-08-09T22:32:10Z")

</div>

> [@featherless](#):
>
> Thanks for sharing those links! @taylorswift: your projects are similarly rendering HTML it looks like; do you think something like Slipstream could make it easier to iterate on the generated HTML?

Swiftinit itself is not a ‘static’ site, and it currently uses [swift-dom](https://github.com/tayloraswift/swift-dom) to generate all of its HTML, almost all of which is dynamic.

Swiftinit can export static HTML through its [rendering API](https://swiftinit.org/help/exporting-articles), @tiborbodecs and @Joannis_Orlandos are currently using it to generate the [swiftonserver.com](https://swiftonserver.com/) site, although the export system is intended to be used for “long form” documentation like articles and tutorials rather than API references.

the external rendering system as it currently exists yields one HTML page at a time, as far as i am aware Tibor and Joannis are doing something extra to collate those pages into the swiftonserver website. they may (or may not) have a use for a tool that can assist with that.

---

<div class="post-metadata">

**Author:** ![tiborbodecs](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tiborbodecs/32/32508_2.png) [@tiborbodecs](https://forums.swift.org/u/tiborbodecs)\
**Post date:** [August 10, 2024, 11:08am UTC](https://forums.swift.org/t/docc-render-with-a-static-html-generator/73866/7 "2024-08-10T11:08:13Z")

</div>

Actually, I have a static site generator written in Swift that can do the job. We integrate the rendered HTML content (generated by the SwiftInit service) into our build pipeline; that’s how [swiftonserver.com](http://swiftonserver.com) is made. The DocC articles are part of a separate repository, and we simply use the render API (mentioned above) to import the HTML along with some additional markdown content and YAML metadata to process everything. Feel free to take a look at our [repository](https://github.com/BinaryBirds/Toucan/tree/dev). The project is still a work in progress, but we are already looking for user feedback. :)
