--- /dev/null
+..
+ This file is part of m.css.
+
+ Copyright © 2017 Vladimír Vondruš <mosra@centrum.cz>
+
+ 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>`_.
--- /dev/null
+..
+ This file is part of m.css.
+
+ Copyright © 2017 Vladimír Vondruš <mosra@centrum.cz>
+
+ 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>`_.
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`_
====================
<article>
{% 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)) %}
<div class="m-clearfix-l"></div>
<!-- content -->
{{ article.content }}
</div>
</div>
</div>
+ {% if (article.hide_summary is defined and article.hide_summary != 'True') or
+ (article.hide_summary is not defined and not M_HIDE_ARTICLE_SUMMARY) %}
<div class="m-container">
<div class="m-row">
<div class="m-col-m-10 m-push-m-1 m-nopady">
</div>
</div>
</div>
+ {% endif %}
</header>
<div class="m-container m-container-inflatable">
<div class="m-row">
</time>
{{ article.title }}
</a></h1>
+ {# 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 %}
</header>
<article>
{% 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)) %}
<div class="m-clearfix-l"></div>
<!-- content -->
{{ article.content }}
~cjwatson / blog.git / commitdiff