# Pelidoc Theme

Adapted from [Pelican Bootstrap3](https://github.com/getpelican/pelican-themes/tree/master/pelican-bootstrap3), originally developed by
[DandyDev](https://github.com/DandyDev). It's fully responsive and contains
sub-themes from the Bootswatch project. Pelican-bootstrap3 is compatible with
Pelican 3.3.0 and higher.

We removed many parts of Pelican Bootstrap3, including the i18n support, and this theme has only been tested within the Pelidoc project.

## README content from Pelican Bootstrap3

We might have broken some of the functionality described below in our efforts to reduce complexity for Pelidoc.

## Usage

This theme honors the following standard Pelican settings:

* Putting feeds in the `<head>` section:
	* `FEED_ALL_ATOM`
	* `FEED_ALL_RSS`
* Template settings:
	* `DISPLAY_PAGES_ON_MENU`
	* `DISPLAY_CATEGORIES_ON_MENU`
	* `MENUITEMS`
	* `LINKS` (Blogroll will be put in the sidebar instead of the head)
* Analytics & Comments
	* `GOOGLE_ANALYTICS` (classic tracking code)
	* `GOOGLE_ANALYTICS_UNIVERSAL` and `GOOGLE_ANALYTICS_UNIVERSAL_PROPERTY` (Universal tracking code)
	* `PIWIK_URL`, `PIWIK_SSL_URL` and `PIWIK_SITE_ID`

It uses the `tag_cloud` variable for displaying tags in the sidebar. You can
control the amount of tags shown with: `TAG_CLOUD_MAX_ITEMS`

## Extras

### Bootswatch and other Bootstrap 3 themes

Part of the versatility of this theme comes from the fact that I included all
the lovely Bootstrap 3 themes from [Bootswatch](http://bootswatch.com/), built
by [Thomas Park](https://github.com/thomaspark). You can tell Pelican what
Bootswatch theme to use, by setting `BOOTSTRAP_THEME` to the desired theme, in
lowercase (ie. 'readable' or 'cosmo' etc.). My own site is using _Simplex_. If
you want to use any other Bootstrap 3 compatible theme, just put the minified
CSS in the `static/css` directory and rename it using the following naming
scheme: `bootstrap.{theme-name}.min.css`. Then update the `BOOTSTRAP_THEME`
variable with the _theme-name_ used.

### Article info

Set `SHOW_ARTICLE_AUTHOR` to True to show the author of the article at the top
of the article and in the index of articles. Set `SHOW_ARTICLE_CATEGORY` to
show the Category of each article. Set `SHOW_DATE_MODIFIED` to True to show the
article modified date next to the published date.

### Custom CSS/JS

If you want to add custom css/js to the theme, without having to clone and
maintain your own version of the theme, you can use `CUSTOM_CSS` and `CUSTOM_JS` variables.
The value is the location where you tell Pelican to put the file (see below):

```
CUSTOM_CSS = 'static/css/custom.css'
CUSTOM_JS = 'static/js/custom.js'
```

To tell Pelican to copy the relevant file to the desired destination, add the
path to `STATIC_PATHS` and the destination to `EXTRA_PATH_METADATA`, like so:

```
# Tell Pelican to add files from 'extra' to the output dir
STATIC_PATHS = [
  'images',
  'extra'
]

# Tell Pelican to change the path to 'static/custom.css' in the output dir
EXTRA_PATH_METADATA = {
    'extra/custom.css': {'path': 'static/css/custom.css'},
    'extra/custom.js': {'path': 'static/js/custom.js'}
}
```

### Pygments

You can choose the syntax highlighting style by using the `PYGMENTS_STYLE`
variable to specify one of the built-in Pygments styles. By default the
`native` style is used. The following styles are avaiable:

- autumn
- borland
- bw
- colorful
- default
- emacs
- friendly
- fruity
- manni
- monokai
- murphy
- native
- pastie
- perldoc
- solarizeddark
- solarizedlight
- tango
- trac
- vim
- vs
- zenburn

For a demo of the different Pygment styles, have a look [here](http://pygments.org/demo/218030/)

### Pagination

Pelican-Bootstrap3 follows the standard Pagination settings of Pelican and uses
the Bootstrap3 [Pagination
component](http://getbootstrap.com/components/#pagination), but you can
optionally use the Boostrap3 _Pager_ by setting `USE_PAGER` to `True`.

### Bootstrap fluid layout

If you'd like to use the fluid container layout from Bootstrap, set the flag
`BOOTSTRAP_FLUID` to _True_.

### Site Brand

You can provide a logo for your site using `SITELOGO`. For example: `SITELOGO =
'images/my_site_logo.png'`. You can then define the size of the logo using
`SITELOGO_SIZE`. The `width` of the `<img>` element will be set accordingly.

By default the `SITENAME` will be shown as well. It's also possible to hide the site name using the `HIDE_SITENAME` flag.

### Breadcrumbs

It's possible to show breadcrumbs in your site using the `DISPLAY_BREADCRUMBS`
flag. By default the article category isn't shown in the breadcrumbs, if you
wish to enable it, set the `DISPLAY_CATEGORY_IN_BREADCRUMBS` flag to _True_.

### Navbar

If you wish to use the inverse navbar from Bootstrap, set the flag `BOOTSTRAP_NAVBAR_INVERSE` to _True_.

### Related Posts

This theme has support for the [Related Posts
plugin](https://github.com/getpelican/pelican-plugins/tree/master/related_posts).
All you have to do, is enable the plugin, and the theme will do the rest.

### Series

This theme supports the [Series
plugin](https://github.com/getpelican/pelican-plugins/tree/master/series). If
you enable the plugin you will find in the footer the links to the previous and
next articles in the series.

You may customize the header of this list setting the `SERIES_TEXT` variable,
which can also include the `index` and `name` variables. The first is the index
of the current article in the series (starting from 1) and the second is the
name of the series. The default string is `Part %(index)s of the %(name)s
series`.

You may display on the sidebar the link to the previous and next article in the
series setting `DISPLAY_SERIES_ON_SIDEBAR` to `True`.

You may display information on the series just under the article title setting
`SHOW_SERIES` to `True`.

### IPython Notebook support

This theme supports including IPython notebooks through the [Liquid Tags
plugin](https://github.com/getpelican/pelican-plugins/tree/master/liquid_tags).
If you enable the plugin, the theme will automatically include the right CSS/JS
to make the notebooks work.

### Favicon

Set the `FAVICON` option in your `pelicanconf.py`. For example: `FAVICON =
'images/favicon.png'`

### Index page

* If `DISPLAY_ARTICLE_INFO_ON_INDEX` is set to _True_, article info (date,
  tags) will be show under the title for each article, otherwise only title and
  summary will be shown (default).

### Short menu labels for pages

By default, the title of a page is used both for showing the title as
part of a page's content, and, if pages in menu is enabled, as the
label of the corresponding menu item. You can choose a different label
for the menu (such as a short single word) than the page title by adding a
Menulabel metadata attribute to the page header (`Menulabel:` in
markdown, `:Menulabel:` in rst).

### Banner Image

A banner image can be added to the theme, displayed with the SITENAME and an optional subtitle. Config options are as follows:

* Set the banner image with `BANNER = '/path/to/banner.png'`
* Set the subtitle text with `BANNER_SUBTITLE = 'This is my subtitle'`
* By default, the banner is only shown on the index page. To display the banner on all pages, set `BANNER_ALL_PAGES = True`

### Sidebar options

The following things can be displayed on the sidebar:

* **Social links** can be provided through the `SOCIAL` variable. If it's empty, the section will not be shown
	* In your `pelicanconf.py` provide your social links like this:

```
SOCIAL = (('twitter', 'http://twitter.com/DaanDebie'),
          ('linkedin', 'http://www.linkedin.com/in/danieldebie'),
          ('github', 'http://github.com/DandyDev'),
          ('stackoverflow', 'http://stackoverflow.com/users/872397/dandydev', 'stack-overflow')
```
The first string in each item will be used for both the name as shown in the sidebar, and to determine the [FontAwesome](http://fontawesome.io/icons/)
icon to show. You can provide an alternative icon string as the third string (as shown in the _stackoverflow_ item).
* **Tags** will be shown if `DISPLAY_TAGS_ON_SIDEBAR` is set to _True_ and the [tag_cloud](https://github.com/getpelican/pelican-plugins/tree/master/tag_cloud) plugin is enabled. Normally, tags are shown as a list.
	* Set `DISPLAY_TAGS_INLINE` to _True_, to display the tags inline (ie. as tagcloud)
	* Set `TAGS_URL` to the relative URL of the tags index page (typically `tags.html`)
* **Categories** will be shown if `DISPLAY_CATEGORIES_ON_SIDEBAR` is set to _True_
* **Recent Posts** will be shown if `DISPLAY_RECENT_POSTS_ON_SIDEBAR` is set to _True_
	* Use `RECENT_POST_COUNT` to control the amount of recent posts. Defaults to **5**
* **Archive** will be shown if `DISPLAY_ARCHIVE_ON_SIDEBAR` is set to _True_ and `MONTH_ARCHIVE_SAVE_AS` is set up properly.

Other sidebar related options include:

* To remove the sidebar entirely, set `HIDE_SIDEBAR` to _True_.
* To move the sidebar to the left, set `SIDEBAR_ON_LEFT` to _True_.
* To turn off inlined icons in the titles set `DISABLE_SIDEBAR_TITLE_ICONS` to
  _True_.

### Padded, Single Column Content Style

The main body of the pages will be generated centered and with padding on the sides when `PADDED_SINGLE_COLUMN_STYLE` is set to `True`.

The values in `HIDE_SIDEBAR`, `ABOUT_ME`, and ` AVATAR` are ignored when `PADDED_SINGLE_COLUMN_STYLE` is set to `True`.  This means that none of the sidebar content will be rendered.

Use of the `PADDED_SINGLE_COLUMN_STYLE` can be seen at [droun.in](https://droun.in/).  Note that the example blog is utilizing a modified [Bootstrap/Bootswatch configuration](https://github.com/digitalrounin/bootswatch/tree/drounin/drounin) with [custom CSS](https://droun.in/css/custom.css).

### reStructuredText styles

If you're using reStructuredText for writing articles and pages, you can include the extra CSS styles that are used by the `docutils`-generated HTML by setting `DOCUTIL_CSS` to True. This can be done as a global setting or  setting it in the metadata of a specific article or page.

### GitHub

The theme can show your most recently active GitHub repos in the sidebar. To enable, provide a `GITHUB_USER`. Appearance and behaviour can be controlled using the following variables:

* `GITHUB_REPO_COUNT`: An integer representing the number of repos to display (sorted by modification date, descending)
* `GITHUB_SKIP_FORK`: Either `'false'` [default] or `'true'`. If `'true'`, exclude forked repositories from display in the sidebar. 
* `GITHUB_SHOW_USER_LINK`: If undefined [default], don't show a link to the `GITHUB_USER`'s user page. If defined, show it.

NOTE: Boolean values will _not_ work here! They will be interpreted as literal strings by JS, so instead use `'true'` and `'false'`

### Facebook Open Graph

In order to make the Facebook like button and other social sharing options work better, the template contains Open Graph metatags like `<meta property="og:type" content="article"/>`. You can disable them by setting `USE_OPEN_GRAPH` to _False_. You can use `OPEN_GRAPH_FB_APP_ID` to provide a Facebook _app id_.
You can also provide a default image that will be passed as an Open Graph tag  by setting `OPEN_GRAPH_IMAGE` to a relative file path, which will be prefixed by your site's base url. Optionally, you can override this default image on a per article and per page basis, by setting the `og_image` variable in an article or page.

### Twitter Cards

The theme supports [Summary Twitter Cards](https://dev.twitter.com/docs/cards/types/summary-card). To activate the necessary tags set `TWITTER_CARDS` to `True`. Because _Twitter Cards_ also use Open Graph tags to identify some of the necessary metadata, `USE_OPEN_GRAPH` must also be set to `True` (which is the default).

You can optionally provide a `TWITTER_USERNAME` which will be used to set the Twitter username for the site and for the content creator.

The same image options for Open Graph (see above) can be used for setting images that appear on Twitter Cards. So if you have set an `OPEN_GRAPH_IMAGE` and optionally `og_image` for articles and/or pages, you're good to go for Twitter Cards as well.

### Twitter Timeline

The theme can show your twitter timeline in the sidebar. To enable, provide a `TWITTER_USERNAME` and a `TWITTER_WIDGET_ID`.

To get a `TWITTER_WIDGET_ID`, go to: https://twitter.com/settings/widgets and select `Create new`. You'll find the TWITTER_WIDGET_ID under the html or in the site url:

`https://twitter.com/settings/widgets/TWITTER_WIDGET_ID/edit`

### AddThis

You can enable sharing buttons through [AddThis](http://www.addthis.com/) by setting `ADDTHIS_PROFILE` to your AddThis profile-id. This will display a **Tweet**, **Facebook Like** and **Google +1** button under each post.

* AddThis automatically adds a short hashtag to the end of your URLs. This lets you reveal how often visitors copy your URL from their address bar to share. Example of URL: `http://domain.com/page.html#UF0983`. This function can be disabled by setting `ADDTHIS_DATA_TRACK_ADDRESSBAR` to _False_.
* All social buttons are enabled by default. You can disable certain button by setting following properties to _False_: `ADDTHIS_FACEBOOK_LIKE`, `ADDTHIS_TWEET`, `ADDTHIS_GOOGLE_PLUSONE`.


### Tipue Search

This theme has support for the
[Tipue Search plugin](https://github.com/getpelican/pelican-plugins/tree/master/tipue_search).

All you have to do, is:
- enable the plugin, and the theme will add a search box on the right
  side of the menu
- Add `'search'` to the `DIRECT_TEMPLATES` in your `pelicanconf.py`. E.g. `DIRECT_TEMPLATES = ('index', 'categories', 'authors', 'archives', 'search').
By default, the Tipue search page is configured at "/search.html", but you can override that with the `SEARCH_URL` 
setting, which comes in handy if you have fancy rewrite rules in your Apache or Nginx configuration.

### Flattr

This theme has support for linking your domain with [Flattr](https://flattr.com). To enable this provide your `FLATTR_ID`. Be aware that you will also have to go [Flattr's domain settings](https://flattr.com/settings/domains) and link your domain.

### Footer

The footer will display a copyright message using the AUTHOR variable and the year of the latest post. If a content license mark is enabled (see above), that will be shown as well.

### Sidebar Images

Include a series of images in the sidebar, with an optional header:

SIDEBAR_IMAGES_HEADER = 'My Images'
SIDEBAR_IMAGES = ["/path/to/image1.png", "/path/to/image2.png"]

Originally developed for including certification marks in your sidebar. E.g.,

http://dmark.github.io

### Translations

This template can be translated using pybabel and the enclosed Makefile. See
[Localizing themes with Jinja2](https://github.com/getpelican/pelican-plugins/blob/master/i18n_subsites/localizing_using_jinja2.rst) for more details and pointers.

## Live example

[This is the website of the original author](http://dandydev.net)

If you want more examples of what you could do with this theme, have a [look here](EXAMPLES.md).

## Screenshot

![](screenshot.png)

![](screenshot-article.png)


