Feature request: add an annoucement bar

Ir1d commented 5 years ago

Sometimes you want to announce something in your website. For example: “We are looking to revamp our docs, please fill this survey”.

The announcement bar is dismissable and render above the nav bar.

Or maybe something like popups or alerts showing up at up-right corner might also be a good idea.

squidfunk commented 5 years ago

That's a nice idea. It could theoretically be implemented with the metadata extension, but dismissing would need to be implemented with a cookie or local storage. If somebody wants to go ahead on this and implement a prototype, feel free to do so. If it works reasonably well, we can integrate it into Material. Unfortunately, I don't have any time for this at the moment.

urna commented 5 years ago

yes, also think this would be useful.

Ir1d commented 4 years ago

We have an ugly workaround, posting here in case someone else might need it.

https://github.com/OI-wiki/mkdocs-material/compare/40794bbff7a27a563677274091ed8f706592cd18..24c05b4ba1eb5536bd7818913560394429d035ae

demo at https://oi-wiki.org

squidfunk commented 4 years ago

In case somebody wants this feature, I could use some help here. A great starting point would be a proposal how this announcement bar should behave. Some questions to anwer:

Should it be above the header? Overlay the header?
What about mobile?
Is HTML content allowed?
Should it stretch?
Which color should it have? Accent? Primary?

Maybe also provide some mockups and some ideas how this could be integrated/used from a user perspective. I really want to release it as part of v5 as I think this is a nice feature.

Stanzilla commented 4 years ago

I kinda abused the hero feature for that

pawamoy commented 4 years ago

You can get inspiration from the Django docs for example: on https://docs.djangoproject.com/en/dev/ and https://docs.djangoproject.com/en/1.7/. But maybe this is more a "banner" than an annoucement bar?

it is above the header (though having it below on this theme seems good as well)
it stretches

A few remarks:

it should be clearly visible as users may put important information in it, so not the same color as the header
the user should be able to pick the color, depending on the contents of the announcement (like admonitions? warning-yellow, danger-red, etc.)
it should not always be dismissible (or not at all dismissible from my point of view, but I understand the need for other use-cases)
being able to put at least links into it could be nice (example: link to another page with more detailed information about the announcement, external link to a survey, etc.), with HTML/Markdown, or simply text URLs that are made clickable
it should be configurable globally or per page
it should appear on mobile as well

squidfunk commented 4 years ago

@pawamoy thanks for your ideas.

My initial idea was to implement it with front matter which supports HTML content but we could also try and prototype something using template blocks. Defining an announcement bar would have to be done using theme extension but I guess that might be the best idea in order to cater to many use cases anyway. I'm unsure about the color customization, as I don't want to introduce more and more options to the mkdocs.yml, so maybe we just use the accent color as a default and make it easily overridable via CSS.

I'm also not quite sure whether the DX is gonna be good enough, as an announcement bar is kind of a cross-cutting piece of content. Some people may only want to have it on the front page, some on other pages, some think it should be dismissible (for how long?). We we're discussing a new section in the docs called "Recipes" (or something similar) where we could list some common theme extension use cases, so maybe the whole announcement bar story should go into there.

squidfunk commented 4 years ago

I think I've found a good way to implement this feature. The header is now positioned with sticky instead of fixed which means it will lock into place when the announcement bar is scrolled past. Note that the bar is only visible at the top of the page. Personally, I think that's good UX, because it doesn't limit the available screen on mobile, and thus is rather unobtrusive.

Demo:

Announcement bar

It's implemented as a template block, so in order to set content the main template needs to be extended. Using theme extension gives ultimate flexibility, so users can put anything in there, buttons, links, etc. This is very simple:

{% extends "base.html" %}

{% block announcement %}
  The quick brown fox jumpy over the lazy dog
{% endblock %}

This is a POC implementation and thus an experimental feature, there's currently no possibility to dismiss the bar. The implementation is part of the refactoring branch and will be released with Material v5.

Stanzilla commented 4 years ago

I like it! I think I switched my header to sticky in my fork as well

pawamoy commented 4 years ago

This looks great 🙂 Looking forward to try v5!

squidfunk commented 4 years ago

Material for MkDocs 5.0.0rc1 is out which fixes this issue 😀 Let's test and improve it together!

The announcement bar can be added with simple theme extension, see:

https://github.com/squidfunk/mkdocs-material/blob/77987485af3448c9b86a5535d3a119498ddbe100/src/overrides/home.html#L25-L27

squidfunk / mkdocs-material

Feature request: add an annoucement bar #1190