timvink / mkdocs-git-revision-date-localized-plugin

MkDocs plugin to add a last updated date to your site pages
https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html
MIT License
206 stars 44 forks source link

Add localization for 'Last Updated' #18

Closed timvink closed 4 years ago

timvink commented 4 years ago

Currently, the localization is implemented in mkdocs-material. For those not using that theme, this plugin should offer the same functionality.

Basically we move the same functionality into the plugin. We then add an option to add a localized 'Last updated: ' text.

Initially by default that option should be turned off (backward compatible). Then we can discuss mkdocs-material to remove the localization, and release a version of the plugin that sets that option to True by default.

timvink commented 4 years ago

@squidfunk Currently mkdocs-material has localizations for the mkdocs-git-revision-date-localized-plugin. This is working great so far, but wondering how you feel about that design decision? Should we move the localization of the revision date to this plugin, and remove it from mkdocs-material, or would you like to leave it as-is?

squidfunk commented 4 years ago

@timvink I'd prefer leaving it in Material, as we'd have all localizations in one place 😊

BTW, as an FYI, note that I will remove the plugin from the Docker image with the advent of version 6. The reason is that the plugin significantly blows up the Docker image due to the dependencies it brings. However, installing a plugin inside the Docker image is very easy.

timvink commented 4 years ago

Clear. Easier for me also, let's keep it as-is. Closing this issue.

I wasn't aware babel and GitPython were such large dependencies. GitPython I can work around (mkdocs-git-authors-plugin implements it's own git classes to do that already), babel is needed for localization. But makes sense to make the docker image as clean as possible.

Btw, what I find missing in the mkdocs eco-system is an overview of the most useful / commonly used plugins. For mkdocs to catch-up a bit with sphinx it needs to be easier for new users to find good themes and plugins. In that sense I'm missing your plugins section in the mkdocs-material docs ;)

squidfunk commented 4 years ago

I started an overview on the old docs for plugins that were supported by Material, but as I inverted the docs from "what's supported" into "how to achieve X", I don't know whether it makes sense to add a plugin index. There's the official wiki page, but I agree that it's a bit of a mess. I'm happy to add further sections to Material for MkDocs which show how to use plugins in a use-case-based way, though. However, I feel that the MkDocs ecosystem is very fragmented with many similar plugins, so I'd not know where to start when interviewing people for the most popular ones.

squidfunk commented 4 years ago

I just saw that the wiki has download counts, that's a reasonable indicator for popularity: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

timvink commented 4 years ago

I guess other eco-systems have similar problems. Not sure how to solve it... I'm trying to do my part by writing a blogpost on how to use it for documenting machine learning models. And those download counts I actually added them to the wiki 😄

I like your use-case descriptions idea. I remember seeing a PR where you already did some work on this, but it was never merged? Showing a couple of working, fully configured examples for different use cases could make it easier for new users to get started, and could promote relevant plugins at the same time.

squidfunk commented 4 years ago

I remember seeing a PR where you already did some work on this, but it was never merged?

I guess you mean the tutorials section, right? Providing tutorials was the idea I followed before I decided to scrap everything and rewrite the entire docs, so the entire docs are tutorials 😉 The "Setup" section provides tutorials on what can be configured, and the "Reference" section does the same for writing.

timvink commented 4 years ago

Ah I see. If you ever consider adding an "Example use cases" section, I'd be happy to contribute! Some use cases to show off different functionalities and plugins:

squidfunk commented 4 years ago

That's a little beyond the scope of Material, but could be a project of its own?

timvink commented 4 years ago

I would see a use case being a simple as a short description, a list of applicable plugins and markdown_extensions, and an example (collapsed) mkdocs.yml file. All use cases would easily fit in a single page. But yeah, I agree it is beyond the scope of Material.

I'm not inclined to start a separate project for this though. I have an internal demo repo at my company showcasing a complete mkdocs setup, and that works fine. Also not sure how new users would find that project / repo. Finally, with even more mkdocs resources, there's also a bit of this that applies

image