Document pagekind usefulness

getnikola · Aug 25, 2015 · 3004e81 · 3004e81
1 parent 41b6c33
commit 3004e81
Showing 1 changed file with 67 additions and 0 deletions.
diff --git a/stories/creating-a-theme.txt b/stories/creating-a-theme.txt
@@ -761,6 +761,73 @@ Similar changes (basically adding class names to elements) needed to be done in
         </header>
     </%def>
 
+Identifying and customizing different kinds of pages
+----------------------------------------------------
+
+Nikola provides a `pagekind` in each template contexts that can be used to
+modify shared templates based on the context it’s being used. For example,
+the ``base_helper.tmpl`` is used in all pages, ``indexes.tmpl`` is used in
+many contexts and you may want to add or remove something from only one of
+these contexts.
+
+Example of conditionally loading different resources on all index pages
+(archives, author pages, and tag pages), and others again o the front page
+and in every post pages:
+
+.. code:: html+mako
+
+    <head>
+        …
+        % if 'index' in pagekind:
+            <link href="/assets/css/multicolumn.css" rel="stylesheet">
+        % endif
+        % if 'front_page' in pagekind:
+            <link href="/assets/css/fancy_homepage.css" rel="stylesheet">
+            <script src="/assets/js/post_carousel.js"></script>
+        % endif
+        % if 'post_page' in pagekind:
+            <link href="/assets/css/article.css" rel="stylesheet">
+            <script src="/assets/js/comment_system.js"></script>
+        % endif
+    </head>
+
+Promoting visits to the front page when visiting other filtered
+``index.tmpl`` page variants such as author pages and tag pages. This
+could have been included in ``index.tmpl`` or maybe in ``base.tmpl``
+depending on what you want to achieve.
+
+.. code:: html+mako
+
+    % if 'index' in pagekind:
+        % if 'author_page' in postkind:
+            <p>These posts were written by ${author}. See posts by all
+               authors on the <a href="/">front page</a>.</p>
+        % elif 'tag_page' in postkind:
+            <p>This is a filtered selection of posts tagged “${tag}”, visit
+               the <a href="/">front page</a> to see all posts.</p>
+        % endif
+    % endif 
+
+
+List of page kinds provided by default plugins:
+
+* front_page
+* index
+* index, archive_page
+* index, author_page
+* index, tag_page
+* list
+* list, archive_page
+* list, author_page
+* list, tag_page
+* list, tags_page
+* post_page
+* story_page
+* listing
+* generic_page
+* gallery_front
+* gallery_page
+
 Customization
 -------------