Doc: Rationalised the documentation layout; improved README.md

README.md

@@ -7,17 +7,22 @@ Alchemy is a functional, clean, responsive theme for the [Pelican](http://getpel
 Inspired by [crowsfoot](http://github.com/porterjamesj/crowsfoot) and [clean-blog](https://github.com/BlackrockDigital/startbootstrap-clean-blog), it features:
 
 - Powered by [Bootstrap 4](https://getbootstrap.com/) (v4.3.1)
-- Supports any [Boostwatch](https://bootswatch.com/) themes
+- Styled by CSS, not Javascript
+- Supports any [Boostwatch](https://bootswatch.com/) themes if you want it to
 - [Font Awesome](http://fontawesome.io/) icons
 - [Pygments](http://pygments.org/) syntax highlighting styles
 - Pelican `sitemap.xml` support
 - [Favicon Generator](http://realfavicongenerator.net/) support
-- External analytics ([Google](https://analytics.google.com), [Gauges](https://gaug.es), [Piwik](https://piwik.org)) support **
-- External comments ([Disqus](https://disqus.com)) support **
 
-** Features link to external assets (webfonts etc).
 
-## Screenshots
+## Examples
+
+### Live site
+
+[Adapted as a Progressive Web Application](https://test.12voltfarm.com/)
+
+
+### Screenshots
 
 <table>
 <tr>
@@ -64,7 +69,11 @@ Inspired by [crowsfoot](http://github.com/porterjamesj/crowsfoot) and [clean-blo
 
 ## Installation
 
-### From Git repo
+Like all pelican themes, there are four ways of calling it:
+
+### 1. From Git repo
+
+In my opinion, this is the best long-term method to use.
 
 Clone the repo:
 
@@ -72,13 +81,13 @@ Clone the repo:
 git clone https://github.com/nairobilug/pelican-alchemy
 ```
 
-Set the `THEME` variable in your Pelican config:
+Set the `THEME` variable in your Pelican config file: pelicanconf.py:
 
 ```python
 THEME = '<PATH_TO_REPO>/alchemy'
 ```
 
-### As a Submodule
+### 2. As a Submodule
 
 In your Pelican site:
 
@@ -93,7 +102,7 @@ And in Pelican config:
 THEME = 'themes/pelican-alchemy/alchemy'
 ```
 
-### With pip
+### 3. With pip
 
 Alternatively, you can install this theme with pip:
 
@@ -101,7 +110,7 @@ Alternatively, you can install this theme with pip:
 pip install "https://github.com/nairobilug/pelican-alchemy/tarball/master"
 ```
 
-And import it from Pelican config:
+And import it from Pelican config file: pelicanconf.py:
 
 ```python
 import alchemy
@@ -110,6 +119,10 @@ THEME = alchemy.path()
 
 ## Usage
 
+1. [Settings docs](docs/settings.md)
+2. [Pelican-Alchemy Tips](docs/pelican-tips.md)
+3. [Adding comments to Pelican blog](docs/comments.md)
+
 Visit the [Settings docs](docs/settings.md) for examples:
 
 - **SITESUBTITLE**: Subtitle that appears in the header.
@@ -134,7 +147,7 @@ Visit the [Settings docs](docs/settings.md) for examples:
   theme. Alchemy uses no JS by default. Both relative and absolute URLs are
   supported.
 
-[CSS class]: https://fontawesome.com/how-to-use/on-the-web/referencing-icons/basic-use
+[CSS class]: [https://fontawesome.com/how-to-use/on-the-web/referencing-icons/basic-use](https://fontawesome.com/how-to-use/on-the-web/referencing-icons/basic-use)
 
 Misc settings:
 
@@ -144,16 +157,19 @@ Misc settings:
 - **PIWIK_URL**
 - **PIWIK_SITE_ID**
 
-Example [pelicanconf.py](https://github.com/nairobilug/pelican-alchemy/blob/demo/pelicanconf.py) (demo website).
 
 ### Tips & Tricks
 
-[See documentation page](docs/pelican-tips.md)
+[Pelican-Alchemy Tips](docs/pelican-tips.md)
+
+### Adding comments
+
+[Adding comments to Pelican blog](docs/comments.md)
 
 ## How to Contribute
 
 1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
-1. Fork [the repository](https://github.com/nairobilug/pelican-alchemy) on GitHub to start making your changes to the master branch (or branch off of it).
+1. Fork [the repository](https://github.com/leekimber/pelican-alchemy) on GitHub to start making your changes to the master branch (or branch off of it).
 1. Send a pull request and bug the maintainer until it gets merged and published. :)
 
 Alchemy follows the [Contributor Covenant](CODE_OF_CONDUCT.md) code of conduct.

docs/README.md

-Welcome to the pelican-alchemy documentation!
-
-- [Pelican Tips](pelican-tips.md)
-- [Settings](settings.md)
-- [Adding comments to Pelican blog](comments.md)