8000 Make extra.version.default match against the version string by raymond-u · Pull Request #6302 · squidfunk/mkdocs-material · GitHub
[go: up one dir, main page]

Skip to content

Conversation

@raymond-u
Copy link
Contributor
@raymond-u raymond-u commented Nov 6, 2023

Currently, the extra.version.default configuration option only matches against aliases and not the actual version string.

This can be cumbersome in the following scenario:

extra:
  version:
    provider: mike
    default:
      - nightly
      - stable

In this case, nightly is used as a version string, while stable is an alias pointing to an actual version number. The goal is to suppress the outdated message header for both of them. If extra.version.default matches both the version string and aliases, I can simply deploy with:

mike deploy nightly
mike deploy --update-aliases 0.1 stable

Without this fix, a workaround is required, such as using mike deploy nightly continuously.

@squidfunk
Copy link
Owner

Thanks for the PR. I'm not feeling comfortable just merging this through. I also wasn't aware that you can use a string as a version. Could you please explain what your workflow is and how you use mike to deploy your docs? We need to make sure that this change does not break other users' docs.

@raymond-u
Copy link
Contributor Author

Sure. I have two GitHub Ac B0DA tions workflows named docs_nightly.yaml and docs_stable.yaml, which look like this:

name: Docs nightly
on:
  push:
    branches:
      - main
jobs:
  deploy-docs:

    ...

    - name: Deploy docs
      run: mike deploy --push nightly

and

name: Docs stable
on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
jobs:
  deploy-docs:

    ...

    - name: Deploy docs
      run: |
        mike deploy --push --update-aliases ${{ steps.docs_version.outputs.docs_version }} stable
        mike set-default --push stable

Running these workflows would generate the following version.json:

[
  {
    "version": "nightly",
    "title": "nightly",
    "aliases": [],
  },
  {
    "version": "0.1",
    "title": "0.1",
    "aliases": ["stable"]
  }
]

If extra.version.default only matches against aliases, I would need to set up an additional alias, such as continuous, and use mike deploy --push --update-aliases nightly continuous to publish the nightly docs, which is not very ideal.

If there is any other information you would need, just let me know!

@squidfunk
Copy link
Owner

Thanks for the explanation. I don't see why this should break anything for existing users, as we're only adding an additional name to the version strings to check against which must be explicitly listed in extra.version.default. Thus, we'll merge this PR and revisit it if we find out that it breaks something downstream.

@squidfunk squidfunk merged commit e4d1353 into squidfunk:master Nov 12, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

0