Academic and Educational Static Website Generation

Recent Advances in Information Science

ALMIR MUTAPCIC, Ph.D. Computer Science Department University Sarajevo School of Science and Technology Hrasnička cesta 3a, Sarajevo 72000 BOSNIA AND HERZEGOVINA [email protected]

Abstract: - In this paper, we present a solution and a set of good practices for academic and educational static website generation and maintenance. We present a publishing framework based on open-source software such as Jekyll, Pygments, MathJax, Git, and others. We show how a sample educational site can be setup and hosted for free on modern web services such as GitHub, Amazon AWS, and Heroku.

Key-Words: - Computer based education, Education, Open source software, Website generation

1 Introduction In this paper, we describe a solution and a set of There are many open-source and commercial good practices for generation and maintenance of blogging and content management system (CMS) academic and educational static websites, based on platforms such as Drupal, Joomla, and WordPress, the following components: which can be used to publish and maintain academic and educational websites. Most of these platforms 1. Jekyll: static site generation generate dynamic sites, in the sense that they require 2. Git: distributed version control of the content a dynamic server-side component (e.g., a relational 3. Pygments: syntax highlighter database) to store the site content. Often this makes 4. MathJax: math equation rendering 5. HTML5/CSS3/JavaScript: front-end code these platforms complex and hard to maintain.

Recently there have been several attempts to These technologies (in particular Jekyll and Git) are simplify blogging platforms, and hence generation ideal for group collaboration when creating sites for and maintenance of blogging content. One of the educational courses, group research pages, and other more popular new blogging platforms is Jekyll, a similar sites. blog-aware, static site generator written in Ruby.

Jekyll takes a template directory, representing a raw form of a website, runs its marked content through 2 Problem Formulation converters (such as Markdown, Textile, or Liquid We would like to find a framework for generation converters), and generates a complete, static website and maintenance of academic and educational sites. The framework would generate static sites and that can be served using Apache, Nginx, or any would not require dynamic server-side components, other web server. Jekyll is also the engine behind such as relational databases to store the site content. GitHub Pages, a service that hosts GitHub users’ The dynamic components should be implemented personal and open-source project pages for free [1]. using the front-end browser technologies, such as In the engineering academic community, jemdoc HTML5, CSS3, and JavaScript. has become a popular tool to generate academic and The framework should favor convention-over- educational static sites. jemdoc is a light text-based configuration, a popular design principle in modern markup language and static site generator written in web frameworks. It should also use LaTeX for Python, with advanced features such as LaTeX typesetting math equations and YAML/JSON for equation generation, table support, and CSS-based configuration markup. YAML and JSON are data styling. Its LaTeX support is the most interesting serialization formats designed for human readability feature for the engineering and math community; and easy interaction with scripting languages [3]. however, it also adds an external dependency on the The framework should use a modern distributed latex and dvipng system executables to process the version control systems, such as Git or Mercurial. embedded equations [2].

ISBN: 978-960-474-304-9 330 Recent Advances in Information Science

3 Problem Solution using the triple-dashed lines. Here, we can set any We propose to use Jekyll for the main static site Jekyll predefined variables or custom variables. For generation. We recommend writing the site content example, we use custom variables lecture and lab such as lecture and lab material in GitHub-flavored to declare a lecture or lab post, respectively. markdown format [4]. We augment Jekyll with Pygments for code syntax highlighting [5] and use 3.2 Lecture posts MathJax to display math symbols and equations [6]. Each lecture post is denoted with the lecture field We use Git for version control and distributed that specifies the lecture number. For example, the group collaboration. It is often helpful to setup a first lecture post file with the name 2013-02-25- remote repository for the site on GitHub, BitBucket, lecture-1.md is given below: or a similar provider of hosted Git services. We can then open-source the site, in which case the web community can participate in improving its content. --- 3.1 Site structure layout: post A basic Jekyll site for educational site can be lecture: 1 organized using the following structure: ---

