Eliminate nesting of generated files for static hosting?

I'm generating my documentation using this command:

% swift package \
    --allow-writing-to-directory ./.docs \
    generate-documentation \
        --target Time \
        --output-path ./.docs \
        --emit-digest \
        --disable-indexing \

This is working great, except that the root index.html file shows "An unexpected error has occurred", produces a 404 to the /theme_settings.json file, and the actual documentation is buried at /documentation/time/index.html.

What is the point of this extra nesting of stuff, and how do I get rid of it so my docs generate at the root level, and not a nested folder?

Edit: I should note that I'm intending to host this documentation on GitHub Pages, so I do not have access to things like server rewrite rules, which I have seen mentioned around online.

1 Like

I have lots of similar questions but try checking out the --hosting-base-path parameter from Publishing to GitHub Pages. I'm guessing you'd want --hosting-base-path time. I've hosted stuff successfully after following this article. You still won't be able to just open the index.html and view the site but it'll work on GitHub pages.

I did see that article, but later on it says:

I'd like to eliminate the last two path parameters.

My full configuration is here: time/.github/workflows/docc.yml at main · davedelong/time · GitHub


I would recommend keeping the target name, since a single package can expose multiple modules. Even if your package only has a single module today, you may want or need to add others later (for reasons that we can't predict).

I think the documentation component is there because that's how Apple's developer site is structured - e.g. https://developer.apple.com/documentation/swift/string, and it's just hardcoded in. It would be nice to remove that for other sites.

1 Like

A reason for the documentation component is that the archive could contain tutorials which have the same second path component (based on the archive's "display name" which may be derived from the module name).

One solution to that could be to only add the documentation component if the archive contains tutorials but that may result in all the pages moving if you decide to write a tutorial at a later point.

An alternative to that would be to remove it for documentation but not for tutorials but that would be a bit inconsistent.

1 Like