A Course Template using AsciiDoctor

This project is a template for computer science course materials. The template uses Asciidoctor source files to generate various documents (Reveal.js slides, HTML "book").

Structure of the project

The main file of the project is index.adoc. It includes the chapters of the course which are in their own directory. Images are in the figs directory in each chapter. Source code examples are put in the examples directory. An option for code examples is to use git-subrepo to integrate examples from another git repository.

Metadata about the course (author and version) are in the file meta.adoc Configuration parameters specific to book output are in index.adoc. Parameters common to book and slide output are in attributes.adoc.

When a chapter directory is added, deleted or if its name changes, the Rakefile has to be updated.

Project building

Building the project requires a Ruby environment. More precisely,

• Ruby packages (gems) are managed with bundler,

• building the project required rake, and

• graphviz is used for some diagrams.

Tools setup (on Debian/Linux, first time only)

$ sudo apt-get update && sudo apt-get -y install bundler

Ruby dependencies setup (first time only)

$ bundle install

Course building

$ rake

See also

• Asciidoctor

• Reveal.js

Deploying on github pages

The public site can be accessed using github pages. The content on branch gh-pages is used as the root for the web site.

1. Switch to branch gh-pages

   $ git checkout gh-pages

2. Copy the content of the html directory to the root

   $ mv html/* .
   $ rm -r html

3. Commit the changes (if there is new content, use git add before)

   $ git ci -am"Update the public site"

4. Publish on github

   $ git push origin gh-pages