Added support for hero text

docs/customization.md

@@ -151,6 +151,7 @@ The Material theme provides the following template blocks:
 | `fonts`      | Wraps the webfont definitions                   |
 | `footer`     | Wraps the footer with navigation and copyright  |
 | `header`     | Wraps the fixed header bar                      |
+| `hero`       | Wraps the hero teaser                           |
 | `htmltitle`  | Wraps the `<title>` tag                         |
 | `libs`       | Wraps the JavaScript libraries, e.g. Modernizr  |
 | `repo`       | Wraps the repository link in the header bar     |

docs/extensions/metadata.md

@@ -1,3 +1,4 @@
+hero: Yes, this is set via Metadata
 path: tree/master/docs/extensions
 source: metadata.md
 
@@ -39,6 +40,15 @@ source: file.js
 
 See the next section which covers the metadata that is supported by Material.
 
+### Setting a hero text
+
+Material exposes a simple text-only page-local hero via Metadata, as you can
+see on the current page when you scroll to the top. It's as simple as:
+
+``` markdown
+hero: Yes, this is set via Metadata
+```
+
 ### Overriding the title
 
 The page title can be overridden on a per-document level:

material/base.html

@@ -9,7 +9,7 @@
       <meta charset="utf-8">
       <meta name="viewport" content="width=device-width,initial-scale=1">
       <meta http-equiv="x-ua-compatible" content="ie=edge">
-      {% if page and page.meta.description %}
+      {% if page and page.meta and page.meta.description %}
         <meta name="description" content="{{ page.meta.description }}">
       {% elif config.site_description %}
         <meta name="description" content="{{ config.site_description }}">
@@ -17,7 +17,7 @@
       {% if page.canonical_url %}
         <link rel="canonical" href="{{ page.canonical_url }}">
       {% endif %}
-      {% if page and page.meta.author %}
+      {% if page and page.meta and page.meta.author %}
         <meta name="author" content="{{ page.meta.author | first }}">
       {% elif config.site_author %}
         <meta name="author" content="{{ config.site_author }}">
@@ -37,7 +37,7 @@
       <meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-2.1.1">
     {% endblock %}
     {% block htmltitle %}
-      {% if page and page.meta.title %}
+      {% if page and page.meta and page.meta.title %}
         <title>{{ page.meta.title }}</title>
       {% elif page and page.title and not page.is_homepage %}
         <title>{{ page.title }} - {{ config.site_name }}</title>
@@ -46,7 +46,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application.1411ec6b.css">
+      <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application.d9f8e096.css">
       {% if palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-palette.d142ea54.css">
       {% endif %}
@@ -101,6 +101,11 @@
       {% include "partials/header.html" %}
     {% endblock %}
     <div class="md-container">
+      {% block hero %}
+        {% if page and page.meta and page.meta.hero %}
+          {% include "partials/hero.html" with context %}
+        {% endif %}
+      {% endblock %}
       {% if feature.tabs %}
         {% include "partials/tabs.html" %}
       {% endif %}
@@ -137,7 +142,7 @@
                 {% endif %}
                 {{ page.content }}
                 {% block source %}
-                  {% if page.meta.source %}
+                  {% if page and page.meta and page.meta.source %}
                     <h2 id="__source">{{ lang.t("meta.source") }}</h2>
                     {% set path = page.meta.path | default([""]) %}
                     {% set file = page.meta.source %}
@@ -150,7 +155,7 @@
               {% block disqus %}
                 {% if config.extra.disqus and not page.is_homepage %}
                   <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
-                  {% include "partials/disqus.html" %}
+                  {% include "partials/integrations/disqus.html" %}
                 {% endif %}
               {% endblock %}
             </article>
@@ -162,7 +167,7 @@
       {% endblock %}
     </div>
     {% block scripts %}
-      <script src="{{ base_url }}/assets/javascripts/application.f0a10a07.js"></script>
+      <script src="{{ base_url }}/assets/javascripts/application.446a0cc2.js"></script>
       {% if lang.t("search.language") != "en" %}
         {% set languages = lang.t("search.language").split(",") %}
         {% if languages | length and languages[0] != "" %}
@@ -188,7 +193,7 @@
     {% endblock %}
     {% block analytics %}
       {% if config.google_analytics %}
-      <script>!function(e,a,t,n,o,c,i){e.GoogleAnalyticsObject=o,e.ga=e.ga||function(){(e.ga.q=e.ga.q||[]).push(arguments)},e.ga.l=1*new Date,c=a.createElement(t),i=a.getElementsByTagName(t)[0],c.async=1,c.src="https://www.google-analytics.com/analytics.js",i.parentNode.insertBefore(c,i)}(window,document,"script",0,"ga"),ga("create","{{ config.google_analytics[0] }}","{{ config.google_analytics[1] }}"),ga("set","anonymizeIp",!0),ga("send","pageview");var links=document.getElementsByTagName("a");Array.prototype.map.call(links,function(e){e.host!=document.location.host&&e.addEventListener("click",function(){var a=e.getAttribute("data-md-action")||"follow";ga("send","event","outbound",a,e.href)})});var query=document.forms.search.query;query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})</script>
+        {% include "partials/integrations/analytics.html" %}
       {% endif %}
     {% endblock %}
   </body>

