Pandoc v2 Support

VERSION: 2.0
PANDOC:  2.1.1
STATUS:  5/12 themes ported

Good news for all maintainers of Awesome lists on GitHub: running a GitHub Pages website mirroring your README.md contents is now a one-click operation!

With gh-themes-magick you can publish your project’s single page website from a /docs/ folder on your master branch, using GitHub Page Generator’s themes, and auto-magically update its contents to mirror the project’s README.md.

• Fully static (no Jekyll)
• No gh-pages branch involved
• Single YAML configuration file
• All the power of pandoc v2
• Now with Task-Lists support

The configuration.yaml file exposes all the template’s variables, providing access to the website’s metadata fields (description, keywords, ecc.) needed to boost your website SEO, and extra variables to include additional sytlesheets, custom javascript, and more.

And – of course – this also works with any GitHub project looking for a single-page website, not necessarily built from the project’s README.md but from any markdown documents. Likewise, with a few simple tweaks to the build script you can create a multipage website, exploiting the full power of pandoc’s Markdown flavor.

Contents

• Introduction
• How It Works
• Main Features
  • Single Configuration File
  • Syntax Highligthing
  • Task-Lists Support
• Available Themes
• Setting up a Website
• Updating Its Contents
• Licenses and Credits
  • GitHub Themes
  • Highlight.js
  • Task-List Lua Filter

Introduction

I started to work on gh-themes-magick project at a time when GitHub Pages automatic generator did not allow to chose a theme for project sites published from the /docs/ folder on your master branch. But 3 days before this project was completed, GitHub announced that this very feature was now available:

• https://github.com/blog/2295-new-theme-chooser-for-github-pages

… this somehow obliterated the main purpose of gh-themes-magick — ie: being able to use GitHub themes from master branch and have the website contents mirror the README file.

Still … gh-themes-magick offers an alternative approach to publishing your project site — using pandoc templates instead of Jekyll. This allows easier customization of the themes themselves. Also, this project is open to host user created themes, beside those offered by GitHub; so, hopefully this repo might grow in time, offering a great variety of themes to chose from.

With the release of pandoc v2, this project has acquired new meaning because of the powerful new features introduced in pandoc v2.

How It Works

gh-themes-magick exploits pandoc’s super-powers to convert your repo’s README.md file to a docs/index.html themed file. Your are basically getting a copy of the same themes found on GitHub’s automatic page generator, plus a pandoc html5 template for each theme, and scripts to auto-magically convert/update your project’s single-page website contents from the README.md file in your repo’s root.

This means that now you can:

1. Enjoy GitHub’s automatic page generator themes when publishing your website from the /docs/ folder on your master branch .
2. Update your website to mirror the repo’s latest README.md file, with a single click.

Main Features

Single Configuration File

Website configuration is handled by a single YAML file: configuration.yaml.

Its settings are highly intuitive, comments and sample values are provided for guidance:

# ==============================================================================
#                                 WEBSITE HEADER                                
# ==============================================================================
# These variables are shown in the website header.
# ------------------------------------------------------------------------------
website_title:   'GitHub Pages Themes Magick'
website_tagline: 'A one-click website in `master` branch'

You only have to set once your GitHub username and repo name, gh-themes-magick will create all the template’s required URLs from them:

# ==============================================================================
#                                  GITHUB LINKS                                 
# ==============================================================================
# The following variables are used for automagically creating links to your repo
# on GitHub, and for the .zip and .tar download links.
# ------------------------------------------------------------------------------
# Example: https://github.com/tajmone/gh-themes-magick
your_github_username: tajmone
your_github_reponame: gh-themes-magick

The website metadata is exposed through template variables which allow you to control how your website will be indexed by search engines (optimizing your ranking):

description: 'Your project description, to be shown in search engines results.'
keywords:
  - your
  - keywords list

And many more fine-grain settings are availble within configuration.yaml.

Syntax Highligthing

gh-themes-magick uses highlight.js browser library for highlighting code blocks.

Syntax highlighting occurs automatically because highlight.js does a good job at auto-detecting languages within code blocks. But you can also follow best practices and add the language identifier to fenced code blocks in your markdown source:

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

and your code will shine like this on your project’s website:

require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html

You can disable syntax highlighting for any fenced code block by giving it the nohighlight identifier:

```nohighlight
@ECHO "This block won't be syntax-highlighted"
```

Each theme comes with a custom prebuilt version of highlight.js (9.12.0) with 24 commonly used languages:

You can create your custom build of highlight.js directly in your browser: on the website’s download page pick any languages you want from a list of 176 languages and download a taylored version to overwrite the one that comes with gh-themes-magick by default.

