search

jimporter / mike

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

Allow the default version to be served at the root #83

Closed ofek closed 2 years ago

ofek commented 2 years ago

Basically, the counterpart of https://github.com/squidfunk/mkdocs-material/pull/3252

This would be indicated by the empty version string or some other identifier.

When mike updates the default version, it will first wipe the directory, excluding directories matching any versions in versions.json.

jimporter commented 2 years ago

mike is careful to keep each version as siblings in the directory tree to prevent path conflicts. The current restriction on version strings to is intentional to keep those problems from coming up.

ofek commented 2 years ago

Right, but wouldn't that be user error?

jimporter commented 2 years ago

Sure, but it's easy to prevent this class of error entirely, so that's what mike does.

ofek commented 2 years ago

Okay then do you know of any way to alter the URL to be / for the default version?

jimporter commented 2 years ago

I'd recommend against doing so in the first place. If you're trying to set up a permalink to the latest version of your documentation, that's handled by aliases. For example, you could set up a latest alias that points to the latest released version of your docs, and then links to example.com/latest/page/ would always point to the current docs. You can also set the default version to be latest so that users visiting example.com get redirected to example.com/latest/.

However, there's not an easy way to specifically put your docs at your server root. If you're using a real webserver, you might be able to write some Apache redirects that do what you want.

jimporter commented 2 years ago

Just to explain a bit more about why this is more complex than it would appear, and hence why I won't be changing the current behavior.

In order to keep the docs clean for a given version (e.g. remove stale pages), mike generates Git commits by first deleting all the files in that version's directory, and then adding the new versions of all of them (Git is smart enough to simplify this diff as much as possible). However, if a version were stored at the root directory, then cleaning the directory would delete the entire site, including any versions that live in subdirectories and any "extra" files the user added manually, such as CNAME (see the README for a brief discussion about this). Before this was fixed, this resulted in users experiencing broken behavior with mike; see https://github.com/jimporter/mike/issues/49#issuecomment-809575314 for example.

Now, for other versions of the docs, mike knows they exist and could theoretically be enhanced to avoid deleting them. This would be possible, but non-trivial, since mike currently only has to say "delete this entire directory" when generating the commit. Deleting everything but certain files would be significantly more work. Even so, that wouldn't address the issue of special files like CNAME that the user manually added. That part could be worked around by deploying CNAME when deploying the "" version to the site root, but the obvious way to do that results in odd behavior: normally, MkDocs would have you put the CNAME file in your docs/ dir, but then deploying to a named version would put a CNAME file at example.com/1.0/CNAME. That probably wouldn't hurt anything (at least not in this case), but it's unexpected and serves no real purpose.

pan3793 commented 1 year ago

I'm also looking forward this feature. Or, is there a workaround to pin "some pages" in root?