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.

Setting a Base Path for the DocC Archive in Xcode

Inside the Project Editor, choose the target you want to configure the base path for and select Build Settings from the top pane. Here you can edit the Documentation Compiler - Options and add the name of your GitHub repository as a value for the DocC Archive Hosting Base Path key.

Once configured, you can build the documentation again and export the DocC Archive for the project. It will be generated with the correct base path configured.

The content of the archive could then be placed in a directory such as a /docs folder within the git repository that is pushed to GitHub and then used by GitHub Pages to deploy the site.

To use GitHub Pages, you have to enable the GitHub Pages feature for your repository by navigating to the repository settings. Inside the left pane, you can select Pages. Then you can choose the git branch you want to use for hosting the static site. Then you have to select the folder in which the files for the page will be located. The default folder name is docs.

By adding the archive files to that folder inside the repository, GitHub will automatically deploy these as a page with the URL scheme username.github.io/repository-name/documentation/ once the files have been committed and pushed to the repository. Github will automatically deploy the static site through GitHub Pages.

That's it. If you want to know more about distributing documentation to other developers, check out the DocC Documentation in the official Apple Developer Documentation. To add DocC documentation to your Swift Packages, use the Swift-DocC Plugin and learn how to create documentation for Swift, Objective-C, and even C code since WWDC 2022. In our article "Using the Swift Package Manager command plugin for Swift-DocC", we cover the basics to get started.

We can't wait for more projects to adopt the DocC framework to leverage the same look and feel of the official Apple documentation with its new article and tutorial formats.