Merge pull request #408 from Pelican-Elegant/add-feat-docs

Add feat docs

documentation/content/Appearance and Style/article-count.md

@@ -0,0 +1,27 @@
+---
+Title: Articles Count With Every Tag & Category
+Tags: nuances
+layout: post
+Date: 2013-08-27 23:20
+comments: false
+Slug: articles-count-with-every-tag-and-category
+Category: Appearance & Style
+---
+
+Readers of an article on your site usually look for other articles on the same
+topic. Categories and tags are a way of showing them related articles. Elegant
+displays the count of articles that you have written in a category or tag in a
+non-intrusive manner.
+
+Every category and tag has the count of articles in superscript. So if you have
+written three articles in the C++ category or tag, it will have 3 in the
+superscript. This way visitor will know you have written other articles too on
+the same topic.
+
+Check out the screenshots,
+
+![Count of articles in a category is displayed in
+superscript]({static}/images/elegant-theme_category-superscript-count.png)
+
+![Count of articles that have been tagged is displayed in
+superscript]({static}/images/elegant-theme_tag-superscript-count.png)

documentation/content/Appearance and Style/article-subtitle.md

@@ -0,0 +1,24 @@
+---
+Title: Article Subtitle
+Tags: nuances
+layout: post
+Date: 2013-08-27 23:20
+comments: false
+Slug: article-subtitle
+Category: Appearance & Style
+---
+
+Pelican lets you define title of your article in the meta data. Elegant adds
+subtitle support. Just define `subtitle` in your article's meta data and it
+will appear along with your title. Here is an example,
+
+![Article subtitle
+example]({static}/images/elegant-theme_article-subtitle.png)
+
+Article subtitle is displayed with the title in every list. To keep it visibly
+separate from title, subtitle is enclosed in `<small>` tag. When visible cue
+cannot be used, like in the title attribute of HTML anchor tag `<a>`, a hyphen
+is inserted between them.
+
+![Article title and subtitle separated with a
+hyphen]({static}/images/elegant-theme_article-subtitle-hyphen.png)

documentation/content/Appearance and Style/page-title.md

@@ -0,0 +1,33 @@
+---
+Title: Page Title
+Tags: nuances
+layout: post
+Date: 2013-08-27 23:20
+comments: false
+Slug: page-title
+Category: Appearance & Style
+---
+
+Elegant follows following format for the `<title>` tag
+
+```
+Article title · Site Name
+```
+
+![Article title is always visible in the
+tab]({static}/images/elegant-theme_page-title.png)
+
+Some sites put site title first and article title later in the `<title>` tag.
+There is a problem with this approach. When you open too many tabs, browser
+delimits tab's title from the end. In such cases, only the first few words or
+even letters of the `<title>` are left visible.
+
+If visitor has opened several tabs from your website, all tabs will have "Site
+Name..." title. User will need to click on each tab to identify his required
+tab from the content. But with Elegant's approach article title will always be
+visible, and reader will have less difficultly in identifying the tab he is
+after.
+
+Putting site title before the article title increases your site name
+visibility. Elegant achieves this by putting site name in the top navigation
+bar of every page, where it always stays above the fold.

documentation/content/Appearance and Style/web-safe-fonts.md

@@ -0,0 +1,12 @@
+Title: Web Safe Fonts
+Tags: web-design
+Category: Appearance & Style
+Date: 2014-04-22 16:23
+Slug: web-safe-fonts
+
+Elegant uses commonly available typefaces in every style rule. It has a list of
+closely matching fonts in the fallback list.
+
+For examples Baskerville is the
+first choice for headings. But if reader does not have Baskerville installed,
+Garamond will be used. If that too fails then Georgia will be used.

documentation/content/Building Readership/landing-page.md

