GitHub Pages Themes Magick

Static project website from README.md file — Published from master branch

🡸 Give gh-themes-magick a star!


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.

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

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:

… 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:

1. Apache 13. JavaScript
2. Bash 14. Makefile
3. C# 15. Markdown
4. C++ 16. Nginx
5. CSS 17. Objective-C
6. CoffeeScript 18. PHP
7. Diff 19. Perl
8. HTML, XML 20. Python
9. HTTP 21. Ruby
10. Ini 22. SQL
11. JSON 23. Shell Session
12. Java 24. YAML

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:


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
Cayman Dinky
CC-BY 4.0 CC-BY 3.0

Leap Day

Merlot

by Matt Graham by Cameron McEfee
Leap Day Merlot
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:

THEME AUTHOR FOLDER LICENSE
Architect Jason Long /gh-themes/architect/ CC-BY 4.0
Cayman Jason Long /gh-themes/cayman/ CC-BY 4.0
Dinky Diana Mounter /gh-themes/dinky/ CC-BY 3.0
Leap Day Matt Graham /gh-themes/leapday/ CC-BY 3.0 + MIT
Merlot Cameron McEfee /gh-themes/merlot/ MIT

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):

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.

🡸 Don’t forget to star gh-themes-magick!