From f4f4ce87ba00343d9871ab55b91577a10aa2e415 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Thu, 2 Nov 2017 20:13:54 +0100
Subject: [PATCH] theme: new :header: and :footer: page fields.

I'm putting the page-specific navigation there, because otherwise
highlighting the last page section would highlight the nav as well and
that is just wrong in so many ways.
---
 doc/admire/math.rst               | 10 +++---
 doc/css/components.rst            | 10 +++---
 doc/css/grid.rst                  | 10 +++---
 doc/css/page-layout.rst           | 10 +++---
 doc/css/themes.rst                | 10 +++---
 doc/css/typography.rst            | 10 +++---
 doc/pelican/theme-test.rst        | 14 +++++++--
 doc/pelican/theme.rst             | 52 ++++++++++++++++++++++++++-----
 doc/pelican/writing-content.rst   | 10 +++---
 doc/plugins/components.rst        | 10 +++---
 doc/plugins/htmlsanity.rst        | 10 +++---
 doc/plugins/images.rst            | 10 +++---
 doc/plugins/links.rst             | 10 +++---
 doc/plugins/math-and-code.rst     | 10 +++---
 pelican-theme/templates/page.html | 22 +++++++++++++
 site/pelicanconf.py               |  2 +-
 16 files changed, 140 insertions(+), 70 deletions(-)

diff --git a/doc/admire/math.rst b/doc/admire/math.rst
index 86a934a9..e2b79087 100644
--- a/doc/admire/math.rst
+++ b/doc/admire/math.rst
@@ -34,6 +34,11 @@ m.css math
 :url: admire/math/
 :cover: {filename}/static/cover-math.jpg
 :summary: The fastest possible math rendering for the modern web
+:footer:
+    .. note-dim::
+
+        *Wondering what m.css is all about?* Visit the `main page <{filename}/index.rst>`_
+        to see what else it can offer to you.
 :landing:
     .. container:: m-row
 
@@ -189,8 +194,3 @@ line spacing and that nothing gets relayouted during page load:
     .. class:: m-text m-text-right m-dim m-em
 
     ---  `Discrete Fourier transform § Shift theorem <https://en.wikipedia.org/wiki/Discrete_Fourier_transform#Shift_theorem>`_, Wikipedia
-
-.. note-dim::
-
-    *Wondering what m.css is all about?* Visit the `main page <{filename}/index.rst>`_
-    to see what else it can offer to you.
diff --git a/doc/css/components.rst b/doc/css/components.rst
index 9971a203..727f1389 100644
--- a/doc/css/components.rst
+++ b/doc/css/components.rst
@@ -26,6 +26,11 @@ Components
 ##########
 
 :breadcrumb: {filename}/css.rst CSS
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Typography <{filename}/css/typography.rst>`_ | `CSS <{filename}/css.rst>`_ | `Page layout » <{filename}/css/page-layout.rst>`_
 
 ``m.css`` provides a set of basic components for further improving the layout
 and display of authored content.
@@ -912,8 +917,3 @@ element overflows.
 
 There's also :css:`.m-fullwidth` that will make your element always occupy 100%
 of the parent element width. Useful for tables or images.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Typography <{filename}/css/typography.rst>`_ | `CSS <{filename}/css.rst>`_ | `Page layout » <{filename}/css/page-layout.rst>`_
diff --git a/doc/css/grid.rst b/doc/css/grid.rst
index 200a80e6..0e16ab52 100644
--- a/doc/css/grid.rst
+++ b/doc/css/grid.rst
@@ -26,6 +26,11 @@ Grid system
 ###########
 
 :breadcrumb: {filename}/css.rst CSS
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `CSS <{filename}/css.rst>`_ | `Typography » <{filename}/css/typography.rst>`_
 
 .. role:: css(code)
     :language: css
@@ -367,8 +372,3 @@ you to spot the problems better:
 Other than highlighting problems, this file doesn't alter your website
 appearance in any way. To save unnecessary requests and bandwidth, I recommend
 that you remove the reference again when publishing the website.
-
-.. note-dim::
-    :class: m-text-center
-
-    `CSS <{filename}/css.rst>`_ | `Typography » <{filename}/css/typography.rst>`_
diff --git a/doc/css/page-layout.rst b/doc/css/page-layout.rst
index 14dfa522..f0d3862d 100644
--- a/doc/css/page-layout.rst
+++ b/doc/css/page-layout.rst
@@ -26,6 +26,11 @@ Page layout
 ###########
 
 :breadcrumb: {filename}/css.rst CSS
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Components <{filename}/css/components.rst>`_ | `CSS <{filename}/css.rst>`_ | `Themes » <{filename}/css/themes.rst>`_
 
 .. role:: raw-html(raw)
    :format: html
@@ -639,8 +644,3 @@ and save vertical space. For a tag cloud, mark the :html:`<ul>` with
             </ul>
           </div>
         </nav>
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Components <{filename}/css/components.rst>`_ | `CSS <{filename}/css.rst>`_ | `Themes » <{filename}/css/themes.rst>`_
diff --git a/doc/css/themes.rst b/doc/css/themes.rst
index 5496f5d2..40201796 100644
--- a/doc/css/themes.rst
+++ b/doc/css/themes.rst
@@ -26,6 +26,11 @@ Themes
 ######
 
 :breadcrumb: {filename}/css.rst CSS
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Page layout <{filename}/css/page-layout.rst>`_ | `CSS <{filename}/css.rst>`_
 
 .. role:: css(code)
     :language: css
@@ -122,8 +127,3 @@ then generate a CSS file out of it:
 
     Made a theme and want to share it with the world? I'm happy to
     :gh:`incorporate your contributions <mosra/m.css/pulls/new>`.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Page layout <{filename}/css/page-layout.rst>`_ | `CSS <{filename}/css.rst>`_
diff --git a/doc/css/typography.rst b/doc/css/typography.rst
index 9ebf37da..b053fb20 100644
--- a/doc/css/typography.rst
+++ b/doc/css/typography.rst
@@ -26,6 +26,11 @@ Typography
 ##########
 
 :breadcrumb: {filename}/css.rst CSS
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Grid <{filename}/css/grid.rst>`_ | `CSS <{filename}/css.rst>`_ | `Components » <{filename}/css/components.rst>`_
 
 .. role:: css(code)
     :language: css
@@ -330,8 +335,3 @@ for aligning and floating blocks in a similar way.
 Block elements :html:`<p>`, :html:`<ol>`, :html:`<ul>`, :html:`<dl>`,
 :html:`<blockqote>`, :html:`<pre>` and :html:`<hr>` by default have :css:`1rem`
 padding after, except when they are the last child, to avoid excessive spacing.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Grid <{filename}/css/grid.rst>`_ | `CSS <{filename}/css.rst>`_ | `Components » <{filename}/css/components.rst>`_
diff --git a/doc/pelican/theme-test.rst b/doc/pelican/theme-test.rst
index 5bcdb8ae..f00a82b7 100644
--- a/doc/pelican/theme-test.rst
+++ b/doc/pelican/theme-test.rst
@@ -31,6 +31,16 @@ Test
 :css: {filename}/static/dummy.css
       {filename}/static/dummy.css
 :summary: um
+:header:
+    .. note-warning::
 
-This page should have a breadcrumb and also two additional links to
-``/static/dummy.css``.
+        This is a page header with an `internal link <{filename}/pelican.rst>`_.
+        This shouldn't be wrapped in a ``<p>``.
+:footer:
+    .. note-danger::
+
+        This is a page footer with an `internal link <{filename}/pelican.rst>`_.
+        This shouldn't be wrapped in a ``<p>``.
+
+This page should have a breadcrumb, summary in a meta tag, header and a footer
+and also two additional links to ``/static/dummy.css``.
diff --git a/doc/pelican/theme.rst b/doc/pelican/theme.rst
index a1b41eed..aeb9c967 100644
--- a/doc/pelican/theme.rst
+++ b/doc/pelican/theme.rst
@@ -26,6 +26,11 @@ Theme
 #####
 
 :breadcrumb: {filename}/pelican.rst Pelican
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Writing content <{filename}/pelican/writing-content.rst>`_ | `Pelican <{filename}/pelican.rst>`_
 
 .. role:: rst(code)
     :language: rst
@@ -196,8 +201,9 @@ documentation, populating the last column implicitly:
 
 Page content is simply put into :html:`<main>`, wrapped in an :html:`<article>`,
 in the center 10 columns on large screens and spanning the full 12 columns
-elsewhere. Page title is rendered in an :html:`<h1>` and there's nothing else
-apart from the page content.
+elsewhere; the container is marked as `inflatable <{filename}/css/grid.rst#inflatable-nested-grid>`_.
+Page title is rendered in an :html:`<h1>` and there's nothing else apart from
+the page content.
 
 `Extra CSS`_
 ------------
@@ -302,6 +308,43 @@ destination and URL.
 
     You can see the landing page in action on the `main project page <{filename}/index.rst>`_.
 
+`Page header and footer`_
+-------------------------
+
+It's possible to add extra :abbr:`reST <reStructuredText>`-processed content
+(such as page-specific navigation) before and after the page contents by
+putting it into :rst:`:header:` / :rst:`:footer:` fields. Compared to having
+these directly in page content, these will be put semantically outside the page
+:html:`<article>` element (so even before the :html:`<h1>` heading and after
+the last :html:`<section>` ends). The header / footer is put, equivalently to
+page content, in the center 10 columns on large screens and spanning the full
+12 columns elsewhere; the container is marked as `inflatable`_. Example of a
+page-specific footer navigation, extending the breadcrumb navigation from
+above:
+
+.. code:: rst
+
+    Steam engine
+    ############
+
+    :breadcrumb: {filename}/help.rst Help
+                 {filename}/help/components.rst Components
+    :footer:
+        `« Water tank <{filename}/help/components/water-tank.rst>`_ |
+        `Components <{filename}/help/components.rst>`_ |
+        `Chimney » <{filename}/help/components/chimney.rst>`_
+
+.. block-warning:: Configuration
+
+    Similarly to landing page content, in order to have the :rst:`:header:` /
+    :rst:`:footer:` fields properly parsed, you need to explicitly list them in
+    :py:`FORMATTED_FIELDS`. Don't forget that :py:`'summary'` is already listed
+    there.
+
+    .. code:: py
+
+        FORMATTED_FIELDS += ['header', 'footer']
+
 `(Social) meta tags for pages`_
 -------------------------------
 
@@ -459,8 +502,3 @@ is valid HTML5 and should be parsable as XML.
 
     This is one of the main goals of this project. Please
     :gh:`report a bug <mosra/m.css/issues/new>` if it's not like that.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Writing content <{filename}/pelican/writing-content.rst>`_ | `Pelican <{filename}/pelican.rst>`_
diff --git a/doc/pelican/writing-content.rst b/doc/pelican/writing-content.rst
index 7c9704e8..ecf523b7 100644
--- a/doc/pelican/writing-content.rst
+++ b/doc/pelican/writing-content.rst
@@ -26,6 +26,11 @@ Writing content
 ###############
 
 :breadcrumb: {filename}/pelican.rst Pelican
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `Pelican <{filename}/pelican.rst>`_ | `Theme » <{filename}/pelican/theme.rst>`_
 
 While the official `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
 documentation provides an extensive syntax guide, the info is scattered across
@@ -434,8 +439,3 @@ Again, ``m.css`` provides `Pelican plugins`_ that allow you to have inline
 code, math, GitHub and Doxygen links and much more. Head over to the official
 :abbr:`reST <reStructuredText>` documentation for
 `more info about builtin roles <http://docutils.sourceforge.net/docs/ref/rst/roles.html>`_.
-
-.. note-dim::
-    :class: m-text-center
-
-    `Pelican <{filename}/pelican.rst>`_ | `Theme » <{filename}/pelican/theme.rst>`_
diff --git a/doc/plugins/components.rst b/doc/plugins/components.rst
index f9ebebb8..9c81a373 100644
--- a/doc/plugins/components.rst
+++ b/doc/plugins/components.rst
@@ -26,6 +26,11 @@ Components
 ##########
 
 :breadcrumb: {filename}/plugins.rst Pelican plugins
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« HTML sanity <{filename}/plugins/htmlsanity.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Images » <{filename}/plugins/images.rst>`_
 
 .. role:: rst(code)
     :language: rst
@@ -332,8 +337,3 @@ arranging content in three-column grid can be done like this:
         .. container:: m-col-m-4 m-text-center
 
             Right column content.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« HTML sanity <{filename}/plugins/htmlsanity.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Images » <{filename}/plugins/images.rst>`_
diff --git a/doc/plugins/htmlsanity.rst b/doc/plugins/htmlsanity.rst
index c6f6bad8..dde2f61d 100644
--- a/doc/plugins/htmlsanity.rst
+++ b/doc/plugins/htmlsanity.rst
@@ -26,6 +26,11 @@ HTML sanity
 ###########
 
 :breadcrumb: {filename}/plugins.rst Pelican plugins
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `Pelican plugins <{filename}/plugins.rst>`_ | `Components » <{filename}/plugins/components.rst>`_
 
 .. role:: html(code)
     :language: html
@@ -340,8 +345,3 @@ There are already
 that try to do similar things, but they *attempt* to fix it using BeautifulSoup
 on top of the generated HTML. That's a horrendous thing to do, so why not just
 prevent the horror from happening?
