A starting point for developing GDI slide sets using the reveal.js library and the jekyll static site generator.
Jekyll is a static-site generator typically used to generate blogs, but also used heavily by Github Pages to publish websites.
This starter kit allows the user to create a RevealJS slide set for a class. This particular version of reveal has been customized specifically by and for Girl Develop It to keep class materials consistent.
The GDIMpls Version of reveal is embedded in this starter kit as a git submodule in order to provide the ability to get central updates when the designs change.
This starter kit needs to have the following software already installed:
gem install bundler
- Hub if you are on a Mac
-
Fork the starter kit into your GitHub account
-
In the repo's
Settings
area, set the "GitHub Pages" section to use "master branch /docs folder" if it isn't already set to that. -
cd
into the local repo you just cloned -
Run the
setup.sh
script -
Modify the files
_staging.yml
and_publish.yml
to fit your repo's needs.
There are some configuration values to set, which are found in the
_config.yml
, _staging.yml
and _publish.yml
files in the home
directory. (See
editing yaml files
in the starter kit wiki.) Edit these files in your code editor and
change the settings to be what you want.
Note: the baseurl
value must begin with a "/" character. Leave
the end without a "/" character as well.
Obvious things like the title, description, and keywords should be changed to fit your new slide set. These appear in the head of the documents, and in the default title page of the of the slide set.
Don't touch baseurl
or url
in this file. These are the values that
work with the Jekyll server so you can preview your work.
This file gets appended to the configuration set when building for
staging. In this file, you should set the url
field by changing the
YOUR_GITHUB_ACCOUNT
string to, well, your github account name.
Change baseurl
to the name of your github repo. Make sure the string
begins with a forward slash ("/").
Change the baseurl
to the name of the github repo as it will be on
https://github.com/gdiminneapolis
. If you don't feel comfortable
doing this, discuss this with at the organization.
NOTE that the jekyll --watch
option does not work on Windows. We have to do something else to make a convenient watching/viewing-as-you-save-changes thing.
Everything should be good to go, now, and you can start up the Jekyll development server to show the slides while you create them.
$ rake
You may want to pay attention to the terminal window running the server, as that is where errors will be reported in case there's something amiss in your slides. Every time you modify a file in folder, jekyll will rebuild the site. Since there's not going to be a lot of slides, or other material, this generally is very fast.
The server will show you the URL you can browse to locally to see the slides. With this initial starter kit set up, there's no live-reloading of changes, so you'll still need to refresh the slide page in the browser.
Slides live in the _slides
folder, and should be named with the
following conventions:
- start with a sequence number, the slides will be ordered by this
sequence number. A good sequencing scheme is
00.00
where the first set of numbers is the class section, and the second set is the slides in that section. Example:00.00.introduction.html
- the slide title, lowercased, only letters, numbers, and dashes -- use dashes for spaces between words.
- the extension
.html
(you can also edit your slides in Markdown using the.md
extension.)
For example, the introduction slide is:
_slides/00.00.introduction.html
and the very last slide would be
_slides/99.99.fin.html
.
A very good practice is to leave gaps in the sequence number to make it easy to rearrange slides if you want, or insert content as you'd like.
If you need more than 100 sections or more than 100 slides per
section, make sure your numbering allows this because the system is
rather stupid about it. Example: 000.001.slide-title.html
. If you do
think you need this, though, think about restructuring the
presentation into more than one slide set. You can create new
collections, for example, and have a root .html
file for each
collection.
Frontmatter is a preamble of YAML settings at the start of every slide.
Every slide needs to have at least the following frontmatter:
---
layout: slide
---
You can also put other meta data in the frontmatter. A useful one is the slide's title:
---
layout: slide
title: Let's Develop It!
---
And you can use the title in the body with a little Liquid:
<h1>{{ page.title }}</h1>
This comes in very handy when there are multiple section
s in the
slide to put the title on each section
.
After that point, you can provide the HTML that will make up your slide.
In reveal.js
whatever appears within a <section>
tag is the body
of the slide. The slide
layout in the frontmatter provides this for
you, so you can simply start on the content.
For example, the standard "Welcome" slide has the following content:
---
layout: slide
title: "Welcome!"
---
<h1>{{ page.title }}</h1>
<div class="left-align">
<p>Girl Develop It is here to provide affordable and accessible programs to learn software through mentorship and hands-on instruction.</p>
<p class="green">Some "rules"</p>
<ul class="go-wide">
<li>We are here for you!</li>
<li>Every question is important</li>
<li>Help each other</li>
<li>Have fun</li>
</ul>
</div>
which should be pretty easy to figure out.
Note that slides can also be in MarkDown form. Use the .md
or
.markdown
extension instead of .html
.
---
layout: slide
title: "Welcome!"
---
# {{page.title}}
<div class="left-align">
Girl Develop It is here to provide affordable and accessible programs to learn software through mentorship and hands-on instruction.
Some "rules":
{:.green}
* We are here for you!
* Every question is important
* Help each other
* Have fun
{:.go-wide}
</div>
Using the class .fragment
on an element will cause that element to
be loaded after the slide loads, like slide ups in powerpoint.
You can have slides roll up as well as over by making sub <section>
elements in the slide body.
This might make navigating confusing for some, however, since they may not realize they have to press the down key instead of the right key. If they using the space bar to navigate from slide to slide, they'll get them in the right order.
Since we're all about the code, you can place code snippets on the slide using Jekyll's highlight
feature:
Here's an example:
{% highlight html linenos %}
<div class="introduction">
<h1>Introduction</h1>
<ul>
<li>My Life</li>
</ul>
</div>
{% endhighlight %}
Make sure to keep your snippets short, so they stay on the slide nicely.
There are several helper and override classes defined in _sass/_overrides.scss
. Please feel free to add to this for your own work. You can add more Sass partials to the _sass/
directory as well, just make sure they get @import
ed in css/main.scss
.
The js/
directory holds the scripts you can change, or add your own. If you add new script files, make sure the add them in _includes/scripts.html
as well. Follow the pattern used there for revealConfig.js
.
To build the slide presentation for publication, stop the running
jekyll
server with ctrl-C
. Then at the command line, enter:
$ rake staging
or
$ rake publish
This will build the presentation into the docs
folder. You can open
the presentation from there to see if it's as you want.
With the new Github pages feature of serving from the master's docs/
folder, all the worry about setting up a special gh-pages
branch and
tweaking the local build destination has gone away. After the above
build step, just add, commit, push the changes including the docs/
folder to the remote repo.
Like with any other project, use git's features to maintain a good clean working tree and remote repository. When you want to start off on a new feature, or just try something out, create a branch. If it's what you want, merge it back in to master.
This project is intended to be a safe, welcoming space for collaboration, especially among members of Girl Develop It and it's various chapters. Contributors are expected to read and follow the Contributor Covenant code of conduct.
Feel free to fork this repo and make changes as you want. If you want to contribute back, submit a PR at https://github.com/gdiminneapolis/jekyll-reveal-starter-kit/pulls with your changes. Bug reports, issues, questions, and suggestions are welcome at https://github.com/gdiminneapolis/jekyll-reveal-starter-kit/issues. The project has a wiki at https://github.com/gdiminneapolis/jekyll-reveal-starter-kit/wiki where you can contribute wisdom and share information about using the starter kit.
This project is licensed as Creative Commons Attribution Non-commercial 3.0 Unported (CC BY-NC 3.0) https://creativecommons.org/licenses/by-nc/3.0/.
-
The Jekyll team, especially parkr
-
Hakim El Hattab, creator of
reveal.js
-
Cara Jo of the GDI Boulder team