Configuring the Hosting Base Path in Xcode to Publish DocC Documentation on GitHub Pages

When working with the Swift-DocC framework to create rich documentation for your app development projects, you can leverage its latest features to make publishing the documentation as a static website on GitHub pages as easy as a breeze.

Since Xcode 14, you can share DocC documentation archives easier than ever. From the Product Menu select Build Documentation or use the shortcut ^⇧⌘D to compile the documentation archive. The documentation for your package or App project will then appear in the local developer documentation, from which you can easily export the documentation archive to share it with other developers.

Here, for example, this is shown with the SlothCreator framework Apple provides as Demo content for the DocC Framework.

It will be saved as a .doccarchive file, which can be opened by other developers and viewed directly in excode without any additional steps necessary. Inside the archive, there are actually all the needed files to render the documentation as a website that you could also host on almost any web server without any additional configuration.

If you do that with the example of the SlothCreator Swift Package, the documentation would be served under your specific domain as follows:

subdomain.your-domain.com/documentation/slothcreator
subdomain.your-domain.com/tutorials/slothcreator

Any documentation pages would be hosted under the /documentation/clothcreator path, while for example tutorials would be served at /tutorials/slothcreator.

However, if you want to host your documentation on GitHub Pages, this comes with an additional challenge, as a GitHub Pages site is not served at the root path but rather at a base path that corresponds to the repository name, such as:

username.github.com/repository-name

Consequently, the base path of the DocC archive needs to be adjusted so it can be accessed under this base path as

username.github.com/repository-name/documentation/slothcreator
username.github.com/repository-name/tutorials/slothcreator

Xcode 14 comes with a new build setting, that addresses this use case. Let's see how to configure these settings and publish documentation on GitHub Pages.

Become a free member or log in to proceed.