The command `mike serve` does not work when the docs are deployed using `--prefix` flag

[chrimaho]

Summary

The command mike serve does not work when the docs are deployed using --prefix flag.

Configuration and Logs

Once you've built your docs, you can then deploy like this:

VERSION=v1.0.0
mike deploy --branch=docs-site --prefix=web --update-aliases $(VERSION) latest
mike set-default --branch=docs-site --prefix=web --push latest

This will deploy successfully. Then, if we wanted to check the serving while developing, we would run:

mike serve --branch=docs-site --prefix=web

But then we get the error:

mike: error: unrecognized arguments: --prefix=web

But then if I run it like this:

mike serve --branch=docs-site

It can't find the docs, because they're behind the web directory.

• Repository: private
• Platform: Windows 10 with WSL
• mike version: 1.1.2
• Commit generated by mike: N/A
• CI configuration: N/A
• CI logs: N/A

Expected Behavior

I'd expect that if I deploy the docs using the --prefix flag, I can then use this same --prefix flag in the serve command.

Thank you.

[jimporter]

If you go to http://localhost:8000/web, does it work?

[chrimaho]

Nope. Won't even get to that point.

[jimporter]

Have you set a default version for your docs? If not, you'll need to navigate to http://localhost:8000/web/$(VERSION) or http://localhost:8000/web/latest.

[chrimaho]

Yup, I have set the default version.

Okay, that worked now. I navigated to http://localhost:8000/web/, and it seemed to find my docs now:

Thanks for your suggestion :+1:

But it seems like a bit of a round-about way of doing it. Would it be easier to enable the --prefix flag for the mike serve command?

[jimporter]

The purpose of having a deploy prefix is mainly in order to support having multiple sets of documentation living side-by-side (e.g. example.com/foo-project/1.0, example.com/bar-project/1.0, ...). For that case, there's no benefit to a serve --prefix flag, and in fact it would likely just add extra confusion when serving the docs for testing.

The fact that your prefix is web/ is somewhat concerning though: it seems like you might be adding an unnecessary directory level. Does your gh-pages branch include any siblings of web/? If not, you should probably just drop the prefix entirely.

[chrimaho]

Makes sense. Thanks.

Actually, it is necessary for me to have the web/ directory there. I'm not using GitHub pages or GitLab pages. It's a completely different system all together, used for hosting static web pages. We have a process set up to curl push the docs to the server, and that process requires the docs to be hosted under a sub-directory on the repo. Hence why I've set it up like that.

I agree, it seems somewhat a little cumbersome, and I agree it'd be easier to just drop the prefix entirely. But, alas, I cannot.

Thanks for your suggestion though.

[jimporter]

Actually, it is necessary for me to have the web/ directory there. I'm not using GitHub pages or GitLab pages. It's a completely different system all together, used for hosting static web pages. We have a process set up to curl push the docs to the server, and that process requires the docs to be hosted under a sub-directory on the repo. Hence why I've set it up like that.

Couldn't you just check out the gh-pages branch into a subdirectory named web and then push that? That's probably a minor issue, but it'd make your repo a bit cleaner.

(More generally though, I wouldn't exactly recommend using mike with anything but Github pages. You could probably do all the things mike does in a better way if you had a server that you had a bit more control over. However, no one has made a tool to help manage that case, so here we are I guess...)

[chrimaho]

Nope, mike is working well with my solution 😉 I'm quite happy with it. This issue with the --prefix flag on the mike serve command is the first one I've come across. Actually, more of a confusion on my part than an issue really. Thanks for your hard work on this package 👍 it's great!