material/partials/hero.html

@@ -0,0 +1,9 @@
+{% set class = "md-hero" %}
+{% if not feature.tabs %}
+  {% set class = "md-hero md-hero--expand" %}
+{% endif %}
+<div class="{{ class }}" data-md-component="hero">
+  <div class="md-hero__inner md-grid">
+    {{ page.meta.hero }}
+  </div>
+</div>

material/partials/integrations/analytics.html

@@ -0,0 +1 @@
+<script>!function(e,a,t,n,o,c,i){e.GoogleAnalyticsObject=o,e.ga=e.ga||function(){(e.ga.q=e.ga.q||[]).push(arguments)},e.ga.l=1*new Date,c=a.createElement(t),i=a.getElementsByTagName(t)[0],c.async=1,c.src="https://www.google-analytics.com/analytics.js",i.parentNode.insertBefore(c,i)}(window,document,"script",0,"ga"),ga("create","{{ config.google_analytics[0] }}","{{ config.google_analytics[1] }}"),ga("set","anonymizeIp",!0),ga("send","pageview");var links=document.getElementsByTagName("a");Array.prototype.map.call(links,function(e){e.host!=document.location.host&&e.addEventListener("click",function(){var a=e.getAttribute("data-md-action")||"follow";ga("send","event","outbound",a,e.href)})});var query=document.forms.search.query;query.addEventListener("blur",function(){if(this.value){var e=document.location.pathname;ga("send","pageview",e+"?q="+this.value)}})</script>

mkdocs.yml

@@ -120,7 +120,3 @@ pages:
 google_analytics:
   - !!python/object/apply:os.getenv ["GOOGLE_ANALYTICS_KEY"]
   - auto
-
-# Just for testing
-extra_javascript:
-  - https://ginseng-analytics.com/analytics.js

src/assets/javascripts/application.js

@@ -212,12 +212,12 @@ function initialize(config) { // eslint-disable-line func-style
   }).listen()
 
   /* Component: header shadow toggle */
