search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
20.12k stars 3.47k forks source link

🥳 Material for MkDocs 9.2 – Beta #5686

Closed squidfunk closed 1 year ago

squidfunk commented 1 year ago

With the help of our awesome sponsors, I'm happy to announce that the 'Piri Piri' funding goal has been reached, which means that amongst other awesome features, the built-in blog plugin is finding its way into the community edition!

If you experience any problems, for now, please report them as a comment in this issue.

Installation

pip install mkdocs-material==9.2.0b3

Note – This is a beta release, so please test thoroughly before deploying to production.

Changes

Beta 0

Beta 1

Beta 2

Beta 3

Final

Upgrading

Changes to mkdocs.yml

None.

Changes to customizations

If you've customized Material for MkDocs with theme overrides, and added your own partials, you need to update the following partials, as they got updated with new functionality. If you don't update them, you'll not be able to use some of the new features:

You can check the full list of changes here: https://github.com/squidfunk/mkdocs-material/pull/5683/files

Closing thoughts

We're super happy to finally give the built-in blog plugin into the hands of all users, so we can improve it even more. Before issuing the final release, we'll take the opportunity to refactor some edges that need a little polishing and incorporate your feedback.

❤️ ❤️ ❤️

Thanks again to all of our awesome sponsors for making our work on this project possible in the first place! Without you, all of those features would not exist. We hope for your continued support, as it allows us to ship more useful and unique features, like for example the latest improved social plugin, which allows to build entirely custom social cards.

squidfunk commented 1 year ago

@usulpt we need a reproduction without awesome pages, since we don't have official support for it. Please create a new issue and create a reproduction that does not use awesome pages, so we're sure that the bug is on our side 😊

usulpt commented 1 year ago

I found a workaround using awesome-pages and I tried reproducing the issue without awesome-pages and it works fine. sorry to bring this up, carry on the great work! :)

squidfunk commented 1 year ago

Perfect! Could you please share a little about the problem with awesome pages and the workaround you found? Other users might be impacted, too, so you will do them a great favor ☺️

usulpt commented 1 year ago

will do! :)

squidfunk commented 1 year ago

Update: just to let all of you know, I'm currently doing a deep refactor of the blog plugin to address the remaining issues, primarily remove the limitation that a nav entry must be set to use the blog. This should make it compatible with awesome pages and other plugins. Additionally, MkDocs 1.5 made handling of generated pages much simpler. As the blog plugin has roughly a thousand lines of code, this might take some additional time. No breaking changes in configuration or usage are expected, except for when you customized the templates – those will undergo a refactor as well.

sheldonhull commented 1 year ago

@squidfunk thanks for this. I was about to report this issue as well on the nav element being required after beating my head against this in a dockerized build for a few hours. The lack of need to specify nav is one of my favorite features for the more complex docs.

I did run into one other behavior and I'm not certain it's expected. Putting under summary section to avoid noise. Please advise if I should open a new discussion or if this is relevant to beta release.

details on the blog posts slug issue I've run into I try to keep my blog very level in url. So for instances, the url slug for all my blog posts has no blog prefix. It's just a `sheldonhull.com/my-post` not `sheldonhull.com/blog/my-post`. I took this advice from a tech blogger and have found it helpful especially when I reorg physical structure of the posts. While I see the ability to set the blog directory as `.`, I think that prohibits me from placing my content in a `posts` subdirectory. The url schema can eliminate the date prefix, but it assumes the blog/posts prefix from what I see. For now I can move this to a new discussion item if the behavior is intentional, but thought I'd mention as it impacts the url structure for adoption for me at least. The posts below are all served with `sheldonhull.com/slug` no prefix, but you can see I store them in an organized directory structure to avoid having to dig through many posts each year. ![image](https://github.com/squidfunk/mkdocs-material/assets/3526320/713ad035-12c5-4b4a-9a2c-5cf49a108664)
squidfunk commented 1 year ago

@sheldonhull I'm currently rewriting the plugin from the ground up and the navigation issue is already fixed - there are now no limitations to where you place the blog, or whether you specify nav or not. Please give me some more days to finish the refactoring, since the blog plugin has quite a large code base. The refactored version will also improve interop with other plugins, so they can inspect and alter posts and indexes in any way they like.

