Merge pull request #445 from Pelican-Elegant/next

Next release

.travis.yml

@@ -22,7 +22,6 @@ cache:
 
 install:
 - pip install -r documentation/requirements.txt
-- pip install -U Online-W3C-Validator
 - pip install -U html5validator
 - pip install -U pre-commit
 - yarn global add yaspeller

.yaspeller.json

@@ -29,6 +29,8 @@
     "AWegnerGitHub",
     "Ayub",
     "Baskerville",
+    "BestAzon",
+    "bestazon",
     "bing",
     "Blais",
     "blog-o-matic",
@@ -73,6 +75,7 @@
     "github",
     "github.com",
     "google",
+    "gravatar",
     "gshen42",
     "Gómez",
     "Hi Talha",
@@ -81,6 +84,7 @@
     "https",
     "Iconifier.net",
     "ijvxwtg",
+    "imgur",
     "io",
     "iOS",
     "iranzo",

documentation/content/Appearance and Style/modified-date.md

@@ -12,18 +12,19 @@ authors: Talha Mansoor
 ---
 
 You need to update your articles time and again. Sometimes it makes sense to
-display the date when you updated the article. You can show the last updated
+display the date when you updated the article.
+
+Pelican release [v3.4.0](http://docs.getpelican.com/en/stable/changelog.html#id9) has a new
+[ metadata field `modified`](https://github.com/getpelican/pelican/pull/1148). Type of
+its value is `datetime`.
+
+You can show the last updated
 date of the article by defining `modified` in your article metadata.
 
 This is how it is displayed in the side bar,
 
 ![Modified Date]({static}/images/elegant-theme_last-modified.png)
 
-Pelican post [version
-3.3](https://github.com/getpelican/pelican/releases/tag/3.3.0) has a new
-[`modified` metadata](https://github.com/getpelican/pelican/pull/1148). Type of
-its value is `datetime`.
-
 Depending on your
 [`DATE_FORMATS`](http://docs.getpelican.com/en/latest/settings.html#basic-settings)
 setting you can put modified date in your reST formatted file as
@@ -33,9 +34,32 @@ setting you can put modified date in your reST formatted file as
 
 Elegant will process it and display the last updated as "Jan 22, 2014".
 
-Previous versions do not have `modified` metadata in which case type of its
-value is string. If you are using old version of Pelican, i.e 3.3 or less, make
-sure you assign it a value exactly the way you want it to appear. Taking the
+!!! important "Condition to Display Last Updated"
+
+    Last Updated is only displayed if the difference between `article.modifed`
+    and `article.date`is more than or equal to a day.
+
+    This means if you modify and article the same day you add it, then Last
+    Updated will not be displayed.
+
+!!! tip
+
+    You may want to enable
+    [`filetime_from_git`](https://github.com/getpelican/pelican-plugins/tree/master/filetime_from_git)
+    Pelican plugin to auto fill the modified field for your Git commit history.
+
+### Deprecated
+
+!!! Danger "Warning: Legacy Variable"
+
+    Pelican versions prior to 3.4 does not have `modified` metadata in which case type of its
+    value is string.
+
+If you are using old version of Pelican, i.e 3.3 or less, make
+sure you assign it a value exactly the way you want it to appear.
+Whatever you type, it will appear as it is.
+
+Taking the
 example from above, metadata in your reST formatted file should be,
 
     :::Rest

documentation/content/Appearance and Style/table-of-contents.md

@@ -8,115 +8,157 @@ Disqus_identifier: lm95rjd-how-elegant-displays-table-of-contents
 Subtitle:
 Summary: Elegant shows Table of Contents, if available, non intrusively to give a clean reading experience to the visitor
 Keywords:
-authors: Talha Mansoor
+Authors: Talha Mansoor, Jack De Winter
 ---
 
 [TOC]
 
-The idea behind Elegant's design is to make reading a clean and distraction
-free experience. Table of contents is important but it is not part of the
-article content. Therefore, Elegant pushes out table of content to the left of
-the article's main content. Its font size is relatively smaller. This way,
-table of content stays visible for navigation but reader's attention to the
-article stays unaffected.
+The key concept driving Elegant's design is to provide a reading experience that
+is clean with minimal distractions. From that point of view, providing a table of
+contents does not provide any additional information, but only exists to help guide the
+reader through the article.
 
-To utilize this feature, you need to use
-[extract_toc](https://github.com/getpelican/pelican-plugins) plugin. Elegant
-encloses the table of content in `<nav>` tag for semantics.
+Therefore, Elegant places the table of contents on the left side
+of the page with a relatively smaller font. This enables the table to guide the reader without
+grabbing the focus of the reader and distracting them.
 
-You also need to make sure your markup format generates a table of contents of
-your article.
+## Plugin Configuration
 
-# Markdown Format
+Enabling the Elegant' display of the table of contents is a two-step process.
 
-For Markdown, make sure you have enabled `toc` extension in Pelican
-configuration.
+In the first step,
+use the markup languages to provide table of contents.
 
-    :::python
-    MD_EXTENSIONS = ['toc']
+Second step is to take the generated table of contents and display it
+on the left side of the article.
 
-Next, add `[TOC]` in your article's markup. Here is a `sample.md` file.
+If both steps are not completed,
+the table of contents will not be displayed on the left side of the article.
 
-    :::markdown
-    Title: My sample title
-    Date: 2014-12-03
-    Category: Examples
+For the second step, you need to enable the `extract_toc` plugin in
+your pelican configuration.
 
-    [TOC]
+```python
+PLUGINS = ['extract_toc']
+```
 
-    This is my first heading
-    ========================
+## Configuring Markdown
 
-    This is the content of my sample blog post.
+You need to enable the `toc` extension for Markdown in your Pelican configuration.
 
-    This my second heading
-    ======================
+```python
+MARKDOWN = {
+  'extension_configs': {
+    'markdown.extensions.toc': {}
+  }
+}
+```
 
-    I will end my example here.
+Now to generate a table of contents for you article, add the `[TOC]` markdown tag to your
+document.
 
-That's it. Your article's table of contents will appear on the left side of the
-actual content.
+```Markdown
+Title: My sample title
+Date: 2014-12-03
+Category: Examples
 
-## Enable Permalinks
+[TOC]
+
+## This is my first heading
+
+This is the content of my sample blog post.
+
+## This my second heading
 
-You can also take advantage of `permalink` option in `toc` extension.
+I will end my example here.
+```
 
-    :::python
-    MD_EXTENSIONS = ['toc(permalink=true)']
+### Enabling Permalinks
 
-This will generate
-[permalinks](https://github.com/waylan/Python-Markdown/pull/252) for every
-heading. Elegant keeps them hidden until user hovers over the heading.
+Although it is not required, we recommend you to take advantage of `permalink` option available for the
+`toc` extension.
+
+Enabling the `permalink` option will
+provide direct links to each section.
 
 ![Permalinks example using Markdown]({static}/images/elegant-theme-toc-permalinks.png)
 
-# reStructuredText Format
+To enable this option, you need to add the `'permalink': 'true'` property to the
+`'markdown.extensions.toc'` section that was added in the previous section.
+
+```python
+MARKDOWN = {
+  'extension_configs': {
+    'markdown.extensions.toc': {
+      'permalink': 'true',
+    }
+  }
+}
+```
+
+### Other Options
 
-reStructuredText format has
-[`contents`](http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents)
-directive that generates table of contents of the post. Here is a `sample.rst`
-file.
+For other options available for the Markdown Table of Contents extension, refer to the
+[Python - Markdown - Table of Contents](https://python-markdown.github.io/extensions/toc/)
+page.
 
-    :::rest
-    My sample title
-    ###############
+### Debugging
 
-    :date: 2014-12-03
-    :category: Examples
+1. Verify that your Markdown file has `[TOC]` tag
+1. Verify that the
+   `MARKDOWN` configuration variable is set properly.
+1. Verify that the `PLUGINS` configuration variable is
+   set properly.
 
-    .. contents::
+## Configuring reStructuredText Format
 
-    This is my first heading
-    ========================
+reStructuredText format has the
+[`contents` directive](http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents)
+that generates a table of contents in the article.
 
-    This is the content of my sample blog post.
+To generate a table of contents for you article, add the `.. contents::` directive to your document.
 
-    This my second heading
-    ======================
+```rest
+My sample title
+###############
 
-    I will end my example here.
+:date: 2014-12-03
+:category: Examples
 
-## Hide Default Title Text
+.. contents::
 
-Unlike Markdown, reStructuredText generates a default title for the table of
-contents. From [official
+This is my first heading
+========================
+
+This is the content of my sample blog post.
+
+This my second heading
+======================
+
+I will end my example here.
+```
+
+### Hide Default Title Text
+
+!!! note "Possibly Deprecated"
+We couldn't not reproduce this issue in our testing. This should be considered deprecated, but is retained in this document in case someone encounters this.
+
+Using the default configuration, reStructuredText will generate a default title for the table
+of contents. According to the [official
 documentation](http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents),
 
 > Language-dependent boilerplate text will be used for the title. The English
 > default title text is "Contents".
 
-You end up having two titles for your table of contents, one generated by
-reStructuredText and the other by Elegant.
+This default configuration creates two titles for your table of contents, one generated by
+reStructuredText and the other by Elegant. To disable default title generation
+[^disable-title], you need to add following rule in your `custom.css` file to hide the
+duplicate title:
 
-Unfortunately, there is [no straightforward
-way](https://github.com/Pelican-Elegant/elegant/issues/54) to disable default
-title generation in reStructuredText. You need to add following rule in your
-`custom.css` file to hide the duplicate title.
-
-    :::css
-    div#contents p.topic-title.first {
-        display: none;
-    }
+```css
+div#contents p.topic-title.first {
+  display: none;
+}
+```
 
-See [this article](how-to-use-custom-css "How to use custom.css") to understand how you can use
-`custom.css`.
+[^disable-title]: There is [no straightforward way](https://github.com/Pelican-Elegant/elegant/issues/54) to disable default title generation in reStructuredText.

documentation/content/Elegant - Pelican Theme/author-blurbs.md

@@ -15,13 +15,27 @@ Keywords:
 At the end of each article, you can provide a small blurb about the author. This
 can be done by setting up the `AUTHORS` dictionary in your configuration file.
 
-    :::python
-    AUTHORS = {
-        u'Talha Mansoor': {
-            u'blurb': """ created Elegant Pelican theme, dabbles in Python, Vim-L and JavaScript. They can be reached on Github, Twitter and email.""",
-            u'url': 'https://github.com/talha131/'
-        },
-    }
+```python
+AUTHORS = {
+    "Talha Mansoor": {
+        "url": "https://www.oncrashreboot.com/",
+        "blurb": "is the creator and lead developer of Elegant theme.",
+        "avatar": "/images/avatars/talha131.png",
+    },
+    "Pablo Iranzo Gómez": {
+        "url": "http://iranzo.github.io",
+        "blurb": " opensource enthusiast and Lego fan doing some python simple programs like @redken_bot in telegram, etc",
+    },
+}
+```
+
+Key of every entry in `AUTHORS` dictionary is the author name, for example "Pablo Iranzo Gómez".
+
+The value of each key is a dictionary which has three keys.
+
+1. `url` (string) URL that could be link to author's homepage or profile
+1. `blurb` (string) brief introduction of author
+1. `avatar` (string) URL to author's avatar. You could link to an image on your site or to an image on Gravatar, Imgur or any other image host service
 
 Add an entry for each author you'd like a blurb to appear for.
 
@@ -33,15 +47,15 @@ file. Valid values are:
 
 - `author:` - This defines the _single_ author of the article.
 - `authors:` - This is a comma separated list of all article authors. Each known author will get a blurb. Each unknown author will not get a blurb.
-- Default author defined in your configuration file. If either of the two metatags above are not used, the default author you configured will be utilized. This author still requires an entry in the `AUTHORS` dictionary.
+- Default author defined in your configuration file. If either of the two metadata above are not used, the default author you configured will be utilized. This author still requires an entry in the `AUTHORS` dictionary.
 
-**Note:** If you define multiple authors, but use the `author:` metatag, a blurb
-will not be generated. This metatag is for a _single_ author. The correct way to
+**Note:** If you define multiple authors, but use the `author:` metadata, a blurb
+will not be generated. This metadata is for a _single_ author. The correct way to
 declare more than one author is to use `authors:`.
 
-This is an example of multiple authors using the following metatag value:
+This is an example of multiple authors using the following metadata value:
 
-    :::python
+    :::yaml
     authors: Talha Mansoor, Milton Bradley
 
 ![Author Blurb]({static}/images/author-blurb.png)