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

Configure all mike yaml options in `plugins:mike:`? #75

Closed nejch closed 2 years ago

nejch commented 2 years ago

Currently remote_name and remote_branch are configured at the root of mkdocs.yml. I think it might be clearer if all options were available in the plugins section, as they're really mike-specific and not mkdocs, even if they're not actually processed by the plugin.

It'd also maybe be easier to bring them closer to the CLI flags and prevent colliding with potential mkdocs-native options or other tooling, as they're scoped to mike. E.g. remote_name currently isn't 100% accurate, it can also be a URL, and same with remote_branch techinically, without --push it's a local branch. https://github.com/jimporter/mike/issues/51 is another candidate maybe.

So you'd have something like:

plugins:
  - mike:
      # these fields are all optional; the defaults are as below...
      branch: gh-pages
      remote: origin
      prefix: ""
      version_selector: true   # set to false to leave out the version selector
      css_dir: css             # the directory to put the version selector's CSS
      javascript_dir: js       # the directory to put the version selector's JS
      canonical_version: null  # the version for <link rel="canonical">; `null`
                               # uses the version specified via `mike deploy`

The only thing that feels a bit weird is that since it's not processed by the plugin I guess you'd have to set some dummy defaults there and duplicate them in load_mkdocs_config() I suppose :thinking: .

jimporter commented 2 years ago

Those settings are part of vanilla MkDocs: https://www.mkdocs.org/user-guide/configuration/#remote_branch. I think mike should consult those for compatibility purposes, especially since they're used via mkdocs gh-deploy, and mike deploy is really just a more-featureful version of gh-deploy. I think the current behavior is the right thing here.

If there are some values of either of these settings that work under gh-deploy but not with mike, that's a bug and it should be fixed. If you've come across a problem like that, feel free to file an issue about it.

nejch commented 2 years ago

Those settings are part of vanilla MkDocs: https://www.mkdocs.org/user-guide/configuration/#remote_branch. I think mike should consult those for compatibility purposes, especially since they're used via mkdocs gh-deploy, and mike deploy is really just a more-featureful version of gh-deploy. I think the current behavior is the right thing here.

If there are some values of either of these settings that work under gh-deploy but not with mike, that's a bug and it should be fixed. If you've come across a problem like that, feel free to file an issue about it.

Ah, I totally missed that. Thanks!