Commit 2b12b9b1 authored by Lee Kimber's avatar Lee Kimber
Browse files

Doc: Rationalised the documentation layout; improved README.md

parent a482a9af
......@@ -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.
......
Welcome to the pelican-alchemy documentation!
- [Pelican Tips](pelican-tips.md)
- [Settings](settings.md)
- [Adding comments to Pelican blog](comments.md)
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment