From: Vladimír Vondruš Date: Wed, 6 Dec 2017 11:36:58 +0000 (+0100) Subject: theme: ability to control article expansion and summary appearance. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=7910a9090ae6a04113d4b9068585dc36cc917efb;p=blog.git theme: ability to control article expansion and summary appearance. --- diff --git a/doc/examples/article-hide-summary.rst b/doc/examples/article-hide-summary.rst new file mode 100644 index 00000000..37c997af --- /dev/null +++ b/doc/examples/article-hide-summary.rst @@ -0,0 +1,50 @@ +.. + This file is part of m.css. + + Copyright © 2017 Vladimír VondruÅ¡ + + 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 NONINFRINGEMENT. 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. +.. + +Article with hidden summary +########################### + +.. role:: language-la + :class: language-la + +:date: 2017-12-06 0:00 +:category: Examples +:tags: Special +:author: An Author +:slug: article-hide-summary +:hide_summary: True + +Implicit article summary paragraph. :language-la:`Lorem ipsum dolor sit amet, +consectetur adipiscing elit. Aenean id elit posuere, consectetur magna congue, +sagittis est.` + +Article contents. :language-la:`Pellentesque est neque, aliquet nec consectetur +in, mattis ac diam. Aliquam placerat justo ut purus interdum, ac placerat lacus +consequat. Mauris id suscipit mauris, in scelerisque lectus. Aenean nec nunc eu +sem tincidunt imperdiet ut non elit. Integer nisi tellus, ullamcorper vitae +euismod quis, venenatis eu nulla.` + +.. note-info:: + + Compare the look to an `article containing explicit summary <{filename}/examples/article.rst>`_. diff --git a/doc/examples/jumbo-article-hide-summary.rst b/doc/examples/jumbo-article-hide-summary.rst new file mode 100644 index 00000000..d893a838 --- /dev/null +++ b/doc/examples/jumbo-article-hide-summary.rst @@ -0,0 +1,51 @@ +.. + This file is part of m.css. + + Copyright © 2017 Vladimír VondruÅ¡ + + 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 NONINFRINGEMENT. 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. +.. + +Article with hidden summary --- a jumbo one +########################################### + +.. role:: language-la + :class: language-la + +:cover: {filename}/static/ship.jpg +:date: 2017-12-06 1:00 +:category: Examples +:tags: Jumbo, Special +:author: An Author +:slug: jumbo-article-hide-summary +:hide_summary: True + +Implicit article summary paragraph. :language-la:`Lorem ipsum dolor sit amet, +consectetur adipiscing elit. Aenean id elit posuere, consectetur magna congue, +sagittis est.` + +Article contents. :language-la:`Pellentesque est neque, aliquet nec consectetur +in, mattis ac diam. Aliquam placerat justo ut purus interdum, ac placerat lacus +consequat. Mauris id suscipit mauris, in scelerisque lectus. Aenean nec nunc eu +sem tincidunt imperdiet ut non elit. Integer nisi tellus, ullamcorper vitae +euismod quis, venenatis eu nulla.` + +.. note-info:: + + Compare the look to a `jumbo article containing explicit summary <{filename}/examples/jumbo-article.rst>`_. diff --git a/doc/pelican/theme.rst b/doc/pelican/theme.rst index d8c886b0..470a65bd 100644 --- a/doc/pelican/theme.rst +++ b/doc/pelican/theme.rst @@ -492,6 +492,55 @@ supported in a similar way: URL of e.g. the `jumbo article`_ into either `Facebook Debugger`_ or `Twitter Card Validator`_. +`Controlling article appearance`_ +--------------------------------- + +By default, the theme assumes that you provide an explicit :rst:`:summary:` +field for each article. The summary is then displayed on article listing page +and also prepended to fully expanded article. If your :rst:`:summary:` is +automatically generated by Pelican or for any other reason repeats article +content, it might not be desirable to show it in combination with article +content. This can be configured via the following setting: + +.. code:: py + + M_HIDE_ARTICLE_SUMMARY = True + +There's also a possibility to control this on a per-article basis by setting +:rst:`:hide_summary:` to either :py:`True` or :py:`False`. If both global and +per-article setting is present, article-specific setting has a precedence. +Example: + +.. code:: rst + + An article without explicit summary + ################################### + + :cover: {filename}/static/ship.jpg + :hide_summary: True + + Implicit article summary paragraph. + + Article contents. + +.. note-info:: + + Here's the visual appearance of an `article without explicit summary <{filename}/examples/article-hide-summary.rst>`_ + and a corresponding `jumbo article <{filename}/examples/jumbo-article-hide-summary.rst>`__. + +As noted above, the first article is by default fully expanded on index and +archive page. However, sometimes the article is maybe too long to be expanded +or you might want to not expand any article at all. This can be controlled +either globally using the following setting: + +.. code:: py + + M_COLLAPSE_FIRST_ARTICLE = True + +Or, again, on a per-article basis, by setting :rst:`:collapse_first:` to either +:py:`True` or :py:`False`. If both global and per-article setting is present, +article-specific setting has a precedence. + `Pre-defined pages`_ ==================== diff --git a/pelican-theme/templates/archives.html b/pelican-theme/templates/archives.html index bc7f0fd7..28f5268e 100644 --- a/pelican-theme/templates/archives.html +++ b/pelican-theme/templates/archives.html @@ -18,7 +18,9 @@
{% macro header() %}{% include "article_header.html" %}{% endmacro %} {{ header()|indent(8) }} - {% if loop.first and articles_page.number == 1 %} + {% if loop.first and articles_page.number == 1 and + ((article.collapse_first is defined and article.collapse_first != 'True') or + (article.collapse_first is not defined and not M_COLLAPSE_FIRST_ARTICLE)) %}
{{ article.content }} diff --git a/pelican-theme/templates/article.html b/pelican-theme/templates/article.html index c948f4e7..4a3e47cc 100644 --- a/pelican-theme/templates/article.html +++ b/pelican-theme/templates/article.html @@ -49,6 +49,8 @@ + {% if (article.hide_summary is defined and article.hide_summary != 'True') or + (article.hide_summary is not defined and not M_HIDE_ARTICLE_SUMMARY) %}
@@ -56,6 +58,7 @@
+ {% endif %}
diff --git a/pelican-theme/templates/article_header.html b/pelican-theme/templates/article_header.html index fd782411..a05b659a 100644 --- a/pelican-theme/templates/article_header.html +++ b/pelican-theme/templates/article_header.html @@ -6,5 +6,19 @@ {{ article.title }} + {# Display summary only if: + - we're on article listing page and the article is not expanded (it's + expanded only if it's first on the first page only on the index/archive + page and only if it doesn't say it should be collapsed) + - the article is expanded but doesn't say the summary should be hidden #} + {% if (articles_page and + (page_name not in ['index', 'archives'] or + not loop.first or + articles_page.number != 1 or + (article.collapse_first is defined and article.collapse_first == 'True') or + (article.collapse_first is not defined and M_COLLAPSE_FIRST_ARTICLE))) or + (article.hide_summary is defined and article.hide_summary != 'True') or + (article.hide_summary is not defined and not M_HIDE_ARTICLE_SUMMARY) %} {{ article.summary|indent(2) }} + {% endif %} diff --git a/pelican-theme/templates/index.html b/pelican-theme/templates/index.html index bc7f0fd7..28f5268e 100644 --- a/pelican-theme/templates/index.html +++ b/pelican-theme/templates/index.html @@ -18,7 +18,9 @@
{% macro header() %}{% include "article_header.html" %}{% endmacro %} {{ header()|indent(8) }} - {% if loop.first and articles_page.number == 1 %} + {% if loop.first and articles_page.number == 1 and + ((article.collapse_first is defined and article.collapse_first != 'True') or + (article.collapse_first is not defined and not M_COLLAPSE_FIRST_ARTICLE)) %}
{{ article.content }}