Merge pull request #84 from sio/docs

Merge GitHub wiki contents into main repo

README.md

@@ -110,7 +110,7 @@ THEME = alchemy.path()
 
 ## Usage
 
-Visit the [Settings wiki](https://github.com/nairobilug/pelican-alchemy/wiki/Settings) for examples:
+Visit the [Settings docs](docs/settings.md) for examples:
 
 - **SITESUBTITLE**: Subtitle that appears in the header.
 - **SITEIMAGE**: Image that appears in the header.
@@ -141,7 +141,7 @@ Example [pelicanconf.py](https://github.com/nairobilug/pelican-alchemy/blob/demo
 
 ### Tips & Tricks
 
-https://github.com/nairobilug/pelican-alchemy/wiki/Tips
+[See documentation page](docs/pelican-tips.md)
 
 ## How to Contribute
 

docs/README.md

@@ -0,0 +1,4 @@
+Welcome to the pelican-alchemy documentation!
+
+- [Pelican Tips](pelican-tips.md)
+- [Settings](settings.md)

docs/pelican-tips.md

@@ -0,0 +1,72 @@
+# Pelican Tips
+
+## Bootstrap Classes
+
+To have Bootstrap classes set for rendered html (`.table`, `.img-fluid` etc), use the [Bootstrapify](https://github.com/ingwinlu/pelican-bootstrapify) Pelican plugin.
+
+In your Pelican site:
+
+```bash
+mkdir plugins
+git submodule add https://github.com/ingwinlu/pelican-bootstrapify plugins/pelican-bootstrapify
+```
+
+And in Pelican config:
+
+```python
+# 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`.
+
+## Favicons
+
+To use the `RFG_FAVICONS` setting, visit [Favicon Generator](http://realfavicongenerator.net/) to generate a favicon package and download it.
+
+In your Pelican site:
+
+```
+mkdir content/extras
+unzip <PATH_TO_PACKAGE>.zip -d content/extras
+```
+
+And in Pelican config:
+
+```python
+# 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
+```
+
+`EXTRA_PATH_METADATA` should correspond with the favicon package:
+
+```bash
+unzip -l <PATH_TO_PACKAGE>.zip
+```
+
+## Use `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:
+
+```python
+# Default value is ['index', 'tags', 'categories', 'authors', 'archives']
+DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives', 'sitemap']
+SITEMAP_SAVE_AS = 'sitemap.xml'
+```

docs/settings.md

@@ -0,0 +1,125 @@
+# Settings
+
+Unless otherwise specified, settings that refer to paths can be either absolute or relative to the configuration file.
+
+## SITESUBTITLE
+
+Subtitle that appears in the header:
+
+```python
+SITESUBTITLE = 'A magical \u2728 Pelican theme'
+```
+
+## SITEIMAGE
+
+Image that appears in the header:
+
+```python
+SITEIMAGE = '/images/profile.png'
+```
+
+You can also force the image size:
+
+```python
+SITEIMAGE = '/images/profile.svg width=200 height=200'
+```
+
+## DESCRIPTION
+
+Index HTML head `<meta>` description:
+
+```python
+DESCRIPTION = 'A functional, clean, responsive theme for Pelican. Heavily ' \
+              'inspired by crowsfoot and clean-blog, powered by Bootstrap.'
+```
+
+## LINKS
+
+A list of tuples (Title, URL) for menu links:
+
+```python
+LINKS = (
+    ('Pelican', 'http://getpelican.com/'),
+    ('Python.org', 'http://python.org/'),
+    ('Jinja2', 'http://jinja.pocoo.org/'),
+)
+```
+
+## ICONS
+
+A list of tuples (Icon, URL) for icon links:
+
+```python
+ICONS = (
+    ('github', 'https://github.com/nairobilug/pelican-alchemy'),
+)
+```
+
+Icon in (Icon, URL) is a Font Awesome [icon](http://fontawesome.io/icons/) without the `fa-` prefix.
+
+## PYGMENTS_STYLE
+
+You can choose one of the built-in Pygments styles for syntax highlighting.
+
+By default the `default` style is used:
+
+```python
+PYGMENTS_STYLE = 'default'
+```
+
+The following styles are available:
+
+- algol
+- algol_nu
+- autumn
+- borland
+- bw
+- colorful
+- default
+- emacs
+- friendly
+- fruity
+- igor
+- lovelace
+- manni
+- monokai
+- murphy
+- native
+- paraiso-dark
+- paraiso-light
+- pastie
+- perldoc
+- rrt
+- tango
+- trac
+- vim
+- vs
+- xcode
+
+For a demo of the different styles, see [link](http://pygments.org/demo/).
+
+## HIDE_AUTHORS
+
+Hide the author(s) of an article - useful for single author sites:
+
+```python
+HIDE_AUTHORS = True
+```
+
+## NEW_FAVICONS
+
+Use a [realfavicongenerator](https://realfavicongenerator.net/blog/new-favicon-package-less-is-more/) favicon package:
+
+```python
+RFG_FAVICONS = True
+```
+
+---
+
+```python
+DISQUS_SITENAME = '...'
+GAUGES = '...'
+GOOGLE_ANALYTICS = '...'
+PIWIK_URL = '...'
+PIWIK_SITE_ID = '...'
+```