🦄 Update setup instructions

README.md

@@ -1,31 +1,46 @@
 # pelican-alchemy
 
-Alchemy ✨ is a functional, clean, responsive theme for the [Pelican](http://getpelican.com) static site generator. It is heavily inspired by [crowsfoot](http://github.com/porterjamesj/crowsfoot) and [clean-blog](https://github.com/BlackrockDigital/startbootstrap-clean-blog), and is powered by [Bootstrap](https://github.com/twbs/bootstrap) (v3.x).
+Alchemy ✨ is a functional, clean, responsive theme for the [Pelican](http://getpelican.com) static site generator. It is heavily inspired by [crowsfoot](http://github.com/porterjamesj/crowsfoot), [clean-blog](https://github.com/BlackrockDigital/startbootstrap-clean-blog), and powered by [Bootstrap](https://github.com/twbs/bootstrap).
 
 [Demo](https://rwanyoike.github.io/pelican-alchemy/)!
 
+Pull requests are welcome!
+
 ## Screenshot
 
 ![Screenshot](screenshot.jpg "Screenshot")
 
+## Features
+
+- Bootstap 4 (currently v4.0.0-alpha.5)
+- Core Pygments [styles](http://pygments.org/demo/)
+- External analytics (Google Analytics, Gauges, Piwik)
+- External comments (Disqus)
+- Font Awesome font icons
+- No external dependencies
+- No JavaScript (excl. Analytics & Comments)
+- Pelican `sitemap.xml` support
+- realfavicongenerator [package](http://realfavicongenerator.net/blog/new-favicon-package-less-is-more/) support
+- Simple Jinja2 templates
+
 ## Installation
 
-First, clone the repo onto your device:
+First, clone the repo:
 
     $ git clone git@github.com:rwanyoike/pelican-alchemy.git
 
-Point the `THEME` variable in your pelican config to the `alchemy` folder:
+Then point the `THEME` variable in your Pelican config to the `alchemy` folder:
 
     THEME = '/path/to/pelican-alchemy/alchemy'
 
-### Alternative
+### As a Submodule
 
-Setup `pelican-alchemy` as a submodule:
+In your Pelican site:
 
     $ mkdir themes
-    $ git submodule add git@github.com:rwanyoike/pelican-alchemy.git themes/pelican-alchemy
+    $ git submodule add https://github.com/rwanyoike/pelican-alchemy themes/pelican-alchemy
 
-And in pelican config:
+And Pelican config:
 
     THEME = 'themes/pelican-alchemy/alchemy'
 
@@ -35,12 +50,12 @@ Visit the [settings page](https://rwanyoike.github.io/pelican-alchemy/pages/sett
 
 - **SITESUBTITLE**: Subtitle that appears in the header.
 - **SITEIMAGE**: Image that appears in the header.
-- **DESCRIPTION**: Index page HTML head meta description tag.
+- **DESCRIPTION**: Index HTML head `<meta>` description.
 - **LINKS**: A list of tuples (Title, URL) for menu links.
 - **ICONS**: A list of tuples (Icon, URL) for icon links.
 - **PYGMENTS_STYLE**: Built-in Pygments style for syntax highlighting.
-- **HIDE_AUTHORS**: Hide the author(s) of an article.
-- **NEW_FAVICONS**: Use a [realfavicongenerator](https://realfavicongenerator.net/blog/new-favicon-package-less-is-more/) favicon package.
+- **HIDE_AUTHORS**: Hide the author(s) of an article - useful for single author sites.
+- **RFG_FAVICONS**: Use a [realfavicongenerator](https://realfavicongenerator.net/blog/new-favicon-package-less-is-more/) package.
 
 Others:
 
@@ -50,6 +65,65 @@ Others:
 - **PIWIK_URL**
 - **PIWIK_SITE_ID**
 
----
+Example Pelican [config](https://github.com/rwanyoike/pelican-alchemy/blob/demo/pelicanconf.py) (demo site).
 
-Pull requests are welcome! ☺️
+## Tips
+
+### Bootstrap Classes
+
+To have Bootstrap classes set for rendered html (`.table`, `.img-fluid` etc), use the [Bootstrapify](https://github.com/ingwinlu/pelican-bootstrapify) plugin.
+
+In your Pelican site:
+
+    $ mkdir plugins
+    $ git submodule add https://github.com/ingwinlu/pelican-bootstrapify plugins/pelican-bootstrapify
+
+And Pelican config:
+
+    # http://docs.getpelican.com/en/stable/plugins.html#how-to-use-plugins
+    PLUGIN_PATHS = ['plugins']
+    PLUGINS = ['pelican-bootstrapify']
+
+    BOOTSTRAPIFY = {
+        'table': ['table', 'table-striped', 'table-hover'],
+        'img': ['img-fluid'],
+        'blockquote': ['blockquote'],
+    }
+
+Use `BOOTSTRAPIFY` to pass a `{'css-selector': ['list-of-classes']}` dict to the plugin. Bootstrapify will append `list-of-classes` to all tags that match `css-selector`.
+
+### RFG_FAVICONS
+
+To use the `RFG_FAVICONS` setting, visit [realfavicongenerator.net](https://realfavicongenerator.net/) to generate a site favicon package and download it.
+
+In your Pelican site:
+
+    $ mkdir content/extras
+    $ unzip /path/to/favicons.zip -d content/extras
+
+And Pelican config:
+
+    # https://github.com/getpelican/pelican/wiki/Tips-n-Tricks#second-solution-using-static_paths
+    STATIC_PATHS = ['extras', 'images']
+    EXTRA_PATH_METADATA = {
+        'extras/android-chrome-192x192.png': {'path': 'android-chrome-192x192.png'},
+        'extras/apple-touch-icon.png': {'path': 'apple-touch-icon.png'},
+        'extras/browserconfig.xml': {'path': 'browserconfig.xml'},
+        ...
+    }
+
+    RFG_FAVICONS = True
+
+Note: `EXTRA_PATH_METADATA` should correspond with the favicon package:
+
+    $ unzip -l /path/to/favicons.zip
+
+### Generate `sitemap.xml`
+
+There is a `sitemap.html` Jinja2 template that can be used to [generate a sitemap](https://github.com/getpelican/pelican/wiki/Tips-n-Tricks#generate-sitemapxml).
+
+In your Pelican config:
+
+    # Default value is ['index', 'tags', 'categories', 'authors', 'archives']
+    DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'sitemap']
+    SITEMAP_SAVE_AS = 'sitemap.xml'

alchemy/static/css/style.css

@@ -4,6 +4,10 @@
   text-shadow: none;
 }
 
+body {
+  background-color: #f5f5f5;
+}
+
 a {
   color: #333;
 }
@@ -30,7 +34,6 @@ hr {
 
 .header,
 .footer {
-  background-color: #f5f5f5;
   padding: 1.5rem 0 .5rem;
 }
 
@@ -59,6 +62,7 @@ hr {
 }
 
 .main {
+  background-color: #fff;
   padding: 1.5rem 0;
 }
 
@@ -101,11 +105,6 @@ hr {
   text-decoration: underline
 }
 
-/* Pad article content */
-.article .content p {
-  margin: 1.5rem 0;
-}
-
 @media (min-width: 576px) {
   .header .title {
     font-size: 3rem;

alchemy/templates/base.html

@@ -35,7 +35,7 @@
   <link rel="alternate" type="application/rss+xml" href="{{ FEED_DOMAIN }}/{{ TAG_FEED_RSS|format(tag.slug) }}" title="Tags RSS Feed">
   {% endif %}
 
-  {% if NEW_FAVICONS %}
+  {% if RFG_FAVICONS %}
   <link rel="apple-touch-icon" href="{{ SITEURL }}/apple-touch-icon.png" sizes="180x180">
   <link rel="icon" type="image/png" href="{{ SITEURL }}/favicon-32x32.png" sizes="32x32">
   <link rel="icon" type="image/png" href="{{ SITEURL }}/favicon-16x16.png" sizes="16x16">