pandoc-markdown-jekyll-theme¶ ↑
This is a Jekyll theme for blogging with Pandoc. It's based off of Pandoc Markdown CSS Theme for the original CSS file. Read more about the theme there.
Installation¶ ↑
There are two external dependencies in order to use this theme:
Follow the installation instructions for your platform. If you’re using macOS, installation is as easy as:
brew install pandoc brew install jez/formulae/pandoc-sidenote
Next, add this line to your Jekyll site's Gemfile:
# -- Gemfile -- # ... gem "pandoc-markdown-jekyll-theme"
And then run:
# Install the Jekyll theme bundle install # Copy out one file that has to live in the site folder, not the theme cp $(bundle info pandoc-markdown-jekyll-theme --path)/_template.html5 . # Bust the Jekyll cache (Jekyll doesn't track _template.html5 changes) rm -rf .jekyll-cache
And finally, update your _config.yml
file:
# -- _config.yml -- theme: pandoc-markdown-jekyll-theme gems: - jekyll-pandoc markdown: Pandoc pandoc: extensions: - from: 'markdown+smart+tex_math_single_backslash' - filter: 'pandoc-sidenote' - template: '_template' - katex - toc - M: 'site__baseurl=/'
If your Jekyll site has a baseurl:
setting in _config.yml
, change the last line above to site__baseurl=$BASEURL/
, replacing $BASEURL
with what the setting of your baseurl
property reads. (There is unfortunately no easy way to get the Pandoc template file to read from the Jekyll config, so the value must be duplicated.)
Usage¶ ↑
The following variables are used by this theme.
-
site.title
-
Only shows up as suffix in
<title>
element -
page.title
-
site.author
-
page.author
-
page.author_url
-
site.baseurl
-
Make sure you don't have a trailing slash here
-
site.header_includes
-
page.header_includes
-
You can use these to include raw HTML in the
<head>
-
site.include_after
-
site.pandoc_markdown_skip_syntax_theme
-
Set to
true
to skip including the default syntax theme CSS file. -
page.include_after
-
You can use these to include raw HTML in the
<body>
before the content -
site.include_before
-
page.include_before
-
You can use these to include raw HTML in the
<body>
after the content -
page.layout
-
Pick one of
index
,page
, orpost
-
index
won't have a “Return home” link at the bottom of the page -
page.subtitle
-
Shows up in the page.
-
site.description
-
page.description
-
Only shows up in the
<head>
section, as a<meta>
tag. -
page.date
-
page.keywords
-
page.math
-
If
true
, we'll include KaTeX for displaying math formulas. Will add JavaScript on this page. -
page.lang
-
Sets the HTML lang attribute. Default:
'en'
-
page.dir
-
Sets the HTML dir attribute. Default:
'ltr'
You can also define:
-
_includes/enable_checkboxes.html
to be an empty file in your project to remove the only non-math JavaScript.
Developing¶ ↑
To make a release:
vim pandoc-markdown-jekyll-theme.gemspec git commit pandoc-markdown-jekyll-theme.gemspec -m "$version" git tag "$version" git push --tags origin master gem build pandoc-markdown-jekyll-theme.gemspec gem push "pandoc-markdown-jekyll-theme-$version.gem"