search

backstage / mkdocs-techdocs-core

The core MkDocs plugin used by Backstage's TechDocs as a wrapper around multiple MkDocs plugins and Python Markdown extensions
Apache License 2.0
83 stars 61 forks source link

Plans to support mkdocs-material 8.2.x? #63

Closed shanthisagar-dhanya-kumar-db-zz closed 1 year ago

shanthisagar-dhanya-kumar-db-zz commented 2 years ago

We are very much after https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/?h=tags. Can we get the mkdocs-material upgraded sooner?

lacyllana-zb commented 2 years ago

I believe upgrading mkdocs-material would also address this issue: https://github.com/backstage/mkdocs-techdocs-core/issues/35

There is native mermaid support in 8.2.0: https://squidfunk.github.io/mkdocs-material/reference/diagrams/?h=mermaid

abi-jey commented 2 years ago

What needs to be done so we can update and use major versions bigger that 8.2?

iamEAP commented 1 year ago

Hey folks! Chiming in with some context:

The reason we have a hard pin on a specific version of mkdocs-material is that the TechDocs frontend has some implicit dependencies on the exact markup (think: class names, element hierarchy, IDs, etc) of generated docs sites. We rely on these things to be able to hook into the navigation and TOC, isolate content, etc. in order to ensure that they work within the context of a Backstage application. These are not part of the API surface area of mkdocs-material, and thus may change from one version of mkdocs-material to another. As a result, a lot of care and testing has to go into upgrades.

Something that could help make upgrades go more smoothly, and therefore allow us to upgrade more regularly would be to enumerate those implicit dependencies we have (they can be found in the code within @backstage/plugin-techdocs-react and @backstage/plugin-techdocs packages), and find a way to automatically validate that they are still satisfied (in a build step in a CI job on this repo).

This isn't currently a priority for the core team, but we're happy to support folks who can help contribute in this direction.

Referencing #80, for completeness.

DonDebonair commented 1 year ago

Hey @iamEAP, is this likely to become a priority? Because to be honest, technical documentation is a large part of what Backstage is all about, and relying on an increasinly old version of mkdocs-material, will make Backstage increasingly less attractive to use for technical documentation.

What you end up with, is using Backstage for the service administration, but do technical documentation in another way so that mkdocs-material can be leveraged to it's full extend. That is surely not what you folks want?

shanthisagar-dhanya-kumar-db-zz commented 1 year ago

Hey @iamEAP, is this likely to become a priority? Because to be honest, technical documentation is a large part of what Backstage is all about, and relying on an increasinly old version of mkdocs-material, will make Backstage increasingly less attractive to use for technical documentation.

What you end up with, is using Backstage for the service administration, but do technical documentation in another way so that mkdocs-material can be leveraged to it's full extend. That is surely not what you folks want?

I fully support this statement. In our org, we currently have deviated. We have cloned the mkdocs-techodcs-core and going our own way to support the latest version of the mkdocs-material 9.x.x

DonDebonair commented 1 year ago

I fully support this statement. In our org, we currently have deviated. We have cloned the mkdocs-techodcs-core and going our own way to support the latest version of the mkdocs-material 9.x.x

Wow, that sounds cool! Is this a public fork?

DonDebonair commented 1 year ago

I hate to be that guy, but I'd still like to know if support for newer MkDocs versions is in the works @iamEAP . If the answer is no, that is also completely understandable, but I (and probably others) would like to know this so we can consider alternatives.

iamEAP commented 1 year ago

Hey there! We are naturally keen to try and keep things up-to-date and the community moving forward together, so thanks for continuing to engage.

I'm a lot less active on TechDocs these days, however. Lemme pull @agentbellnorm and @soapraj into the conversation!

agentbellnorm commented 1 year ago

Hey! @DonDebonair, @iamEAP, @shanthisagar-dhanya-kumar-db

I've created a PR and some kind of plan to get this out, would appreciate any input! 🙏🏼 https://github.com/backstage/mkdocs-techdocs-core/pull/109

DonDebonair commented 1 year ago

Sorry for the late response. This is super awesome!.

Question: @iamEAP mentioned something earlier about relying on specific classes in the output that mkdocs-material generates

Something that could help make upgrades go more smoothly, and therefore allow us to upgrade more regularly would be to enumerate those implicit dependencies we have (they can be found in the code within @backstage/plugin-techdocs-react and @backstage/plugin-techdocs packages), and find a way to automatically validate that they are still satisfied (in a build step in a CI job on this repo).

Is this something that has been implemented/going to be implemented/is somewhere on the horizon? I can imagine that if something like an automated check for breakage doesn't exist, you will run into exactly this issue again X months from now when someone asks for a newer mkdocs-material :)

agentbellnorm commented 1 year ago

@DonDebonair Yeah that would be cool! It's not something that I think I'll be able to prioritize in the near future though.

I'm closing this issue. Feel free to reopen or create a new one if you experience any problems!