Web server

[karl-johan-grahn]

Can you please clarify, to host the documentation in production with a web server such as nginx, is it enough to just host the content from the gh-pages branch? Is the content there self-contained such that it will that add the version selector too for example? Or do I need to serve the content with mike serve to get the version selector?

[jimporter]

Yes, in order to work on Github Pages, the gh-pages branch is a complete static site, so as long as you serve those pages, everything should work (assuming your server is sufficiently similar to Github's; in particular, watch out for things like redirects, 404 pages, etc).

That said though, if you're not hosting on Github Pages, mike really isn't the best tool to help deploy documentation. Deploying generated documentation to gh-pages is really just a hack in order to make Github happy. Since generated docs are a build/release artifact just like a compiled binary, they don't really belong in your Git repo. With a real server that you control, you could build a more-proper deployment pipeline for all this. Still, that's probably more effort than just using mike and trying not to worry about it.

As for mike serve, you should never use it unless you're just testing things out locally to make sure it looks ok; it's not a production-ready server, and likely has security issues (it's just the Python standard library's HTTP server).

[karl-johan-grahn]

Thank you for quick response. Yes, tried it with nginx and it works as expected. As you say I don't necessarily need to use the content in the gh-pages branch but can treat deployments as release artifacts. Mkdocs' 404.html ends up in each versioned subdirectory - do you have any advice how to handle that?

[karl-johan-grahn]

It can be done with something like this in nginx:

error_page 404 @error404;
location @error404 {
  rewrite ^/(.*)/ /$1/404.html last;
}