search

jimporter / mike

Manage multiple versions of your MkDocs-powered documentation via Git
BSD 3-Clause "New" or "Revised" License
553 stars 47 forks source link

Deploying to a subdirectory #42

Closed oprypin closed 3 years ago

oprypin commented 3 years ago

Normally, if I want to push a site to gh-pages under a /foo/ subdirectory, I could either literally put everything in that MkDocs site under such a subdirectory /docs/foo/, or I could use some deployment magic to just deploy directly to that subdirectory. Either way, it looks like: https://username.github.io/reponame/foo/bar.html

With mike, however, there's no deployment "magic", so I can't achieve https://username.github.io/reponame/foo/1.2.3/bar.html (unless I move the subdirectory manually every time after deployment)

I can only at best have this (via the MkDocs approach): https://username.github.io/reponame/1.2.3/foo/bar.html but it's not a good solution for the site I'm currently migrating, so I am asking for the ability to do the former.

Sorry about another feature request. Seems like it's the last one.

jimporter commented 3 years ago

That makes sense. It's probably not a super-common thing people would want to do, so I think it should be sufficient to provide a --prefix option for the various commands. It does require the person deploying the docs to remember that flag, but I'd guess that most projects whose docs are complex enough to need this would already be using an automated process to build their docs, so there won't be a lot of manual interaction with mike.

oprypin commented 3 years ago

@jimporter I'm trying out your commit b24149e271255e31c9e1b1595cd3a350876a7d7c here

and it works great but I found one issue.

Clicking the site logo in the top left corner brings you to /latest, not /prefix/latest.

jimporter commented 3 years ago

That's because of this line: 

site_url: https://oprypin.github.io/crystal-db/

The site_url would need to include the prefix for it to work right. I'm of two minds about this: on the one hand, mike already fixes up the site_url to account for the version number so maybe it should account for --prefix. On the other hand people might want to add a prefix for compatibility with some other step in their deployment process, so maybe mike shouldn't try to guess how the final result will be structured.

Edit: This also made me realize that the site logo always points to site_url rather than the root of the documentation (at least for the Material theme). I wonder if that's the right thing to do or not...

oprypin commented 3 years ago

Oh I'm sorry, you're totally right