2017-04-08 22:16:33 +02:00
# Pelican Alchemy
2013-11-25 05:59:15 +01:00
2017-11-21 13:36:48 +01:00
> A magical ✨ Pelican theme
Alchemy is a functional, clean, responsive theme for the [Pelican ](http://getpelican.com ) static site generator.
2016-11-08 06:24:42 +01:00
2017-04-08 21:16:19 +02:00
Inspired by [crowsfoot ](http://github.com/porterjamesj/crowsfoot ) and [clean-blog ](https://github.com/BlackrockDigital/startbootstrap-clean-blog ), it features:
2016-11-08 06:24:42 +01:00
2019-10-18 16:13:28 +02:00
- Powered by [Bootstrap 4 ](https://getbootstrap.com/ ) (v4.3.1)
- Supports any [Boostwatch ](https://bootswatch.com/ ) themes
2017-03-07 10:09:00 +01:00
- [Font Awesome ](http://fontawesome.io/ ) icons
- [Pygments ](http://pygments.org/ ) syntax highlighting styles
2017-11-21 13:36:48 +01:00
- 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 **
2016-12-01 11:22:37 +01:00
2017-11-21 13:36:48 +01:00
** Features link to external assets (webfonts etc).
2019-10-18 15:22:49 +02:00
## Screenshots
< table >
< tr >
< td colspan = "2" >
< a href = "screenshots/default.png" >
< img src = "screenshots/default.png" / >
< p align = "center" > Default colors< / p >
< / a >
< / td >
< / tr >
< tr >
< td >
< a href = "screenshots/oldstyle.png" >
< img src = "screenshots/oldstyle.png" / >
< p align = "center" > Old style (see below)< / p >
< / a >
< / td >
< td >
< a href = "screenshots/sketchy.png" >
< img src = "screenshots/sketchy.png" / >
< p align = "center" > Sketchy (Boostwatch)< / p >
< / a >
< / td >
< / tr >
< tr >
< td >
< a href = "screenshots/solar.png" >
< img src = "screenshots/solar.png" / >
< p align = "center" > Solar (Boostwatch)< / p >
< / a >
< / td >
< td >
< a href = "screenshots/united.png" >
< img src = "screenshots/united.png" / >
< p align = "center" > United (Boostwatch)< / p >
< / a >
< / td >
< / tr >
< / table >
> To enable old visual style add `THEME_CSS_OVERRIDES = ['theme/css/oldstyle.css']`
> to your `pelicanconf.py` and use no Boostwatch themes.
> See [stylesheet](alchemy/static/css/oldstyle.css) for more information.
2017-04-08 21:16:19 +02:00
2016-11-29 14:18:03 +01:00
## Installation
2016-11-29 13:05:39 +01:00
2019-09-27 10:03:16 +02:00
### From Git repo
2017-03-07 10:09:00 +01:00
Clone the repo:
2016-11-29 13:05:39 +01:00
2017-11-21 13:36:48 +01:00
```bash
git clone https://github.com/nairobilug/pelican-alchemy
2017-04-08 21:16:19 +02:00
```
2016-11-29 13:05:39 +01:00
2017-03-07 10:09:00 +01:00
Set the `THEME` variable in your Pelican config:
2016-11-29 13:05:39 +01:00
2017-04-08 21:16:19 +02:00
```python
2017-11-21 13:36:48 +01:00
THEME = '< PATH_TO_REPO > /alchemy'
2017-04-08 21:16:19 +02:00
```
2016-11-29 13:05:39 +01:00
2017-04-08 21:16:19 +02:00
### As a Submodule
2016-11-29 13:05:39 +01:00
2016-12-01 11:22:37 +01:00
In your Pelican site:
2016-11-29 13:05:39 +01:00
2017-11-21 13:36:48 +01:00
```bash
mkdir themes
git submodule add https://github.com/nairobilug/pelican-alchemy themes/pelican-alchemy
2017-04-08 21:16:19 +02:00
```
2016-11-29 13:05:39 +01:00
2017-04-08 21:16:19 +02:00
And in Pelican config:
2016-11-29 13:05:39 +01:00
2017-04-08 21:16:19 +02:00
```python
THEME = 'themes/pelican-alchemy/alchemy'
```
2016-11-29 13:05:39 +01:00
2019-09-27 10:03:16 +02:00
### With pip
Alternatively, you can install this theme with pip:
```bash
pip install "https://github.com/nairobilug/pelican-alchemy/tarball/master"
```
And import it from Pelican config:
```python
import alchemy
THEME = alchemy.path()
```
2017-04-08 21:16:19 +02:00
## Usage
2016-11-29 13:05:39 +01:00
2019-12-03 14:23:17 +01:00
Visit the [Settings docs ](docs/settings.md ) for examples:
2016-11-29 13:05:39 +01:00
2016-11-29 14:18:03 +01:00
- **SITESUBTITLE**: Subtitle that appears in the header.
- **SITEIMAGE**: Image that appears in the header.
2016-12-01 11:22:37 +01:00
- **DESCRIPTION**: Index HTML head `<meta>` description.
2016-11-29 14:18:03 +01:00
- **LINKS**: A list of tuples (Title, URL) for menu links.
- **ICONS**: A list of tuples (Icon, URL) for icon links.
2019-10-22 13:07:21 +02:00
- **FOOTER_LINKS**: A list of tuples (Title, URL) for footer links. Replaces
default set of links (Authors, Archives, Categories, Tags).
2019-09-18 15:40:49 +02:00
- **BOOTSTRAP_CSS**: URL of Bootstrap CSS file. Use this to enable Boostwatch themes.
2016-11-29 14:18:03 +01:00
- **PYGMENTS_STYLE**: Built-in Pygments style for syntax highlighting.
2016-12-01 11:22:37 +01:00
- **HIDE_AUTHORS**: Hide the author(s) of an article - useful for single author sites.
2017-03-07 10:09:00 +01:00
- **RFG_FAVICONS**: Use a Favicon Generator package.
2019-09-19 13:24:09 +02:00
- **THEME_CSS_OVERRIDES**: Sequence of stylesheet URLs to override CSS provided by theme.
Both relative and absolute URLs are supported.
2019-10-18 17:08:37 +02:00
- **THEME_JS_OVERRIDES**: Sequence of JavaScript URLs to enable with this
theme. Alchemy uses no JS by default. Both relative and absolute URLs are
supported.
2016-11-29 13:05:39 +01:00
2017-03-07 10:09:00 +01:00
Misc settings:
2016-11-29 13:05:39 +01:00
2016-11-29 14:18:03 +01:00
- **DISQUS_SITENAME**
- **GAUGES**
- **GOOGLE_ANALYTICS**
- **PIWIK_URL**
- **PIWIK_SITE_ID**
2016-11-29 13:05:39 +01:00
2017-03-07 10:09:00 +01:00
Example [pelicanconf.py ](https://github.com/nairobilug/pelican-alchemy/blob/demo/pelicanconf.py ) (demo website).
2016-12-01 11:22:37 +01:00
2017-04-08 21:16:19 +02:00
### Tips & Tricks
2014-05-28 23:54:52 +02:00
2019-12-03 14:23:17 +01:00
[See documentation page ](docs/pelican-tips.md )
2017-04-08 21:16:19 +02:00
2017-11-21 13:36:48 +01:00
## How to Contribute
2017-04-08 21:16:19 +02:00
2017-11-21 13:36:48 +01:00
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. Send a pull request and bug the maintainer until it gets merged and published. :)
2017-04-08 21:16:19 +02:00
2017-11-21 13:36:48 +01:00
Alchemy follows the [Contributor Covenant ](CODE_OF_CONDUCT.md ) code of conduct.
2017-04-08 21:16:19 +02:00
## License
2017-11-21 13:25:36 +01:00
[MIT ](LICENSE ) © 2017 Nairobi GNU/Linux Users Group