NEW: Adding announcement banners (#722)

Co-authored-by: Daniel McCloy <dan@mccloy.info>

docs/conf.py

@@ -108,6 +108,8 @@
     },
     "use_edit_page_button": True,
     "show_toc_level": 1,
+    # "announcement": "Here's a test <a href='https://google.com'>announcement</a>!",
+    "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
     # "show_nav_level": 2,
     # "search_bar_position": "navbar",  # TODO: Deprecated - remove in future version
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly

docs/user_guide/configuring.rst

@@ -78,8 +78,6 @@ This will appear just after your logo image if it is set.
 .. note:: The ``html_title`` field will work as well if no logo images are specified.
 
 
-.. _icon-links:
-
 Configure default theme mode
 ============================
 
@@ -127,6 +125,49 @@ As the Sphinx theme supports multiple modes, the code highlighting colors can be
 
    The native Sphinx option `pygments_style` will be overwritten by this theme.
 
+Announcement banners
+====================
+
+You can add an announcement banner that draws extra attention from your reader.
+It will be displayed at the top of the screen, but will disappear once you start scrolling.
+
+To add an announcement banner, use the ``html_theme_options["announcement"]`` configuration.
+There are two ways to use this.
+
+Provide local HTML in your theme
+--------------------------------
+
+By default, the value of your ``html_theme_options["announcement"]`` will be inserted directly into your announcement banner as raw HTML.
+
+For example, the following configuration adds a simple ``<p>`` with an announcement.
+
+.. code-block:: python
+
+   html_theme_options = {
+      ...
+      "announcement": "<p>Here's a <a href='https://pydata.org'>PyData Announcement!</a></p>",
+   }
+
+Insert remote HTML with JavaScript
+----------------------------------
+
+You can specify an arbitrary URL that will be used as the HTML source for your announcement.
+When the page is loaded, JavaScript will attempt to fetch this HTML and insert it as-is into the announcement banner.
+This allows you to define a single HTML announcement that you can pull into multiple documentation sites or versions.
+
+If the value of ``html_theme_options["announcement"]`` begins with **``http``** it will be treated as a URL to remote HTML.
+
+For example, the following configuration tells the theme to load the ``custom-template.html`` example from this documentation's GitHub repository:
+
+.. code-block:: python
+
+   html_theme_options = {
+      ...
+      "announcement": "https://github.com/pydata/pydata-sphinx-theme/raw/main/docs/_templates/custom-template.html",
+   }
+
+.. _icon-links:
+
 Configure icon links
 ====================
 

src/pydata_sphinx_theme/assets/styles/base/_base.scss

@@ -4,7 +4,6 @@ html {
 }
 
 body {
-  padding-top: var(--pst-header-height);
   background-color: var(--pst-color-background);
   font-family: var(--pst-font-family-base);
   font-weight: 400;

src/pydata_sphinx_theme/assets/styles/index.scss

@@ -34,6 +34,7 @@ $grid-breakpoints: (
 
 // Major theme layout, skeleton, and whitespace
 @import "./sections/container";
+@import "./sections/announcement";
 @import "./sections/article";
 @import "./sections/footer";
 @import "./sections/footer-article";

src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss

@@ -0,0 +1,36 @@
+$announcement-height: 3rem;
+.bd-header-announcement {
+  height: $announcement-height;
+  width: 100%;
+  display: flex;
+  position: relative;
+  align-items: center;
+  justify-content: center;
+  padding: 0.5rem 12.5%; // Horizontal padding so the width is 75%
+  @include media-breakpoint-down(md) {
+    // Announcements can take a bit more width on mobile
+    padding: 0.5rem 2%;
+  }
+
+  p {
+    font-weight: bold;
+    margin: 0;
+  }
+
+  // The same background color transparency hack we use in admonitions
+  &:after {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    left: 0;
+    top: 0;
+    background-color: var(--pst-color-info);
+    opacity: 0.2;
+    content: "";
+    z-index: -1; // So it doesn't hover over the content
+  }
+
+  &:empty {
+    display: none;
+  }
+}

src/pydata_sphinx_theme/assets/styles/sections/_header.scss

@@ -1,5 +1,5 @@
 .navbar {
-  position: fixed;
+  position: sticky;
   min-height: var(--pst-header-height);
   width: 100%;
   padding: 0;

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -26,10 +26,7 @@
 {%- endblock %}
 
 {%- block content %}
-    <div class="bd-header-announcement container-fluid" id="banner">
-      {% include "sections/announcement.html" %}
-    </div>
-
+    {%- include "sections/announcement.html" -%}
     {% block docs_navbar %}
     <nav class="bd-header navbar navbar-light navbar-expand-lg bg-light fixed-top bd-navbar" id="navbar-main">
       {%- include "sections/header.html" %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/announcement.html

@@ -1,2 +1,24 @@
-{# A banner with an alert. #}
-{# Note that this hasn't been optimized yet so may not behave as expected. #}
+{%- if theme_announcement -%}
+
+{% set is_remote=theme_announcement.startswith("http") %}
+
+{# If we are remote, add a script to make an HTTP request for the value on page load #}
+{%- if is_remote %}
+<script>
+$.get("{{ theme_announcement }}", success=(data)=>{
+      $("#header-announcement").html(`<div class="bd-header-announcement__content">${data}</div>`);
+  }).fail(() => {
+  console.log("[PST]: Failed to load announcement at: {{ theme_announcement }}")
+});
+
+</script>
+{% endif %}
+
+<div class="bd-header-announcement container-fluid" id="header-announcement">
+  {#- if announcement text is not remote, populate announcement w/ local content -#}
+  {%- if not is_remote %}
+  <div class="bd-header-announcement__content">{{ theme_announcement }}</div>
+  {%- endif -%}
+</div>
+
+{%- endif %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

@@ -38,6 +38,7 @@ switcher =
 pygment_light_style = tango
 pygment_dark_style = native
 logo =
+announcement =
 
 # DEPRECATE after 0.11
 logo_text =