THE GITHTML FIELD GUIDE
Distinguish DocC static hosting from portable HTML
Static hosting means a server can serve generated files without running a documentation generator for each request. It does not necessarily mean every DocC page is an independent script-free HTML document. Check your toolchain’s output and supported hosting options, preserve the archive’s resources, and test the actual reading environment before promising portable offline use.
Separate server requirements from page behavior
A static host can serve HTML, JavaScript, stylesheets, images, and data files. A browser application can run from those files while still depending on scripts and additional requests. That is different from a single HTML document containing all essential prose and styling.
DocC has evolved its static-hosting and static-content capabilities over time. Avoid treating an old transformation command or a recent experimental feature as a universal requirement for every installed Swift version.
Record the actual toolchain and destination
Note the Swift or Xcode version, plugin version if used, archive source revision, and intended hosting path. Consult the documentation matching that setup. A project served below a path prefix may need different configuration from one served at the domain root.
Use the project’s documented local build procedure and inspect the resulting archive. Do not run a transformation over the only copy of an important archive simply because an older tutorial recommends it. Keep experiments in a separate dedicated output location.
- Record toolchain, plugin, source revision, and intended hosting path.
- Inspect the actual archive and test a deep route through local serving.
- Check script-disabled reading separately before making portability claims.
Test the generated edition concretely
Open a deep documentation route through the intended local serving environment. Inspect whether the page’s essential content is already in its HTML or depends on rendering data and scripts. Check images, symbol links, and direct navigation.
If the goal is script-disabled reading, perform that check explicitly. Recent static-content work does not justify assuming every theme, toolchain, or page has identical capabilities. Describe what you observed for the exact build rather than making a blanket statement about DocC.
Pick an honest distribution promise
For a full documentation site, preserve its resources and state its serving requirements. Hosting is a separate publication decision requiring the owner’s approval. For gitHtml, do not equate indexed .html paths with support for a complete DocC web application.
When a team needs only a portable overview or operational guide, produce a simple companion document with inline CSS and essential content in the markup. Link back to the authoritative API reference and state the companion’s scope, source version, and known omissions.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.