You can also overwrite the syntax highlighting theme, replacing it with on of the 79 themes available from highlight.js, or with your custom color scheme.

Markdown

# Markdown Is Cool

Write text [with links](http://example.com) inline or [link references][1].

* one _thing_ has *em*phasis
* two __things__ are **bold**

[1]: http://example.com

Python

@requires_authorization
def somefunc(param1='', param2=0):
    r'''A docstring'''
    if param1 > param2: # interesting
        print 'Gre\'ater'
    return (param2 - param1 + 1 + 0b10l) or None

diff

Index: languages/ini.js
===================================================================
--- languages/ini.js    (revision 199)
+++ languages/ini.js    (revision 200)
@@ -1,8 +1,7 @@
 hljs.LANGUAGES.ini =
 {
   case_insensitive: true,
-  defaultMode:
-  {
+  defaultMode: {
     contains: ['comment', 'title', 'setting'],
     illegal: '[^\\s]'
   },

CSS

@font-face {
  font-family: Chunkfive; src: url('Chunkfive.otf');
}

body, .usertext {
  color: #F0F0F0; background: #600;
  font-family: Chunkfive, sans;
}

@import url(print.css);
@media print {
  a[href^=http]::after {
    content: attr(href)
  }
}

Apacheconf

# rewrite`s rules for wordpress pretty url
LoadModule rewrite_module  modules/mod_rewrite.so
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php [NC,L]

ExpiresActive On
ExpiresByType application/x-javascript  "access plus 1 days"

Order Deny,Allow
Allow from All

<Location /maps/>
  RewriteMap map txt:map.txt
  RewriteMap lower int:tolower
  RewriteCond %{REQUEST_URI} ^/([^/.]+)\.html$ [NC]
  RewriteCond ${map:${lower:%1}|NOT_FOUND} !NOT_FOUND
  RewriteRule .? /index.php?q=${map:${lower:%1}} [NC,L]
</Location>

Task-Lists Support

Now gh-themes-magick supports GitHub Flavored Markdown’s Task-Lists, thanks to the pandoc Lua filter task-list.lua:

• Add Task-Lists support
  • Thanks to pandoc Lua filters
• Introduced in pandoc v2.x
• Wasn’t available in pandoc v1.x

Available Themes

Currently, 5 of the 12 GitHub themes have been ported to gh-themes-magick, the one used by this site (Architect, by Jason Long) being one of them.

Click on the thumbnails to see a live preview of the other four:

Cayman	Dinky
by Jason Long	by Diana Mounter
CC-BY 4.0	CC-BY 3.0

Leap Day	Merlot
by Matt Graham	by Cameron McEfee
CC BY-SA 3.0	MIT

Setting up a Website

These are the steps:

1. Install pandoc
2. Get gh-themes-magick
3. Choose a theme
4. Copy it to your repo’s master branch
5. Rename the theme folder to /docs/
6. Fill-in the YAML config file
7. Run the abracadabra script
8. Commit and push changes
9. Set GitHub Pages to publish from /master/ branch /docs/ folder

That’s it! Your project website is now live.

(Click here to view GitHub’s Help on how to configure a publishing source for GitHub Pages)

Updating Its Contents

Whenever you want to update your website to mirror the contents of your repo’s README.md:

1. Run the abracadabra script
2. Commit and push changes to master

For detailed instructions on setup and customization, refer to the project’s documentation and online Wiki.

Licenses and Credits

gh-themes-magick is copyright © 2016, Tristano Ajmone (@tajmone).

Tristano Ajmone (@tajmone) is the creator an maintainer of the gh-themes-magick project. First released in December, 2016.

GitHub Themes

gh-themes-magick is released under the Creative Common Attribution 4.0 International License (CC BY 4.0). The project is built around third party themes, each one isolated in its own folder and each released under the terms of its upstream license:

Detailed information on the themes’ licenses, and about the adaptative changes made to the original code and resources, can be found in each theme’s folder, inside the LICENSE and CHANGELIST files.

Highlight.js

All themes also contains a copy of the highlight.js library and one of its CSS themes. Highlight.js is copyright © 2006, Ivan Sagalaev, released under BSD-3-Clause License. The following highlight.js themes have been included in gh-themes-magick (some with changes):

• “GitHub Gist” by Louis Barranqueiro.
• “Docco”, coverted from Docco by Simon Madine.
• “VIM-Hybrid” by w0ng (https://github.com/w0ng/vim-hybrid)

Task-List Lua Filter

The scripts to convert from markdown to HTML use the task-list.lua pandoc filter, copied from the lua-filters project, released under the MIT license.