How this site was made
Although this site is nothing special, I made it in a way that eases maintenance for me - its main purpose is publishing mostly textual information to students, and I wanted to do it in the most simple and efficient way.
First, I decided I wanted to use markdown rather than editing HTML directly, or using a CMS which stores the information/text in some obscure way making it hard to backup, version or reuse content.
Github Pages offer a great solution to what I wanted based on Markdown and Jekyll. Also, just pushing to the repository to github triggers a site build and deployment to the github servers.
- Source for this Site - if you find a typo and want to let me know the cool way, send me a pull request. But be beware, you might find content there that is not yet meant to be published - especially the exercises from former semesters. Don’t start working on them, I might decide to change them and they don’t become official before I link them from the classes’ page!
This site is also deployed to https://home.htw-berlin.de/~kleinen/.
Jekyll
This site uses Jekyll as site generator - producing a static HTML site out of markdown sources and layout templates.
- On Github, Jekyll is triggered automatically on each push to the repository https://github.com/bkleinen/bkleinen.github.io and publishes the page to https://bkleinen.github.io
- for publishing to https://home.htw-berlin.de/~kleinen/I use this script: _bin/deploy-htw.sh
-
locally, I run
jekyll serve --drafts to have the site served on localhost:4000 and automatically rebuilt on every file save. - kramdown: For Markdown Processing, kramdown is used.
HTML Proofing
I use the HTML proofer gem to check for broken links. HTML::Proofer is called via rake, and a travis configuration performes the tests automatically if pushed to github. See the Rakefile and the travis config file .travis.yml for specifics.
Sass preprocessing
To ease working on the css stylesheets, I also use Sass preprocessing.
As of Jekyll 2.2.0, this is part of jekyll. So I updated my site to use the built-in Sass support. To do so, only the sass/scss files go into /css and need to start with the following lines to trigger the files beeing handled by jekyll:
---
---
all included files needed to be moved to the _sass subdirectory.
- https://jekyllrb.com/docs/assets/
- https://sass-lang.com/tutorial.html
- https://de.selfhtml.org for css basics
Bootstrap
I’ve followed this tutorial to integrate Bootstrap with this site: https://simpleit.rocks/how-to-add-bootstrap-4-to-jekyll-the-right-way/ The basic steps are:
- bootstrap css should be compiled from sass to enable theming, and the sass integration of jekyll should be used for that.
Adjustments:
- as github pages runs jekyll in safe mode, the extra load path for sass will not work.
- I’ve copied the sass files to the _sass subdirectory, see _bin/copy-sass.sh