@@ -0,0 +1,102 @@
+---
+Title: Customize Home Page
+Tags: nuances, remarkable, unique
+layout: post
+Date: 2019-07-01 01:22
+comments: false
+Slug: customize-home-page
+Category: Building Readership
+---
+
+This is the page that visitors see when they open your website. Your chance to
+make a good and lasting first impression. Most sites just display a list of
+recent posts. Elegant goes the extra mile. Check this out
+
+![Home Page Sample]({static}/images/elegant-theme_home-page-features.png)
+
+You can see two sections here,
+
+1. About me
+1. My Projects
+
+There is a third section below these two sections, "Recent articles"
+
+![Recent Articles Section]({static}/images/elegant-theme_recent-posts.png)
+
+## Welcome Heading
+
+Define `LANDING_PAGE_TITLE` in your Pelican configuration. It will be displayed as the welcome heading. For example,
+
+```python
+LANDING_PAGE_TITLE = "Elegant – Why it is the Best Pelican Theme"
+```
+
+## About Me
+
+To write about me section, create a page. See [Pelican documentation](http://docs.getpelican.com/en/stable/content.html#pages) on how to create a page.
+
+The slug of the page should be `landing-page-about-hidden` and `status` should be `hidden`. Example,
+
+```yaml
+---
+author: Talha Mansoor
+title: What Is Elegant
+layout: page
+date: 2019-01-14 7:30:47 +0100
+status: hidden
+slug: landing-page-about-hidden
+---
+
+```
+
+The content of this will become your "About me" section, and title will become the heading. You can write content in any markup language, like Markdown, AsciiDoc or reST, as long as Pelican has supports it.
+
+### Deprecated
+
+!!! Danger "Warning: Legacy Variable"
+
+    `LANDING_PAGE_ABOUT` was available in Elegant V2.5.0. It has since been passed out in favour of `landing-page-about-hidden`. The new method lets you write "About Me" in your favourite markup language.
+
+You can write up your own About me section using `LANDING_PAGE_ABOUT` variable
+in your configuration. It is a dictionary that has two keys `title` and
+`details`.
+
+Value of `title` is displayed in the header of the home page, like
+in the above example it is "I design and build software products for iOS and
+OSX".
+
+`details` is the text that appears under "About me" heading. You can add raw HTML to it.
+
+## Projects
+
+Projects list is read from `PROJECTS`. It is an array of dictionaries. Each
+dictionary has three keys,
+
+1. `name` which will have name of your project,
+1. `url` which will have URL of the project, and
+1. `description` which will have the description of the project.
+
+You can define as many projects as you want. Here
+is an example,
+
+    #!Python
+    PROJECTS = [{
+        'name': 'Logpad + Duration',
+        'url': 'https://github.com/talha131/logpad-plus-duration#logpad--duration',
+        'description': 'Vim plugin to emulate Windows Notepad logging feature,'
+        ' and log duration of each entry'},
+        {'name': 'Elegant Theme for Pelican',
+        'url': 'http://oncrashreboot.com/pelican-elegant',
+        'description': 'A clean and distraction free theme, with search and a'
+        ' lot more unique features, using Jinja2 and Bootstrap'}]
+
+To configure the projects' list title, set `PROJECTS_TITLE` variable in your Pelican configuration. Its default value is "My Projects". For example,
+
+```python
+PROJECTS_TITLE = "Related Projects"
+```
+
+### Recent Articles
+
+Recent articles show last `RECENT_ARTICLES_COUNT` whose default value is 10. It
+also has a link to "all posts".

documentation/content/Code Snippets/code-style.md

@@ -0,0 +1,19 @@
+---
+Title: Code Snippets Theme
+Tags: markdown, reST, code-snippets, gist
+layout: post
+Date: 2013-08-27 23:20
+comments: false
+Slug: code-snippets-theme
+Category: Code Snippets
+---
+
+Elegant uses [Solarized](http://ethanschoonover.com/solarized) theme for syntax
+highlighting. Line numbers have a different background color so that they
+appear distinct from the code. Here is an example
+
+    #!c
+    int sample_function (void) {
+        printf ("This is a sample function");
+        return 0
+    }

documentation/content/Appearance and Style/line-numbers-code-snippet.md → documentation/content/Code Snippets/line-numbers-code-snippet.md

@@ -1,9 +1,8 @@
-Title: How to display Line Numbers in Code Snippets
+Title: Display Line Numbers in Code Snippets
 Tags: markdown, reST, code-snippets, gist
-Category: Appearance & Style
+Category: Code Snippets
 Date: 2013-11-05 17:36
-Slug: how-to-display-line-numbers-in-code-snippets
-Disqus_identifier: wmo972t-how-to-display-line-numbers-in-code-snippets
+Slug: display-line-numbers-in-code-snippets
 Subtitle:
 Summary: reStructuredText and Markdown have directives that generate line numbers for code blocks. Use them to display line numbers in code snippets.
 Keywords: codehilite, python-markdown

documentation/content/Comments/collapsible-comments.md

@@ -0,0 +1,33 @@
+---
+Title: Collapsible Comments
+Tags: interaction
+layout: post
+Date: 2013-08-27 23:20
+comments: false
+Slug: collapsible-comments
+Category: Commenting
+---
+
+Readers use scroll bar to track their progress when reading inside their
+browsers. Very often comments take up more space than the actual article. When
+comments take up more space, it throws the scroll bar proportion off and reader
+cannot judge his progress correctly. Hacker News hosted [a
+discussion](https://news.ycombinator.com/item?id=6246777) on this topic.
+
+> tons of online articles list comments on the same page, so the scroll bar is
+> almost a negative incentive to keep reading. "I've read this much of the
+> article and I'm only 1/20th of the way down?"
+> [user stops reading, unaware that there's 450 comments and the article is actually pretty short]
+
+Elegant keeps the comments section hidden by default. Reader can hide and
+unhide the section by clicking on the comments section.
+
+This is how comments section appear
+
+![Collapsed comments
+section]({static}/images/elegant-theme_comments-section-collapsed.png)
+
+It expands when reader clicks on it
+
+![Uncollapsed comments
+section]({static}/images/elegant-theme_comments-section-uncollapsed.png)

documentation/content/Comments/comment-id.md

@@ -0,0 +1,27 @@
+---
+Title: Comments Thread ID
+Tags: interaction
+layout: post
+date: 2019-06-30 22:29
+comments: false
+Slug: comments-thread-id
+Category: Commenting
+---
+
+Most Pelican themes pass article URL to Disqus as the [Disqus
+identifier](http://help.disqus.com/customer/portal/articles/472098-javascript-configuration-variables#disqus_identifier).
+
+This puts you at a disadvantage. If you are forced to change URL of an article
+you will lose Disqus discussion for that article because Disqus identifier for
+the article will change too.
+
+Elegant offers you `comment_id` property that you can set in your
+article metadata. Set it to any unique string you want. It won't be effected by
+the article URL.
+
+If you choose not to use `comment_id`, Elegant passes article URL to
+Disqus.
+
+## Legacy Variable
+
+In previous versions, we had `disqus_identifier`. Though Elegant is backward compatible but we recommend you to change it to `comment_id`.

documentation/content/Comments/disable-comments.md

@@ -0,0 +1,22 @@
+---
+Title: Disable Comments
+Tags: interaction
+layout: post
+date: 2019-01-12 16:29
+comments: false
+Slug: disable-comments-per-article
+Category: Commenting
+---
+
+If you remove your comment service configuration, say you set `DISQUS_SITENAME` to empty string, then comments will disappear from all the articles.
+
+Sometimes you want to disable comments on selected articles. In which case, you can set `comments` variable in the article metadata to `false`.
+
+Here is an example,
+
+```yaml
+Title: Disable Comments
+date: 2019-01-12 16:29
+comments: false
+Category: Commenting
+```

documentation/content/Comments/disqus-comments.md

@@ -0,0 +1,13 @@
+Title: Enable Disqus Comments
+Tags: interaction
+Category: Commenting
+Date: 2014-04-21 16:39
+Slug: enable-disqus-comments
+comment_id: 9jgwmy8-how-to-use-disqus-comments-elegantly
+Subtitle:
+Summary: Elegant offers Disqus comments out of the box with few unique features
+
+You can use Disqus for comments. You have to set `DISQUS_SITENAME` to Disqus
+site name identifier in configuration to enable comments.
+
+That's it. Elegant will take care of the rest.