Blog Setup Day3

Set up my personal website using Jekyll


Reveal.js is a powerful tool to build slides on web using HTML or Markdown. To use it locally is very easy, just download the source code on github and open demo.html you can see the result in your browser. Using it on web page is almost the same, put reveal.js in /assets/reveal.js and modify the path in demo.html to the folder in assets, then everything works.
Reveal.js has natural support of Markdown, which makes it possible for us to integrate it into our jekyll based web page.

Online Solutions

There are already some solutions to integrate reveal.js in jekyll, like jekyll-revealjs, reveal-jekyll. Most of them use costum plugins to porcess raw html files generated by jekyll to reveal.js’s style, this can cause several confusions:

  • many previous solutions require you to write every slide in seperate file
  • jekyll defaultly generates html file for every post using its own parser, this may cause images, math equations and codes incompatible with reveal.js
  • for the same reason, it’s also inconvinent to directly put md code into html letting reveal.js to process markdown using marked

Spending a lot of time sereaching and testing, I decided to turn to offline solutions.


Pandoc is extremely useful to convert files from one format into another, not surprisingly it supports reveal.js:

pandoc -t revealjs -s -o myslides.html -V revealjs-url=

revealjs-url can be local directory like /assets/reveal.js, you can also use other command to specify styles and templates. Notice that the version of your pandoc and reveal.js must be compatible, see more information on this page.

Set Up Pipeline

The first thing to do is to find a place to store markdown files and generated html files. I set up two directories _slides and _slides-md under home directory, then I can create a ruby script generate.rb to generate those slides:

require 'find'

puts "Generate all slides"
Find.find('_slides-md') do |path|
    if path != '_slides-md'
        output_path = path.sub("_slides-md/", "_slides/").sub(".md", ".html")
        puts "source file: " + path
        puts "output file: " + output_path
        system "pandoc -t revealjs -s -o " + output_path + " " + path + " -V revealjs-url=/assets/reveal.js"

puts "Start server"
exec "bundle exec jekyll serve --draft"

The good thing is that now I can use ruby generate.rb to replace bundle exec jekyll serve and care nothing more.
Next thing is permalinks. Add _slides to _config.yml’s inclusion, then all the slides can be accessed in <home-url>/_slides/<name>.html. I also want an archive page for all slides like BLOG in the navigator, this can be done using collection in jekyll. Noticing that directly set up a collection for _slides it won’t work, because we have a bunch of HTML files there rather than Markdown files like those in _posts. To let this work, we can set a collection for _slides-md, then create a navigation page using collection.html in _layouts. At last, the href of each slides need to be reset to _slides rather than [[post.url]], other wise it can only lead to the jekyll-rendered post page. My layout for this page is also listed here:

layout: archive
<!--[ ] for { }-->
[[ content ]]

[% assign entries_layout = page.entries_layout | default: 'list' %]
<div class="entries-[[ entries_layout ]]">
    [% assign entries = site[page.collection] %]
    [% assign entries = entries | sort: 'title' %]
    [%- for post in entries -%]
            [%- unless post.hidden -%]
                [% if post.header.teaser %]
                    [% capture teaser %][[ post.header.teaser ]][% endcapture %]
                [% else %]
                    [% assign teaser = site.teaser %]
                [% endif %]
                [% if %]
                    [% assign title = post.title | markdownify | remove: "<p>" | remove: "</p>" %]
                [% else %]
                    [% assign title = post.title %]
                [% endif %]
                <div class="[[ include.type | default: 'list' ]]__item">
                    <article class="archive__item" itemscope itemtype="">
                    [% if include.type == "grid" and teaser %]
                        <div class="archive__item-teaser">
                        <img src="[[ teaser | relative_url ]]" alt="">
                    [% endif %]
                    <h2 class="archive__item-title no_toc" itemprop="headline">
                    <a href="/_slides/[[ post.url | remove:'/slides/' ]].html" rel="permalink">[[ title ]]</a>
                    [% include post__meta.html type=include.type %]
                    [% if post.excerpt %]<p class="archive__item-excerpt" itemprop="description">[[ post.excerpt | markdownify | strip_html | truncate: 160 ]]</p>[% endif %]
            [%- endunless -%]
    [%- endfor -%]
Liangwang Ruan
Liangwang Ruan
Ph.D Student

I’m a Ph.D student from Peking University advised by Baoquan Chen.