jimporter/mike

Manage multiple versions of your MkDocs-powered documentation via Git

mike's Issues

Add tests

Replace `mike install-extras` with an MkDocs plugin?

mike install-extras is fairly primitive, and just copies over some files to the docs dir. This makes it hard to keep up-to-date with any changes that might happen in the extras (see #33). One solution would be to provide an MkDocs plugin that does all the work of injecting the version selector and keeping the code up to date.

Versioning doesn't work if `site_dir` is set to a custom folder

The folder containing builds' output defaults to site but it can be changed to something else in mkdocs.yml using site_dir. In my case that param was set to public and Mike wasn't able to build the versioned docs tree in the gh-pages branch with no errors.

I think the problem might be in this function that assumes output must be collected from a directory called site.

I can change my output dir to site so it's not a big deal but the error is non obvious.

Deploying to a subdirectory

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.

JS file with Material Theme `install-extras` doesn't work

On a brand new mkdocs (1.1) and a new mkdocs-material (4.6.3) project, executing mike install-extras correctly installs the necessary elements, but the script installed doesn't work.
Looks like there is a typo in there - instead of loading the versions.json from the absolute URL, it tries to load it from the relative URL.. which at least in my browser doesn't work.

Keep mkdocs.yml formatting

A simple cosmetic issue, not important 🙂

I've ran mike install-extras in one of my repositories, and it reformatted my mkdocs.yml file.

• it removed double-quotes around strings. I guess this is just how YAML dumps works. If the string starts with a special character, it is enclosed in single-quotes, so this is safe.
• it indented items in arrays by 2 spaces (both are supported, but maybe this is recommended by YAML?)
• it added a css file and a js one, but the blank lines are wrong:

Before:

extra_css:
  - css/mkdocstrings.css

markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - pymdownx.superfences
  - pymdownx.emoji
  - toc:
      permalink: "¤"

plugins:
  - search
  - mkdocstrings:
      watch:
        - src/mkdocstrings

After:

extra_css:
  - css/mkdocstrings.css

  - css/version-select.css
markdown_extensions:
  - admonition
  - codehilite:
        guess_lang: false
  - pymdownx.superfences
  - pymdownx.emoji
  - toc:
        permalink: ¤

plugins:
  - search
  - mkdocstrings:
        watch:
          - src/mkdocstrings
extra_javascript:
  - js/version-select.js

Note the extra blank line between the two css files, and the missing blank lines before markdown_extensions and extra_javascript.

Would it possible to keep the formatting intact, and to fix these blank lines?

Does mike work with mkdocs-material

On Python 3.7.5 with these packages:

Click==7.0
htmlmin==0.1.12
Jinja2==2.10.1
jsmin==2.2.2
livereload==2.6.1
Markdown==3.1.1
MarkupSafe==1.1.1
mike==0.5.0
mkdocs==1.0.4
mkdocs-material==4.4.2
mkdocs-minify-plugin==0.2.1
mkdocs-versioning==0.1.0
packaging==20.3
pep562==1.0
pkg-resources==0.0.0
Pygments==2.4.2
pymdown-extensions==6.1
pyparsing==2.4.6
PyYAML==5.1.2
ruamel.yaml==0.16.10
ruamel.yaml.clib==0.2.0
six==1.12.0
tornado==6.0.3

mike's output looks like this for me:

Is this the expected styling?

This is from mkdocs.yml:

extra_css:
    - assets/css/extra.css
    - assets/css/version-select.css
extra_javascript:
    - assets/js/version-select.js

I've moved the files around, but not changed them. My .gitconfig is set up with user info.

mike list says:

$ mike list
0.0.2 [latest]
0.0.1

and the default docs are 0.0.2.

404 on image relative links.

Relative links show 404 for images while resolving for markdown_include tables. Using insiders for material, spent about a day trying to figure out what's happening (upgrade, downgrade, etc.) but cannot get these image links to resolve. They work fine in an mkdocs serve but fail to resolve in the mike serve.

Needs a demo

Possibly the most important thing when evaluating a project is the ability to see how the result looks. I wasn't able to find that.
I think it would be really useful to have some placeholder docs with a few versions generated in all the supported themes.

Changes to code not rendering during `mike serve`

Hello! First off, thank you so much for this amazing tool, it's helping me tremendously to add versioning to material theme with mkdocs.

Regarding this issue, I'm almost sure I'm just doing something wrong, but when I run mike serve, my changes are not rendering in the browser when I check my sources in chrome developer tools. I have installed mike and run mike install-extras. When I run mike list I have 1.7 and 1.7.1 [latest], and I've set my default with mike set-default latest. All that works fine, and I can see my dropdown in the sidebar nav. I'm trying to move the dropdown to live in the header, but my code is not picking up the changes. Not sure it's necessary, but I've also run mkdocs build and tried pushing my updated code up to my remote branch, neither of these solved my issue.

My file structure from root looks like:

mkdocs.yaml
versions.json
docs

js

version-select.js

Not sure what else to try or if I'm doing something wrong, thank you in advance!

Default to a better commit message

How to get started? README.md doesn't help.

Dear Contributors,

I use:

• mkdocs
• mkdocs-material

All is OK with mkdocs and mkdocs-material - everything is built and running both on local (with mkdocs serve) and on my web server - site by URL is fully functional!

And with mike:

1. I made git init in the source dir with my mkdocs material sources
2. Then, did add and commit
3. Then, run mike deploy 0.1 dev and mike deploy 0.2 new
4. I see that in my site_dir directory there are rendered web files
5. I deploy that web files to my web server,
6. I don't see the version selector
7. Then locally I do mike serve
8. Locally at http://localhost:8000 I see that version selector appears!!

What do I do wrong?

Why there are no explanations about such cases in README.md for those like me who are out of context?

• question: when I deploy new version, where that version is saved? git doesn't show any changes in the repo sources when I do deploy

Support more themes

Custom templates/index.html

How can I override the default templates/index.html with my own?

Not using GitHub pages or the gh-pages branch but a named branch from which content is copied to a CMS (Drupal).
I use a custom theme to create an HTML block for Drupal, so anything in <head> elements is ignored.
The default templates/index.html, where the script redirect is in the head, doesn't work.

--prefix argument not available in current pip release

This change adds the really nice feature of specifying a directory prefix. This is especially nice when using mike with GitLab since GitLab pages expect artifacts in a directory named public within the repo.

Are there any plans to make a new release sometime soon ?

index.html not collected by the build process

Hi,
I've just noticed that templates/index.html is not collected by the build process so the PyPI version is without it.

Can it support in github action flow

I hive config a github workflow like this:

name: Publish docs via GitHub Pages
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v1
        with:
          python-version: '3.7'
          architecture: 'x64'

      - name: Install dependencies
        run: |
          pip install --upgrade pip
          pip install -r ./requirements.txt

      - name: Mike Deploy 2.0
        run: mike deploy 2.0 -p  // I want to trigger mike deploy to gh-pages here

But it doesn't work, it out put an error like this:

How can I make it? thanks.

Error in deploying using mike - config not found

Hi,

I am trying to created versioned docs using Mike. I read that now there is a support for material theme. I did everything as per the readme.md but as soon I try to deploy I get the following error -
mike: error getting config:

My folder structure is:

Versioning(git repo tag: dev)
-->Versioned_docs
---->docs
----> mkdocs.yml
----> site\

I have done mike install-extras before deploy. Am I missing any obvious steps?

mkdocs.yml:

site_name: My Docs
theme:
  name: material
extra_css:
- css\version-select.css
extra_javascript:
- js\version-select.js

URLs in sitemap.xml do not include version part

When using mike for versioning, the URLs which are listed as part of the sitemap.xml do not include the version part. As an example, see the versioning demo I created, which suffers from this behavior:

Actual result:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url>
     <loc>https://squidfunk.github.io/mkdocs-material-example-versioning/</loc>
     <lastmod>2021-03-29</lastmod>
     <changefreq>daily</changefreq>
    </url>
</urlset>

Expected result:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url>
     <loc>https://squidfunk.github.io/mkdocs-material-example-versioning/0.4/</loc>
     <lastmod>2021-03-29</lastmod>
     <changefreq>daily</changefreq>
    </url>
</urlset>

This issue is more or less meant as a question where this is done by design or was accidentally forgotten. With the URLs not being correct, submitting the sitemap.xml to search indexes might not work as expected.

Does Mike work with GitLab Pages?

BrokenPipeError when running in Azure Devops Pipeline

@jimporter first off: lovely project!

I'm trying to deploy and publish in an Azure Devops pipeline, but I'm running into an BrokenPipeError. Locally everything works fine. Was able to pinpoint the error to stdin.write() when committing the files, but lack the knowledge of subprocess to solve it. I did print the filenames that are being committed and there is variation in when the error occurs, sometimes after the 2nd file, sometimes after the 5th, etc.

Both systems are ubuntu-20.04. Googling suggested it might be related to buffering, so inspected io.DEFAULT_BUFFER_SIZE and PYTHONUNBUFFERED and they are are the same locally and on the pipeline agent.

Any thought on what could be the issue?

+ mike deploy -u -F mkdocs/mkdocs.yml 0.1 latest
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/vsts/work/1/s/mkdocs/site 
INFO    -  Documentation built in 0.22 seconds 
Traceback (most recent call last):
  File "/home/vsts/work/1/s/mike/mike/commands.py", line 53, in deploy
    commit.add_file(f.copy(d, site_dir))
  File "/home/vsts/work/1/s/mike/mike/git_utils.py", line 202, in add_file
    self._write(file_info.data)
  File "/home/vsts/work/1/s/mike/mike/git_utils.py", line 172, in _write
    return self._pipe.stdin.write(data)
BrokenPipeError: [Errno 32] Broken pipe

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/vsts/work/1/s/mike/mike/driver.py", line 240, in main
    return args.func(args)
  File "/home/vsts/work/1/s/mike/mike/driver.py", line 77, in deploy
    commands.deploy(cfg.site_dir, args.version, args.title, args.alias,
  File "/home/vsts/work/1/s/mike/mike/commands.py", line 55, in deploy
    commit.add_file(make_nojekyll())
  File "/home/vsts/work/1/s/mike/mike/git_utils.py", line 165, in __exit__
    self.abort()
  File "/home/vsts/work/1/s/mike/mike/git_utils.py", line 220, in abort
    self._pipe.stdin.close()
BrokenPipeError: [Errno 32] Broken pipe
mike: [Errno 32] Broken pipe

Seperate build and deploy of docs

Hello,

i am a user of https://github.com/squidfunk/mkdocs-material and we upgreaded to the insiders version, whitch also support mike.
Now we want to upgrade our build pipeline(GH Actions) so that it use mike for the versioning.

In the old build pipelien we we did run mkdocs build --site-dir="../build/documentation" and then we manualy deployed it in a seperate step to gh-pages. Now we need to run mike deploy but then we can not seperate the building from commit and push and this is a bad behavor for our complex buildpipeline.

Is there any way to split this in to seperate stages?

For more information you can also look at our build pipeline:
Building: https://github.com/BetonQuest/BetonQuest/blob/de10a21e367ce3cc4d0fb330777bf36e775ebe00/.github/workflows/build.yml#L215
Deploying: https://github.com/BetonQuest/BetonQuest/blob/master/.github/workflows/build.yml#L271
Deploy Script: https://github.com/BetonQuest/BetonQuest/blob/master/.github/scripts/mkdocs.sh

The point is that we build our project parallel with maven and mkdocs, and if both are successfull we deploy both.

For me it yould be perfect, if i can run a mike build command and then run mike deploy

Deploying without `mike deploy`?

Presently I have the build output from mkdocs build deployed without using mkdocs deploy. I'm not sure if I can keep this workflow if adopting mike to add in versioned docs support though?

The present Github Actions workflow for deployment looks like this:

name: 'Documentation'

on:
  workflow_dispatch:
  push:
    branches:
      - master
    paths:
      - '.github/workflows/deploy-docs.yml'
      - 'docs/**'

# Jobs will run shell commands from this subdirectory:
defaults:
  run:
    working-directory: docs

jobs:
  deploy:
    name: 'Deploy Docs'
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2

      - name: 'Build with mkdocs-material via Docker'
        run: docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build --strict

      - name: 'Deploy to Github Pages'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/site
          user_name: 'github-actions[bot]'
          user_email: '41898282+github-actions[bot]@users.noreply.github.com'

• The peaceiris/actions-gh-pages@v3 action is preferred for generic deploys of build output.
• I'm using the docker container for mkdocs-material which simplifies maintenance, but it seems to use mike I'll need to include additional environment setup to add in python and pip install packages?

My understanding is that the main project docs remain as is, but mike will be managing versions with subdirectories of versions/aliases on the gh-pages branch, that it's using this branch to add the new build output to the configured location, and pushing that new commit for deployment?

Other mike features aside, does that mean as long as I mirror gh-pages in publish_dir location in my deployment action, and add my build to the correct version subdirectory, I'd have the equivalent of mike deploy?

A couple of questions

I am starting to experiment on versioning on documentation for a project and noticed today that Material now has a public release of Mike for versioning.

1: I have been trying to get it to work without having to push changes to GitHub and am having problems with doing that.

I have added

extra:
  version:
    provider: mike

in to my mkdocs.yml file and tried mike deploy 1.5 latest and it seems to build the documentation fine. However, when I use either mkdocs serve or mike serve, nothing changes. I don't see a dropdown to select a version or anything. When I do mike list, I see the versions that I have made.

2: I see that there is an area on the index page explaining that there is a way for me to be able to add pages to the documentation without being versioned. I am not clear on the procedure on how to do this though. I want to put a few paged in a non versioned like an index page, news page, FaQ page, and update log. I see that I should be able to put it in the root directory with mkdocs.yml but then it doesn't get included when building. Am I missing something in this area?

3: I have documentation for multiple versions already. Right now, I just have them in folders in /docs. To split them out in to Mike versions, do I need to just add them one at a time, push the version, replace the content with a new version, and repeat? If you need clarification on this, let me know.

4. If I need to edit a previous version, is there a way of doing that?

Redirect from the main index.html?

Add an "alias" command

This command would take a version and a new alias and make a copy of that version's docs for that alias.

Compatibility with mkdocs-redirects

mkdocs-redirects allows for creating redirect pages when a page's path changes. If example.com/foo/ is moved to example.com/bar/, the plugin generates an HTML page with a script that updates the location.href to cause the redirect (like set-default). However, since it is not aware that mike will place the generated content one directory down, the new href will be /bar/ instead of latest/bar/.

mkdocs-redirects does check site_url in mkdocs.yml to see if the site is hosted in a sub-directory. This means mike could write out an updated mkdocs.yml with the version appended to the value of site_url to specify the name of the sub-directory.

Namespace Error

Hey,
A simple issue.
When running mike without the --help flag, it errors:
mike: 'Namespace' object has no attribute 'func'

Issue on extra install: unhashable type: 'CommentedMap'

Hi!

Many thanks for maintaining that "plugin". I was looking for something similar for a while.

However when trying it I got an error upon executing this cmd:

mike install-extras

errror displayed

mike: unhashable type: 'CommentedMap'

The context:

mkdocs, version 0.17.3
Python 3.6.4
mike 0.3.1

Whatever the mkdocs.yml I am using I cannot get rid of this error...

Any thoughts?

Cheers!

Read `remote_branch` and `remote_name` from mkdocs.yml

I use privpage instead of gh-pages. Is that supported in mike?

URL without version doesn't render version select

We've talked about integrating support for mike into Material for MkDocs some time ago, and I was advocating against it due to its JavaScript-driven approach. However, I've reconsidered given the benefits of its lightweight approach and I believe it would be a good addition. I've managed to set up a small test site with two versions, and it works as expected.

– https://squidfunk.github.io/mike-test/latest/
– https://squidfunk.github.io/mike-test/0.2/
– https://squidfunk.github.io/mike-test/0.1/

However, when I open https://squidfunk.github.io/mike-test/ (without the version string), the request in the console fails:

This is clearly due to the way the integration is loading the version selector from one layer above:

mike/mike/themes/material/js/version-select.js

Line 24 in 39d6373

xhr.open("GET", ABS_BASE_URL + "/../versions.json");

My question is: is this by design? Or how should the root URL of a site be linked to the currently active, say (latest) version? I'd expect something like:

– https://squidfunk.github.io/mike-test/ -> https://squidfunk.github.io/mike-test/latest/

I think the best approach would be if mike would add a redirect similar to how the mkdocs-redirects plugin does it to the root of the project. Would that be a viable approach, or how'd you solve it?

Thanks for your efforts!

Rename the "rename" command to "retitle"

rename is a bit ambiguous, since it's really just updating the title.

Redirects works with JavaScript only

Currently people who visit the site without JavaScript enabled (and also probably some search engine robots) just see a blank page instead of being redirected.

For reference, currently a redirect page looks like this

<!DOCTYPE html>
<html>
<head>
  <title>Redirecting</title>
  <script>
    window.location.replace("../0.10.0/index.html");
  </script>
</head>
<body>
</body>
</html>

I would suggest adding a "META redirect" and also as a last resort just render a clickable link.
Even one of the two would help greatly.

A redirect page like this one has worked very well for me:

https://github.com/oprypin/crsfml/blob/1d98a31d96409e6b849e70414ac9407b7586d8f0/index.html

Cheers on using .replace in JavaScript, I hadn't realized that it's the better way, so don't take that part from me 😅

Can an alias ('latest') be a redirect instead?

When creating a "latest" alias for some version, can I make it redirect to that version, rather than just being an exact copy?

Well, I'm pretty sure the answer is currently "no", so this is a feature request.

---

Check out how this site (non-MkDocs) works:

https://crystal-lang.org/api/latest/Hash.html
redirects you to
https://crystal-lang.org/api/0.36.1/Hash.html
but that page contains <link rel="canonical" href="https://crystal-lang.org/api/latest/Hash.html">.

I've been following this topic for some time and concluded that this is good for SEO. And also good for the users, since they don't end up sharing a latest link assuming it's permanent, when it's not.

---

Mike has aliases, and they work quite nicely.

You'd run mike deploy 0.36.1 latest and get both /latest/Hash.html and /0.36.1/Hash.html pages, and I see that both of them have the same canonical of /0.36.1/Hash.html, which is good.

In fact, I can run it in a slightly weird way, mike deploy latest 0.36.1, and then the canonical points to /latest/Hash.html on both pages, which is what I want.

The only aspect that I don't like is that, well, /0.36.1/Hash.html and /latest/Hash.html are actual separate pages, rather than one redirecting to the other.

---

I could set up those redirects myself with some externally generated files, but would like to inquire about it as a feature first.

Running `install-extras` command changing contents of mkdocs.yml

Hey,

Running mike install-extras command changing the content of mkdocs.yml which should not happen, and even worse it making its formatting unsuitable for deployment. Please look into this ASAP.

mike-0.5.5 
mkdocs-1.1.2 
mkdocs-material-6.2.3

CNAME inclusion

Hey there,

Just wondering if the CNAME is supposed to be included out-of-the-box? Currently, the CNAME file is copied in each version directory, but it isn't included at the root of the directory. Please tell me if you want some more detail.

Feature request: Update an existing version

Hello and thank you for creating this neat utility!

Is there a way to update an existing version deployed with Mike? If not, is that in the future plans?

Use case: I'd like to keep an unreleased/develop version where mike would update such existing version upon merge requests. Another example is quickly fixing typos or any trivial content in the docs after it's already live. While I can delete and re-create the same version it can cause disruption.

I'd be happy to contribute after understanding the contribution guidelines and codebase.

Thank you!

Add trailing slash to version selector URL's

URL's in version selector need a trailing slash in order to be in line with other links in generated docs. This ensures that the relative paths to js / css always work. For me the URL's did not work when deploying to Azure blob storage, hosted as "static website".

This probably needs to be fixed in templates/redirect.html and version-select.js in both themes.
I can send you a PR for this if you like.

Similar to: squidfunk/mkdocs-material#2434

Error while deploying

I got this error while I was trying to run this command: mike deploy --push --update-aliases 0.1.0 latest (also, whith mike install-extras I got the same error)

Error: mike: 'charmap' codec can't decode byte 0x81 in position 167: character maps to <undefined>

Support more options for building the docs

We should provide more options for building docs to support cases like this, among others.

Instructions for GitHub Actions workflow

Hello again :-) I've been trying to use Mike with GH Actions to deploy a develop version upon pushes to the develop branch, and version specific upon a new release (i.e. 1.20.1), however pushing to develop is wiping out existing versions file assets.

The version file looks correct but every time develop branch is updated it wipes all sub-directories for other versions.

Am I missing a special parameter, sequence, or perhaps in this case I should always have an alias tied to a version like mike deploy --push develop unreleased?

Appreciate the help!

---

Here's a screenshot of the file structure before and after, and the GitHub action workflow:

New release works as expected

New develop release wipes out the previous version

Develop version workflow

Always builds the latest doc when pushing to develop branch

name: Docs

on:
  push:
    branches:
      - develop

jobs:
  api-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Set up Python
        uses: actions/setup-python@v1
        with:
          python-version: "3.8"
      - name: Install dependencies
        run: make dev
      - name: Setup doc deploy
        run: |
          git config --global user.name Docs deploy
          git config --global user.email [email protected]
      - name: Build docs website and API reference
        run: poetry run mike deploy --push develop

New release version workflow

Creates a new version and update aliases

name: Docs new version release

on:
  release:
    types: [published]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
    - name: Set up Python
      uses: actions/setup-python@v1
      with:
        python-version: "3.8"
    - name: Set release notes tag
      run: |
        export RELEASE_TAG_VERSION=${{ github.event.release.tag_name }}
        echo "RELEASE_TAG_VERSION=${RELEASE_TAG_VERSION:1}" >> $GITHUB_ENV
    - name: Install dependencies
      run: make dev
    - name: Setup doc deploy
      run: |
        git config --global user.name Docs deploy
        git config --global user.email [email protected]
    - name: Release docs website and API reference
      run: |
        poetry run mike deploy --push --update-aliases ${RELEASE_TAG_VERSION} latest
        poetry run mike set-default --push latest

Offline use case

Hi,

I'm using mkdocs material in a slightly different way, gradually expanding data in a site. We retain all the md, just add more and allow mkdocs to rebuild the whole thing each time.

Obviously over time this will become prohibitive so the idea of being able to push monthly blocks into the version style is very attractive.

Can mike do this, or do you have any plans for an offline model? Are you aware of any other tools that can do this?

Basically looking to work on folders locally rather than branches or tags:

edit: wrong key combination submitted above without example, sorry

./latest/md -> versions/2021.04/md
./versions/2021.01/md
./versions/2021.02/md
./versions/2021.03/md
./versions/2021.04/md
...

Replace `set-default` subcommand with a plugin option?

To help keep the default-version redirect up to date (and possibly add support for nice 404 handling), it might make sense to remove the set-default subcommand and instead manage the redirect via the MkDocs plugin.

Can mike add a banner for old doc versions?

Can mike add a banner to let users know that they are looking at an old version of the docs (similar to readthedocs)? If not, what would be a good way to implement this functionality?

EDIT: Maybe by outputting the banner as a markdown file which can be injected on a template block depending on the theme (e.g. mkdocs-material announcement bar)?

Make prefix configurable through mkdocs.yaml plugins

Hi @jimporter !

Thank your for mike, I am using its integration in mkdocs-material and it's great !

AFAIU, mike works by creating / building the documentation and committing it directly to a Git branch (defaults to gh-pages).

In our company we use mkdocs to create our internal documentation.
GitHub pages do not support "private" access and we used to build containers with the built documentation, setup behind an IdentityAwareProxy.

We are thinking about a workflow that would look like:

• Merge to main branch a documentation update
• CI kicks in and runs mike deploy to push the managed versioned doc to a dedicated custom branch
• CI kicks in again, triggered by this "release" branch,
  • builds a container,
  • pushes it to a registry
  • updates some deployment manifests that are also pushed back to GitHub
• CD kicks in, triggered by the deployment repo, and deployments happen.

To be able to do so, we are using the flag --branch and --prefix in all our command using mike.

Would it be possible to set these up in mkdocs.yaml to ease the usage ?

support material theme

Hi,
When I run mike install-extras i get

mike: theme 'material' unsupported

mike serve lacks `--prefix` flag

mike version 1.0.0 appears to lack support for the prefix flag, so one can't use that command if the built sites are stored under a prefix.

mike serve --help
usage: mike serve [-h] [-F FILE] [-r REMOTE] [-b BRANCH] [--rebase | --ignore]
                  [-a IP:PORT]

Start the development server, serving pages from the target branch.

optional arguments:
  -h, --help            show this help message and exit
  -F FILE, --config-file FILE
                        the MkDocs configuration file to use
  -a IP:PORT, --dev-addr IP:PORT
                        IP address and port to serve from (default:
                        localhost:8000)

git arguments:
  -r REMOTE, --remote REMOTE
                        origin to push to (default: origin)
  -b BRANCH, --branch BRANCH
                        branch to commit to (default: gh-pages)
  --rebase              rebase with remote
  --ignore              ignore remote status

Change doc order

I noticed that if you don't set-default version, you can't run mike serve successfully. Shall we change the doc order to remind the users？

Error while deploying with emoji.twemoji

I found the following error while trying to deploy a site with pymdownx.emoji extension enabled, python 3.7.3 and mike 0.5.3 on MacOS 10.15.7:

mike: could not determine a constructor for the tag 'tag:yaml.org,2002:python/name:materialx.emoji.twemoji'

The minimal reproducible example is a site with the following mkdocs.yaml

site_name: Test
markdown_extensions:
    - pymdownx.emoji:
        emoji_index: !!python/name:materialx.emoji.twemoji
        emoji_generator: !!python/name:materialx.emoji.to_svg
nav:
  - Home: 'index.md'

Relative links with respect to versions

Hi there. Before starting I just want to say that your library is great. It's definitely solving an important pain point. We're planning to use it for the next release of creme.

I just have a question with regards to links. In my MarkDown files, I have some links, such as [LinearRegression](api-reference/linear_model/LinearRegression). When I click on the links, it redirects me to localhost:8000/api-reference/linear-model/LinearRegression instead of localhost:8000/<insert_alias_or_version>/api-reference/linear-model/LinearRegression. Is there anything specific I have to do in order to enable the desired behaviour?

I'm happy to clarify if my query is confusing.