Applying plugins: info breaks mkdocs serve

[TWiStErRob]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

https://squidfunk.github.io/mkdocs-material/bug-report/reproduction/#creating-a-zip-file says adding the info plugin will make mkdocs build create a ZIP. This is fine, but also mkdocs serve will do the same. This is unexpected as serve has a totally different purpose. While I agree serve needs to build before serving, the plugin would be much more useful if mkdocs serve continues to work as is even when the plugin is applied.

Use Cases

When reporting a bug, I would want to be able to see what the built page looks like before zipping it up. When the info plugin is added it's not possible to build any more, which is ok, but not being able to serve either means that I constantly have to add/remove the info plugin if I want to try something additional in the repro.

Screenshots / Mockups

No response

[TWiStErRob]

I just noticed this is also packaged into the zip file, so every time you (maintainers) use a repro, you have to remove the info plugin rather than just doing mkdocs serve.

[squidfunk]

Thanks for reporting. Yes, the info plugin is still very new, so it might still need some improvement. Only bundling on build is actually a good idea, as it simplifies introspection when using mkdocs serve, so we could consider this an improvement.

However (and this is a big one), it might lead to the problem where an author has the info plugin still configured, then deploys his docs (which will be built with mkdocs build, thus failing CI) and forgets about it. Thus, I'm not sure we really should alter the current behavior. Let me think about this and come to a decision. Further input appreciated.

[TWiStErRob]

I would say the "annoyance and toil" involved in the current behaviour outweighs the "someone might make a mistake" problem. If someone manages to push the info plugin to CI, they've checked in code to source control without reviewing it and expecting it to work. I think those cases could've pushed it even with the current behaviour and the failure will be the same.

[squidfunk]

What is the benefit for the author in implementing the proposed functionality? As a maintainer, yes, there's a benefit, but as an author? It's the last step you exercise in a reproduction.

[TWiStErRob]

I'm not sure about others, but when I author a bug report this is my workflow:

• discover the problem
• minimize the repro
• prepare artifact (to know what I'll upload)
• write the report in GitHub (or wherever) based on artifact
• revise the repro based on report (e.g. names might change for easier understanding of the problem)
• re-package artifact (if there were changes)
• test packaged artifact that the repro indeed reproduces
• upload
• revise wording in report
• submit

Development is always iterative, just as repro writing, and there's almost always some changes that have to be made to the repro. I collect mine here. From history you can't really see but there's always a git commit --amend before pushing the final version. As an example, while I was writing the report for #4884 I added/removed the plugin about 6 times for various reasons. For example the last remove: I packaged the artifact, uploaded it, then extracted and removed the plugin so that I can verify you'll be able to repro.

In addition to the iterative process, there's sometimes questions about the problem, and the reporter might need to revisit the repro, at this point they're after the last step in the repro process and need to remove the plugin (similar to a maintainer consuming the repro).
(This last thing can be also resolved by filtering the plugin from the example.zip.)

To take a step a back (might be a silly question), but:
Is there a reason for not creating another verb for packaging? e.g. mkdocs pack

[squidfunk]

Thanks for the detailed elaboration. Those are some valid points, and we want to make the bug reporting process as smooth as possible, so I agree that this might help iterating. So, why not support both? In c31ef00, I've added the behavior you requested: mkdocs serve will disable the info plugin by default. Additionally, this can now be configured with a new setting, similar to how drafts can be enabled and disabled in the built-in blog plugin with draft_on_serve:

plugins:
  - info:
      enabled_on_serve: true

Normally, configuring this should not be necessary, but keeping it configurable doesn't hurt.

Is there a reason for not creating another verb for packaging? e.g. mkdocs pack

Yes. We can't add new commands to MkDocs from within a theme or plugin. Thus, this would have to be added to MkDocs itself. Material for MkDocs is moving faster than MkDocs, which is why this is implemented here.

[squidfunk]

Released as part of 9.0.6.

[TWiStErRob]

Material for MkDocs is moving faster than MkDocs

I can see that from the open issue count :)

Thanks for this.

[squidfunk]

Yeah, that's exactly what the sponsorships allow: keep the project in good shape and fix bugs quickly.

[squidfunk]

Fixed another problem related to this issue in ad6c47d.