Feature/plugins

[alexvoss]

Documentation for the first six plugins:

• redirect plugin
• tags plugin
• minify plugin
• meta plugin
• awesome-nav
• literate-nav

[pawamoy]

Do we use material/tags instead of zensical/tags because tags in mkdocs.yml is normalized as material/tags? @squidfunk

[squidfunk]

We should not use the material/* names. Those are only necessary for compat.

[alexvoss]

Ok, will change it for the tags configuration.

@squidfunk

• Meta does not seem to have a short name if codex did not just miss it.
• For tags, it also tells me that "the default listings_directive is strictly material/tags".

[alexvoss]

I have pushed pages for the literate-nav and awesome-nav plugins as well now. I tried to have them be complete without replicating the entire docs (of awesome-nav in particular). Added an admonition at the top to alert people to the fact that we have our own ideas about navigation as content and modular navigation.

[squidfunk]

Here's my feedback. I haven't annotated them here, since most things are high-level and cross multiple boundaries.

---

• We should not advertise plugins in the main tab area. Zensical's extension concept is "modules", not "plugins". Plugins are part of the compatibility layer that we create to mirror MkDocs compatibility. Putting it onto the /plugins/ path sounds as if we decided to make it a first-class citizen of the Zensical ecosystem, which is not the case. Please find a better way to reframe that under compatibility.

• The Extensions tab points to /setup/extensions/about/, which is a smell, since it's not a top-level category. Extensions also belong to MkDocs compat. We need to find a way to unify both.

• We must mention that the plugins are direct ports of the functionality to Zensical. We must credit the original authors, and link to the original plugins. This is another reason why "plugins" should not be marketed as the central extension point for Zensical.

• Remove the modular navigation banner in both navigation plugins. Once we have something to show, we can add it back.

• Navigation hierarchy for some plgins is almost-all-h2. Hard to identify what's relevant for me as a reader.

• Plugin labels Literal navigation and Awesome navigation – these sound like distinctive features, yet they are plugin names. Please don't use them as navigation labels. Moving everyting into a bigger compact context, use the actual plugin names.

• As mentioned before, please do not use material/*, use the actual plugin name only. This omits ugly necessary quotes in TOML. We detect the material/ prefixes name but it was never the canonical name we advertised in the docs. Just drop it.

• Tags plugin: please use the style from the Material for MKDocs documentation, explicitly listing the name of the setting. This make discovery in search significantly simpler. Additionally, do not merge settings into one.

• plugins/redirects/#directory-urls - very noisy example, hard to follow

[pawamoy]

We should not advertise plugins in the main tab area. Zensical's extension concept is "modules", not "plugins". Plugins are part of the compatibility layer that we create to mirror MkDocs compatibility. Putting it onto the /plugins/ path sounds as if we decided to make it a first-class citizen of the Zensical ecosystem, which is not the case. Please find a better way to reframe that under compatibility.

The Extensions tab points to /setup/extensions/about/, which is a smell, since it's not a top-level category. Extensions also belong to MkDocs compat. We need to find a way to unify both.

So that includes autorefs, glightbox, macros (+ table-reader), markdown-exec and mkdocstrings, right?

[alexvoss]

Extensions also belong to MkDocs compat. We need to find a way to unify both.

So that includes autorefs, glightbox, macros (+ table-reader), markdown-exec and mkdocstrings, right?

My 2p: people don't care much about what is a Markdown extension vs. a plugin. I am trying out a refactor calling them all extensions and mentioning "plugin" only when mentioning specific compatibility with a MkDocs plugin. I am not sure people will understand "module" either but am happy either way (not the hill I will die on).

So, yes, the existing docs on Markdown extensions would sit under the same tab as the extensions we are about to release. Some are plugins in the MkDocs world, some are not. I had the idea of distinguishing between Material for MkDocs stuff and third party stuff using page status icons. Let's see if that flies.

The main thing is to factor the compatibility pages from the website into the docs, update it, make sure it all inter-links.

[alexvoss]

• Consolidated all the Python Markdown extensions and modules that replace plugins under "modules".
• Made sure the structure is similar to the in the Material for MkDocs plugins section.
• this includes adjusting level headings
• Added acknowledgements and links for third party plugins and clarified these are ports.
• Removed the admonitions on modular navigation
• Changed navigation labels to match plugin names
• Using simple plugin names in config.
• Simplified plugins/redirects/#directory-urls
• Integrated compatibility information from the website into /features.md, which sits in "Get Started"

[squidfunk]

I've consolidated the compatibility content of web/docs into a dedicated section in the docs which guides MkDocs users interested in adopting Zensical. Plugin settings are now moved to their respective external guides. It doesn't make sense for us to mirror each and every setting, since MkDocs users are already familiar with the existing plugins. Additionally, new users of Zensical should rather adopt our new upcoming modules than the plugin replacements that are merely provided for compatibility.