-  new Material.Event.MatchMedia("(min-width: 1220px)",
+  new Material.Event.Listener(window, [
-    new Material.Event.Listener(window, [
+    "scroll", "resize", "orientationchange"
-      "scroll", "resize", "orientationchange"
+  ], new Material.Header.Shadow(
-    ], new Material.Header.Shadow(
+    "[data-md-component=container]",
-      "[data-md-component=container]",
+    "[data-md-component=header]")
-      "[data-md-component=header]")))
+  ).listen()
 
   /* Component: header title toggle */
   new Material.Event.Listener(window, [
@@ -227,6 +227,12 @@ function initialize(config) { // eslint-disable-line func-style
     ".md-typeset h1")
   ).listen()
 
+  /* Component: hero visibility toggle */
+  if (document.querySelector("[data-md-component=hero]"))
+    new Material.Event.Listener(window, [
+      "scroll", "resize", "orientationchange"
+    ], new Material.Tabs.Toggle("[data-md-component=hero]")).listen()
+
   /* Component: tabs visibility toggle */
   if (document.querySelector("[data-md-component=tabs]"))
     new Material.Event.Listener(window, [

src/assets/javascripts/components/Material/Header/Shadow.js

@@ -76,11 +76,18 @@ export default class Shadow {
 
   /**
    * Update shadow state
+   *
+   * @param {Event} ev - Event
    */
-  update() {
+  update(ev) {
-    const active = window.pageYOffset >= this.height_
+    if (ev && (ev.type === "resize" || ev.type === "orientationchange")) {
-    if (active !== this.active_)
+      this.height_ = 0
-      this.header_.dataset.mdState = (this.active_ = active) ? "shadow" : ""
+      this.setup()
+    } else {
+      const active = window.pageYOffset >= this.height_
+      if (active !== this.active_)
+        this.header_.dataset.mdState = (this.active_ = active) ? "shadow" : ""
+    }
   }
 
   /**

src/assets/javascripts/components/Material/Header/Title.js

@@ -78,7 +78,7 @@ export default class Title {
       this.el_.dataset.mdState = (this.active_ = active) ? "active" : ""
 
     /* Hack: induce ellipsis on topics */
-    if (ev.type === "resize") {
+    if (ev.type === "resize" || ev.type === "orientationchange") {
       Array.prototype.forEach.call(this.el_.children, node => {
         node.style.width = `${this.el_.offsetWidth - 20}px`
       })

src/assets/javascripts/components/Material/Tabs/Toggle.js

@@ -46,7 +46,6 @@ export default class Toggle {
     this.el_ = ref
 
     /* Initialize offset and state */
-    this.offset_ = 5
     this.active_ = false
   }
 
@@ -54,7 +53,8 @@ export default class Toggle {
    * Update visibility
    */
   update() {
-    const active = window.pageYOffset >= this.offset_
+    const active = window.pageYOffset >=
+      this.el_.children[0].offsetTop + (5 - 48)                                 // TODO: quick hack to enable same handling for hero
     if (active !== this.active_)
       this.el_.dataset.mdState = (this.active_ = active) ? "hidden" : ""
   }

src/assets/stylesheets/application.scss

@@ -45,6 +45,7 @@
 @import "layout/clipboard";
 @import "layout/content";
 @import "layout/header";
+@import "layout/hero";
 @import "layout/footer";
 @import "layout/nav";
 @import "layout/search";

src/assets/stylesheets/layout/_header.scss

@@ -36,9 +36,7 @@
     color 0.25s;
   background-color: $md-color-primary;
   color: $md-color-white;
-  box-shadow:
+  box-shadow: none;
-    0 0      0.4rem rgba(0, 0, 0, 0.1),
-    0 0.4rem 0.8rem rgba(0, 0, 0, 0.2);
   z-index: 2;
   // Hack: putting the header on the GPU avoids unnecessary repaints
   backface-visibility: hidden;
@@ -48,20 +46,15 @@
     box-shadow: none;
   }
 
-  // [screen +]: Show shadow depending on scroll offset
+  // Show and animate shadow
-  @include break-from-device(screen) {
+  &[data-md-state="shadow"] {
-    box-shadow: none;
+    transition:
-
+      background-color 0.25s,
-    // Show and animate shadow
+      color 0.25s,
-    &[data-md-state="shadow"] {
+      box-shadow 0.25s;
-      transition:
+    box-shadow:
-        background-color 0.25s,
+      0 0      0.4rem rgba(0, 0, 0, 0.1),
-        color 0.25s,
+      0 0.4rem 0.8rem rgba(0, 0, 0, 0.2);
-        box-shadow 0.25s;
-      box-shadow:
-        0 0      0.4rem rgba(0, 0, 0, 0.1),
-        0 0.4rem 0.8rem rgba(0, 0, 0, 0.2);
-    }
   }
 
   // Hide for print

src/assets/stylesheets/layout/_hero.scss

@@ -0,0 +1,64 @@
+////
+/// Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+///
+/// Permission is hereby granted, free of charge, to any person obtaining a
+/// copy of this software and associated documentation files (the "Software"),
+/// to deal in the Software without restriction, including without limitation
+/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
+/// and/or sell copies of the Software, and to permit persons to whom the
+/// Software is furnished to do so, subject to the following conditions:
+///
+/// The above copyright notice and this permission notice shall be included in
+/// all copies or substantial portions of the Software.
+///
+/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
+/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+/// DEALINGS
+////
+
+// ----------------------------------------------------------------------------
+// Rules
+// ----------------------------------------------------------------------------
+
+// Hero teaser
+.md-hero {
+  transition: background 0.25s;
+  background: $md-color-primary;
+  color: $md-color-white;
+  font-size: ms(1);
+  overflow: auto;
+
+  // Inner wrapper
+  &__inner {
+    margin-top: 2rem;
+    padding: 1.6rem 1.6rem 0.8rem;
+    transition:
+      transform 0.4s cubic-bezier(0.1, 0.7, 0.1, 1),
+      opacity   0.25s;
+
+    // [tablet -]: Compensate for missing tabs
+    @include break-to-device(tablet) {
+      margin-top: 4.8rem;
+      margin-bottom: 2.4rem;
+    }
+
+    // Fade-out tabs background upon scrolling
+    [data-md-state="hidden"] & {
+      pointer-events: none;
+      transform: translateY(1.25rem);
+      transition:
+        transform 0s 0.4s,
+        opacity   0.1s;
+      opacity: 0;
+    }
+
+    /* Adjust bottom spacing if there are no tabs */
+    .md-hero--expand & {
+      margin-bottom: 2.4rem;
+    }
+  }
+}

src/base.html

@@ -40,7 +40,7 @@
       <meta http-equiv="x-ua-compatible" content="ie=edge" />
 
       <!-- Page description -->
-      {% if page and page.meta.description %}
+      {% if page and page.meta and page.meta.description %}
         <meta name="description"
             content="{{ page.meta.description }}" />
       {% elif config.site_description %}
@@ -53,7 +53,7 @@
       {% endif %}
 
       <!-- Page author -->
-      {% if page and page.meta.author %}
+      {% if page and page.meta and page.meta.author %}
         <meta name="author" content="{{ page.meta.author | first }}" />
       {% elif config.site_author %}
         <meta name="author" content="{{ config.site_author }}" />
@@ -83,7 +83,7 @@
 
     <!-- Site title -->
     {% block htmltitle %}
-      {% if page and page.meta.title %}
+      {% if page and page.meta and page.meta.title %}
         <title>{{ page.meta.title }}</title>
       {% elif page and page.title and not page.is_homepage %}
         <title>{{ page.title }} - {{ config.site_name }}</title>
@@ -197,6 +197,13 @@
     <!-- Container, necessary for web-application context -->
     <div class="md-container">
 
+      <!-- Hero teaser -->
+      {% block hero %}
+        {% if page and page.meta and page.meta.hero %}
+          {% include "partials/hero.html" with context %}
+        {% endif %}
+      {% endblock %}
+
       <!-- Tabs with outline -->
       {% if feature.tabs %}
         {% include "partials/tabs.html" %}
@@ -262,7 +269,7 @@
 
                 <!-- Source files -->
                 {% block source %}
-                  {% if page.meta.source %}
+                  {% if page and page.meta and page.meta.source %}
                     <h2 id="__source">{{ lang.t("meta.source") }}</h2>
                     {% set path = page.meta.path | default([""]) %}
                     {% set file = page.meta.source %}
@@ -278,7 +285,7 @@
               {% block disqus %}
                 {% if config.extra.disqus and not page.is_homepage %}
                   <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
-                  {% include "partials/disqus.html" %}
+                  {% include "partials/integrations/disqus.html" %}
                 {% endif %}
               {% endblock %}
             </article>
@@ -333,42 +340,7 @@
     <!-- Analytic scripts -->
     {% block analytics %}
       {% if config.google_analytics %}
-      <script>
+        {% include "partials/integrations/analytics.html" %}
-        (function(i,s,o,g,r,a,m){
-          i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||
-          []).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;
-          m.parentNode.insertBefore(a,m)
-        })(window, document,
-          "script", "https://www.google-analytics.com/analytics.js", "ga");
-
-        /* General initialization */
-        ga("create",
-          "{{ config.google_analytics[0] }}",
-          "{{ config.google_analytics[1] }}");
-        ga("set", "anonymizeIp", true);
-        ga("send", "pageview");
-
-        /* Track outbound links */
-        var links = document.getElementsByTagName("a");
-        Array.prototype.map.call(links, function(item) {
-          if (item.host != document.location.host) {
-            item.addEventListener("click", function() {
-              var action = item.getAttribute("data-md-action") || "follow";
-              ga("send", "event", "outbound", action, item.href);
-            });
-          }
-        });
-
-        /* Register handler to log search on blur */
-        var query = document.forms.search.query;
-        query.addEventListener("blur", function() {
-          if (this.value) {
-            var path = document.location.pathname;
-            ga("send", "pageview", path + "?q=" + this.value);
-          }
-        });
-      </script>
       {% endif %}
     {% endblock %}
   </body>

src/partials/hero.html

@@ -0,0 +1,34 @@
+<!--
+  Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- Determine class according to level -->
+{% set class = "md-hero" %}
+{% if not feature.tabs %}
+  {% set class = "md-hero md-hero--expand" %}
+{% endif %}
+
+<!-- Hero teaser -->
+<div class="{{ class }}" data-md-component="hero">
+  <div class="md-hero__inner md-grid">
+    {{ page.meta.hero }}
+  </div>
+</div>

src/partials/integrations/analytics.html

@@ -0,0 +1,59 @@
+<!--
+  Copyright (c) 2016-2017 Martin Donath <martin.donath@squidfunk.com>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to
+  deal in the Software without restriction, including without limitation the
+  rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+  sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+-->
+
+<!-- Google Analytics integration -->
+<script>
+  (function(i,s,o,g,r,a,m){
+    i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||
+    []).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;
+    m.parentNode.insertBefore(a,m)
+  })(window, document,
+    "script", "https://www.google-analytics.com/analytics.js", "ga");
+
+  /* General initialization */
+  ga("create",
+    "{{ config.google_analytics[0] }}",
+    "{{ config.google_analytics[1] }}");
+  ga("set", "anonymizeIp", true);
+  ga("send", "pageview");
+
+  /* Track outbound links */
+  var links = document.getElementsByTagName("a");
+  Array.prototype.map.call(links, function(item) {
+    if (item.host != document.location.host) {
+      item.addEventListener("click", function() {
+        var action = item.getAttribute("data-md-action") || "follow";
+        ga("send", "event", "outbound", action, item.href);
+      });
+    }
+  });
+
+  /* Register handler to log search on blur */
+  var query = document.forms.search.query;
+  query.addEventListener("blur", function() {
+    if (this.value) {
+      var path = document.location.pathname;
+      ga("send", "pageview", path + "?q=" + this.value);
+    }
+  });
+</script>