Regarding the issue with slugs – you should set blog_dir to . and then put your posts in docs/posts. You can then also put arbitrary pages in docs at locations you wish – the posts directory is essentially just a storage location for pages that are treated as blog posts, and whose URLs are all dynamically computed. Everything else is left untouched. Example:

.
├─ docs/
│  ├─ posts/
│  │  └─ hello-world.md 
│  ├─ reference/
│  │  ├─ index.md  # example.com/reference/
│  │  ├─ foo.md    # example.com/reference/foo/
│  │  └─ bar.md    # example.com/reference/bar/
│  ├─ baz.md       # example.com/baz/
│  └─ index.md     # example.com/
└─ mkdocs.yml

Note that when there's no blog prefix, you must make sure that your slugs don't collide with URLs of other pages.

squidfunk commented 1 year ago

Additionally, for the sake of completeness: you can organize your posts as you like – everything in the posts directory receives a computed URL based on the schemes configured, which means that the directory structure is not relevant. This allows you to group your posts as you like, which will also give you the ability to use the meta plugin intelligently.

do-me commented 1 year ago

Thanks a lot for all the work you put in the blog feature, this is so awesome! For me, mkdocs-material now has finally become a real hugo/jekyll alternative.

I guess this might be the right issue to mention a few missing translation options for the blog. The docs currently only mention easy translation of these parts:

  - blog:
      categories_name: Categories
      archive_name: Archive

but the following are missing (afaik):

image

I guess I could just modify the templates, but it doesn't feel right as the other settings are located in the mkdocs.yml too.

squidfunk commented 1 year ago

Those translations are provided as part of localizations:

https://github.com/squidfunk/mkdocs-material/blob/ccc3c444edc66479074aa480b3afca56f17d38ed/src/partials/languages/en.html#L31-L38

https://github.com/squidfunk/mkdocs-material/blob/ccc3c444edc66479074aa480b3afca56f17d38ed/src/partials/languages/en.html#L51-L52

You can override them easily, as mentioned in our docs.

do-me commented 1 year ago

Thanks for the links! So the idea is that the options in mkdocs.yml for categories and archive are rather for convenient renaming (e.g. "themes/topics" or similar) than actual translation. Translations should then always go in mkdocs-material/src/partials/languages/ if I get it right.

squidfunk commented 1 year ago

Yes, exactly, both options are regarded as content and not part of the site structure. They are also part of the translations, so that we can provide good defaults per language. In German, the default will be "Archiv" and "Kategorien".

ofek commented 1 year ago

Hey! We just deployed using the beta and I think perhaps something related to CSS changed https://datadoghq.dev/integrations-core/

The site should be using our branded purple color but it seems like it is not. Did something change that I missed?

squidfunk commented 1 year ago

@ofek What did you use before? There were no recent changes from 9.1 to 9.2 that could explain the behavior. Looking at your CSS; it looks like you're coming from an older version. You need to adjust the selector when overriding primary colors. This was changed in 8.5.10 (see diff) which was released 9 months ago.

ofek commented 1 year ago

That was it indeed; thank you and sorry for the noise!

squidfunk commented 1 year ago

No worries, it was a necessary change to make color customization easier, and there are probably some installations (like yours) out there that need updating. However, we can't do a major release for every little bit of customization we change, or we would be at v237 already 😅 Glad we could sort it out so quickly

squidfunk commented 1 year ago

Material for MkDocs 9.2.0 was just released! It brings many new capabilities and fixes some long standing bugs.

Thank you all for testing the beta releases and for your patience ❤️

TimChaubet-I4U commented 9 months ago

No worries, I think I know where this is coming from. It should only happen if you add the search plugin during serve mode. If you restart mkdocs build, it should work again. We'll fix this issue as well.

This is still an issue in the container version of mkdocs (tested today 2023-11-21). We fixed it by putting build & serve in the startup script of docker compose.

version = "9.4.8" (material) mkdocs, version 1.5.3 from /usr/local/lib/python3.11/site-packages/mkdocs (Python 3.11)

squidfunk commented 9 months ago

@TimChaubet-I4U Sorry, I don't know what you mean (I haven't skimmed through all comments here and the quote does not provide enough context). If you're referring to https://github.com/squidfunk/mkdocs-material/issues/6364, this is fixed on master.