Lecture {{ page.lecture }} . |-- _config.yml ======|-- _includes |-- _layouts - introduction to the class | |-- default.html - administrative information | `-- post.html - syllabus overview |-- _posts | |-- 2013-02-25-lecture-1.md | `-- 2013-03-08-lab-week-2.md 3.3 Lab posts |-- _site Each lab post is denoted with the lab field that gives |-- javascript its lab week. We also use the assignment field to |-- css specify its corresponding pdf file (which is placed under the pdf directory). For example, the lab post |-- pdf file with the name 2013-03-08-lab-week-2.md is `-- index.html given below: where the files and directories are described below.

--- _config.yml: stores site configuration data. _includes: the partials that can be mixed and layout: post matched by layouts and posts to reuse data. lab: week 2 _layouts: the templates for lecture and lab posts. assignment: Week 2 CSIS160.pdf _posts: the content files (for example, the lecture --- and lab posts), which are named using the year- month-day-title.markup convention. Lab {{ page.lab }} _site: the folder where the generated site is placed. ======javascript: the directory with javascript files. - Eclipse and Java quick start css: the directory with CSS styles. - Lab : the directory with our pdf files (such as lecture pdf assignment handouts, lab assignments, homeworks, etc.) index.html: the main site index file.

Each post file can be configured using the front 3.4 Index file and supporting files matter blocks, which must be the first thing in the The index file can be fully customized using Liquid file and are separated from the rest of the content templates and markup code [7]. An example index

ISBN: 978-960-474-304-9 331 Recent Advances in Information Science

file that processes the course posts and sorts the modify the Jekyll source itself. In general, plugins lecture and lab posts based on their front matter will fall into one of the following four categories: variables is shown below. generators, converters, tags, and filters. There are many available prebuilt Jekyll plugins that can be used for academic and educational sites: MathJax

Lectures:

Liquid tags, archive generator, table of contents

{{ post.date | date: "%d %b %Y" }} » {{ post.title }} Any files or directories that are not part of the {% if post.slides %} standard Jekyll or plugins source system will be ( passed without processing to the generated final site slides) directory. This way we can extend the static site {% endif %} with any custom HTML content, and in particular,

Disqus [10], or analytics system for site engagement

Labs:

tracking such as Google Analytics [11].

{{ post.date | date: "%d %b the content from a local web server, we just need to %Y" }} » {{ post.title }} by the web server. {% if post.assignment %} It is also easy to serve the generated site from a (assignment< Heroku [12]. Often we just need to setup a proper /a>) Git branches on our remote server and a source push {% endif %} to the service will cause it to update the live site. For

example, we have the following remote GitHub {% endif %} branches defined for our Java programming class {% endfor %} CS/IS 160 at Sarajevo School of Science and

Technology. After committing new course material to the local Git repository, we perform a remote source push, which automatically refreshes the live A similar index site can be implemented to list course website on GitHub. academic research papers, for example, sorted based on their research subject or published time criteria. The index and posts files can be easily coded and $ git remote –v marked up to implement arbitrary functionality and origin format of the site content. https://github.com/csis160/csis160.github. com.git (fetch) 3.5 Plugin system https://github.com/csis160/csis160.github. The Jekyll plugin system allows integration of com.git (push) custom generated content specific to each site. We can run custom code for the site without having to $ git push origin master

ISBN: 978-960-474-304-9 332 Recent Advances in Information Science

4 Conclusion In this paper, we have presented a procedure and a set of good practices for generation of academic and educational static websites. The framework is built around the Jekyll blogging software, Jekyll-powered templates and plugins, and it also uses other open- source technologies such as markdown format, Pygments, MathJax, Git, and others. Several site templates and examples are available on GitHub.

References: [1] Jekyll, https://github.com/mojombo/jekyll. [2] jemdoc, http://jemdoc.jaboc.net. [3] YAML, http://www.yaml.org. [4] GitHub Flavored Markdown, https://help.github.com/articles/github-flavored-markdown. [5] Pygments, http://pygments.org. [6] MathJax, http://www.mathjax.org. [7] Liquid, http://wiki.shopify.com/Liquid. [8] Jekyll Plugins, https://github.com/mojombo/jekyll/wiki/Plugins. [9] CodeMirror, http://codemirror.net. [10] Disqus, http://disqus.com. [11] Google Analytics, http://google.com/analytics. [12] Jekyll Deployment, https://github.com/mojombo/jekyll/wiki/Deployment.

ISBN: 978-960-474-304-9 333