-
-.. note-dim::
-    :class: m-text-center
-
-    `Pelican plugins <{filename}/plugins.rst>`_ | `Components » <{filename}/plugins/components.rst>`_
diff --git a/doc/plugins/images.rst b/doc/plugins/images.rst
index ee78d780..4c0bf0c7 100644
--- a/doc/plugins/images.rst
+++ b/doc/plugins/images.rst
@@ -26,6 +26,11 @@ Images
 ######
 
 :breadcrumb: {filename}/plugins.rst Pelican plugins
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Components <{filename}/plugins/components.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Math and code » <{filename}/plugins/math-and-code.rst>`_
 
 Gives sane defaults to images and figures and provides a way to present
 beautiful image galleries.
@@ -140,8 +145,3 @@ with non-repeating images, head over to `my blog <http://blog.mosra.cz/cesty/mai
     the images present on a filesystem to extract size information. It's
     advised to use the builtin *absolute* ``{filename}`` or ``{attach}`` syntax
     for `linking to internal content <http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content>`_.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Components <{filename}/plugins/components.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Math and code » <{filename}/plugins/math-and-code.rst>`_
diff --git a/doc/plugins/links.rst b/doc/plugins/links.rst
index 5711cb7c..6aee7694 100644
--- a/doc/plugins/links.rst
+++ b/doc/plugins/links.rst
@@ -26,6 +26,11 @@ Links
 #####
 
 :breadcrumb: {filename}/plugins.rst Pelican plugins
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Math and code <{filename}/plugins/math-and-code.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_
 
 .. role:: py(code)
     :language: py
@@ -235,8 +240,3 @@ first before calculating the size.
     :filesize:`{filename}/../css/m-dark.compiled.css` but only
     :filesize-gz:`{filename}/../css/m-dark.compiled.css` when the server
     sends it compressed.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Math and code <{filename}/plugins/math-and-code.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_
diff --git a/doc/plugins/math-and-code.rst b/doc/plugins/math-and-code.rst
index ebf14748..131fea30 100644
--- a/doc/plugins/math-and-code.rst
+++ b/doc/plugins/math-and-code.rst
@@ -26,6 +26,11 @@ Math and code
 #############
 
 :breadcrumb: {filename}/plugins.rst Pelican plugins
+:footer:
+    .. note-dim::
+        :class: m-text-center
+
+        `« Images <{filename}/plugins/images.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Links » <{filename}/plugins/links.rst>`_
 
 .. role:: css(code)
     :language: css
@@ -195,8 +200,3 @@ specify which language should be highlighted, derive a custom role from it:
     With the :cmake:`add_executable(foo bar.cpp)` CMake command you can create
     an executable from a file that contains just :cpp:`int main() { return 666; }`
     and nothing else.
-
-.. note-dim::
-    :class: m-text-center
-
-    `« Images <{filename}/plugins/images.rst>`_ | `Pelican plugins <{filename}/plugins.rst>`_ | `Links » <{filename}/plugins/links.rst>`_
diff --git a/pelican-theme/templates/page.html b/pelican-theme/templates/page.html
index a1f3d169..abc26b39 100644
--- a/pelican-theme/templates/page.html
+++ b/pelican-theme/templates/page.html
@@ -41,6 +41,17 @@
 {% endblock %}
 
 {% block main %}
+{% if page.header %}
+<div class="m-container m-container-inflatable">
+  <div class="m-row">
+    <div class="m-col-l-10 m-push-l-1 m-nopadb">
+<!-- header -->
+{{ page.header|expand_links(page) -}}
+<!-- /header -->
+    </div>
+  </div>
+</div>
+{% endif %}
 <article>
   {% if page.landing %}
   <div id="m-landing-image"{% if page.cover %} style="background-image: url('{{ page.cover|expand_link(page) }}');"{% endif %}>
@@ -77,4 +88,15 @@
     </div>
   </div>
 </article>
+{% if page.footer %}
+<div class="m-container m-container-inflatable">
+  <div class="m-row">
+    <div class="m-col-l-10 m-push-l-1 m-nopadt">
+<!-- footer -->
+{{ page.footer|expand_links(page) -}}
+<!-- /footer -->
+    </div>
+  </div>
+</div>
+{% endif %}
 {% endblock %}
diff --git a/site/pelicanconf.py b/site/pelicanconf.py
index cd2b07d2..26e59607 100644
--- a/site/pelicanconf.py
+++ b/site/pelicanconf.py
@@ -128,7 +128,7 @@ CSS_FILES = ['https://fonts.googleapis.com/css?family=Source+Code+Pro:400,400i,6
 #CSS_FILES = ['https://fonts.googleapis.com/css?family=Libre+Baskerville:400,400i,700%7CSource+Code+Pro:400,400i,600',
              #'/static/m-light.css']
 
-FORMATTED_FIELDS = ['summary', 'landing']
+FORMATTED_FIELDS = ['summary', 'landing', 'header', 'footer']
 
 M_HTMLSANITY_SMART_QUOTES = True
 M_HTMLSANITY_HYPHENATION = True
-- 
2.30.2