swiftfire-jekyll-theme 0.2.0

data/pages/classic/06-categories.md

@@ -0,0 +1,38 @@
+---
+layout: page
+title: "Categories in classic"
+date: 2017-12-15
+menuInclude: yes
+menuTopTitle: Classic
+menuSubs:
+- title: About Categories
+  index: 6
+excerpt: "An excerpt is used as the page description and can be up to 160 characters long..."
+---
+
+### Category pages
+
+Category pages can be created with a little assistance of the web designer. To kick of the creation of a category page, create a page with the `layout` set to _category-page_. Also add a `title` that is set to the name of the category for which the page is created.
+
+An example can be seen in the _pages/categories/classic.md_ file:
+
+	---
+	layout: category-page
+	title: classic
+	---
+
+All other content in a category generation file is ignored.
+
+### Category Menu Item
+
+To enable the creation of a category menu item set the `site.data.setup.generate-categories-menu parameter` to _yes_. This will create a drop-down menu entry with the names of the categories for which pages were generated.
+
+PS: The name of the categories menu item can be configured in `site.data.text-for.tCategories`.
+
+### Category widget
+
+As an alternative to the menu a widget is available that can be included somewhere to have access to the category pages.
+
+### Widget or Menu
+
+Using the categories menu is not possible when the drop-down menus are disabled (by setting `site.data.setup.drop-down-menu` to _no_). In that case the widget is the only way to access the categories pages.

data/pages/classic/07-terminology.md

@@ -0,0 +1,35 @@
+---
+layout: page
+title: Terminology
+date: 2017-12-15
+tertiary-column: none
+menuInclude: yes
+menuTopTitle: Classic
+menuSubs:
+- title: Terminology
+  index: 7
+excerpt: The terminology used throughout the classic-jekyll-theme code base
+---
+When configuring the many options it is necessary to have a good view of the names used in the layout.
+
+At the top level there are the following visible elements:
+
+![top-level elements]({{ "/assets/img/top-level-layout.png" | relative_url }}){:.image-centered}
+
+Of these the footer-separator and footer have no further internal decomposition.
+
+The banner-area is the most complex as is displayed below. The column-panel is the main content panel and is divided into the following sub-components:
+
+![column elements]({{ "/assets/img/column-panel-layout.png" | relative_url }}){:.image-centered}
+
+The secondary-column and tertiary-column may be swapped in place, or disabled altogether.
+
+The banner-area is build from the following components:
+
+![column elements]({{ "/assets/img/banner-area-layout.png" | relative_url }}){:.image-centered}
+
+Of these elements the menubar and menubar-bottom-separator may be made invisible by tapping or clicking the menu-symbol. The elements in the banner itself may be arranged differently, or may be absent.
+
+All elements (except the primary-column) can be disabled.
+
+It is also possible to insert an icon into the menubar and disable the banner. This means that the banner-area then only consist of the menubar and its separators (which can also be disabled).

data/pages/classic/08-versioning.md

@@ -0,0 +1,23 @@
+---
+layout: page
+title: Versioning
+date: 2017-12-20
+tertiary-column: none
+menuInclude: yes
+menuTopTitle: Classic
+menuSubs:
+- title: Versioning
+  index: 8
+excerpt: The versioning approach for Classic
+---
+Classic uses the versioning approach Major.Minor.Patch.
+
+However due to the nature of theme's the interpretation of these number is slightly different.
+
+Classic will update the _Patch_ number when adding to the content area's of the theme. I.e. posts or pages. There is no need to follow these updates closely for your own theme.
+
+Classic will update the _Minor_ number when bugfixes or minor additions are made. A list of changed files will be provided. It may be necessary to re-apply changes that were made to the theme's files at your end.
+
+Classic will update the _Major_ number when significant additions have been made. The difference between minor and major additions is entirely subjective.
+
+Backwards compatibility with previously used YAML tags is a very important driver for further development.

data/pages/classic/09-problems.md

@@ -0,0 +1,25 @@
+---
+layout: page
+title: Problems & Workarounds
+date: 2018-02-01
+tertiary-column: none
+menuInclude: yes
+menuTopTitle: Classic
+menuSubs:
+- title: Problems and workarounds
+  index: 9
+excerpt: A discussion of problems that might occur and possible work arounds
+---
+## Issue 16: Youtube-player widget shows video on top of banner for top-fixed banner layout.
+
+Due to the way youtube videos are displayed it is not possible to use the youtube-player.html widget when the banner position is set to top-fixed in the setup.yml file.
+
+To include youtube video's use the iframe directly like this:
+
+~~~~
+    <iframe src="https://www.youtube.com/embed/video-id" width="100px" height="56.25px"></iframe>
+~~~~
+
+Of course the width and height parameters should be scaled to whatever size is required. Multiples of the values given will result in a HD-aspect ratio.
+
+If the youtube-player widget is used for `banner-position: top-fixed`, the site and videos will work as normal. The only problem is that on scrolling the video's may appear to float over the banner (and menubar).

data/pages/contact/contact.md

@@ -0,0 +1,18 @@
+---
+layout: page
+title: Contact
+menuInclude: true
+menuTopTitle: Contact
+menuTopIndex: 99
+excerpt: Contact information for this site.
+tertiary-column: none
+---
+
+This is a placeholder in the theme.
+
+Edit this content in `pages/contact/contact.md`.
+
+But you can contact us at:
+
+- Before the at sign: rien
+- After the at sign: balancingrock.nl

data/pages/cookie-consent/cookie-consent.md

@@ -0,0 +1,7 @@
+---
+layout: default
+title: Cookie policy
+excerpt: Cookie policy information
+---
+
+In compliance with EU law we inform you that this website uses cookies to etc etc.

data/pages/download/download.md

@@ -0,0 +1,10 @@
+---
+layout: page
+title: Download
+menuInclude: yes
+menuLink: yes
+menuTopTitle: Download
+menuTopIndex: 1000
+excerpt: Where to get Classic Jekyll Theme.
+---
+You can get the Classic-Jekyll-Theme at either [rubygems.org](https://rubygems.org/gems/classic-jekyll-theme) or from [github](https://github.com/Balancingrock/classic-jekyll-theme).

data/pages/jekyll/01-jekyll.md

@@ -0,0 +1,42 @@
+---
+layout: page
+title: Jekyll Static Website Generator
+date: 2017-12-20
+menuInclude: yes
+menuTopTitle: Jekyll
+menuTopIndex: 1
+menuSubs:
+- title: Static generator
+  index: 1
+tertiary-column: none
+excerpt: What is Jekyll? Jekyll is a static website generator...
+---
+Back in the early days of the internet websites were just a few files on a computer.
+
+As the web became more widely used, the content became more and more 'dynamic'. This means that two visits to the same site by two different people or at two different times would no longer return the same information.
+
+The information returned depended on the context in which is was requested.
+
+The static pages were replaced by scripting languages and database backends. Needless to say, this increased de complexity of building and maintaining a website. To combat this, many people started to use standard products such as Wordpress.
+
+However as good as Wordpress (and others) might be, they do not simplify the underlying structure. They merely hide it from the site-developper. Add plugins to this, and instability of the platform becomes a real possibility. I know, I lost entire websites -more than once!- because of this.
+
+After the initial embrace of dynamic this and dynamic that, many people started to rediscover the old way of creating websites. Static websites are -as it turns out- more than enough for many small sites or blogs! Certainly with the new wave of "comment" providers like disqus.
+
+Creating a simple website using a comments provider is still a bit of work though.
+
+Enter the static website generator.
+
+Static websites generators take a lot of pain out of traditional web design. And when using a theme (like this!) this becomes even easier.
+
+Creating content is now just a matter of writing the content in a (plain) text editor, then compiling the website and uploading it (or only the changes) to the hosting provider.
+
+Simple, neat.
+
+Jekyll is such a static website generator.
+
+And Classic-Jekyll-Theme is a theme that can be used with Jekyll to create beautiful sites.
+
+For more on Jekyll, see [https://jekyllrb.com](https://jekyllrb.com)
+
+For more on Classic, explore this website!

data/pages/jekyll/02-speed.md

@@ -0,0 +1,88 @@
+---
+layout: page
+title: Compilation Speed
+date: 2017-12-20
+menuInclude: yes
+menuTopTitle: Jekyll
+menuSubs:
+- title: Compilation speed
+  index: 2
+  sub:
+  - title: Jekyll
+    anchorId: jekyll
+    index: 1
+  - title: Classic
+    anchorId: classic
+    index: 2
+tertiary-column: none
+excerpt: Speed hints for Jekyll and Classic
+---
+{:.anchor}
+## Jekyll Speed Hints {#jekyll}
+
+Once the site starts to grow, compilation speed can become an issue. Jekyll is not all that fast, and Classic can slow down things even more.
+
+The main culprit for Classic's performance is the creation of the menubar. More on that below. First some general speed hints about Jekyll.
+
+### Knowledge is power
+
+Turn on the profiler. That shows how much time is spend where.
+
+    bundle exec jekyll serve --profile
+
+will do the trick.
+
+### Exclude content that must not be compiled
+
+In the `_config.yml` exclude the directories that contains stuff that can be copied and stuff that simply does not need to be compiled.
+
+Example:
+
+    keep_files: [assets, icons]
+    exclude: [README.md, raw-material]
+
+Use `keep_files` to simply copy over those files. Use `exclude` to complete ignore the files.
+
+### Incremental build
+
+Jekyll offers an incremental build option. This option does not seem to work pre Jekyll 3.7
+
+    bundle exec jekyll serve --incremental
+    
+Note that the _home_ page is not rebuild when using _incremental_. To see the changes that are made to a post or page, go to that post/page directly.
+
+If you find any strange effects/artefacts, be sure to turn this off first.
+
+### Build only the last post
+
+This helps when writing a new post:
+
+    bundle exec jekyll serve --limit_posts 1
+
+However once the post is ready to be published, it is still necessary to recompile the entire site to ensure that all webpages properly reflect that a new post was added.
+
+{:.anchor}
+## Classic Speed Hints {#classic}
+
+### Use fast-content-build
+
+Setting `fast-content-build` (in _setup.yml_) to _yes_ will disable the creation of the menubar, the vertical menu, categories widget, older-posts widget and the recent-posts widget.
+
+The resulting speed increase is rather large, but of course the created site is not ready for publication. Still it can be advantageous when creating content where the browser window is "reloaded" frequently to view the changes that were made.
+
+To prevent accidentally leaving this setting active, this setting is always disregarded when `jekyll.environment` is set to _production_.
+
+### Use a separate banner-area file
+
+By default the menubar is generated in-line for each page/post. However the menubar generation process is the biggest time consumer when creating a page/post.
+
+It is possible to create the menubar in a separate file and to load that file whenever necessary (using a simple line of Javascript). That increases the speed of compilation but degrades the user experience. The degradation is two fold: the browser must make multiple fetches which will take longer. However that is in our experience not really an issue. The bigger drawback is that the user is no longer given information about which menu item is selected.
+
+With the in-line menubar the menu item for the currently visible page is highlighted.
+
+When the menubar is generated in a separate file this is no longer possible.
+
+If this is no problem, then the menubar (and banner) can be separated by setting the `use-separate-banner-menubar-file` parameter (in _setup.yml_) to 'yes'
+
+Alternatively it is of course also possible to set this parameter to 'yes' during development and to 'no' for deployment.
+

data/pages/jekyll/03-ruby.md

@@ -0,0 +1,19 @@
+---
+layout: page
+title: The Ruby Environment
+date: 2017-12-20
+menuInclude: yes
+menuTopTitle: Jekyll
+menuSubs:
+- title: Ruby environment
+  index: 3
+tertiary-column: none
+excerpt: Ruby and versioning hell
+---
+Versioning is a major headache for people doing more than 1 project. It is not called "Versioning Hell" for nothing.
+
+Ruby is no exception. And using Jekyll for website development may in turn cause problems with other Ruby based projects.
+
+We use [rbenv](https://github.com/rbenv/rbenv) to solve this problem.
+
+With [rbenv](https://github.com/rbenv/rbenv) any Ruby based project can run in its own versioning environment. Recommended!

data/pages/jekyll/04-cron-job.md

@@ -0,0 +1,163 @@
+---
+layout: page
+title: "Cron jobs: create websites periodically"
+date: 2018-02-05
+menuInclude: yes
+menuTopTitle: Jekyll
+menuSubs:
+- title: Create website from git periodically and automatically
+  index: 4
+tertiary-column: none
+excerpt: How to set up the daily creation of a website with jekyll and git...
+---
+When maintaining a website it is common to want to add posts and pages on a regular basis to stimulate regular visits of users. A static website generator makes this harder, but with a little extra effort it is possible to show a new post or page on predefined dates. (Note that the classic-jekyll-theme is needed to have this feature apply to pages as well as posts. Standard Jekyll wil only do dated posts releases)
+
+This is the workflow this example aims for:
+
+- Create a page or post on a local machine.
+- Verify that the layout of the site (on the local machine) is as desired.
+- Check in the changes on the local machine into the local git repository.
+- Push the local git to the git-server.
+
+And have the website on the next day reflect the changes that were made. If changes were made for a future release date, they should only appear on and after the date for which they were written.
+
+## Before we start
+
+The method described here only works if we have control of the server.
+
+It does not work for github hosted sites, though it should be possible to achieve the same result with Github if the cron job does not kick-off the jekyll-build process, but a git-push of an automatically generated file (to github).
+
+The example is given for macOS, but should be easy to replicate for other platforms.
+
+## The setup
+
+The setup is simple: the machine that hosts the website has Jekyll and git-server installed on it. It can be the same machine that is used to create the content, but that is not necessary. One of the side benefits of this approach is that it is easy to update the website from anywhere in the world. Keep in mind though that it is important to use the same version of Jekyll and the ruby environment on all machines.
+
+What we will do:
+
+1. Create a git-server repository on the server that contains the (file for the) website.
+1. Create a git working repository on the server that is used to generate the actual website.
+1. Create a job on the server that checks out the website from the git-server repository into the working repository, compiles the website with Jekyll and then copies the content of `_site` to the website directory used by the server.
+
+And that is all there is to it. Once this is done, we can update the website from any place that has `push` rights to the git-server repository.
+
+To be clear, there are three website directories involved:
+
+1. The server website directory. This is the directory that the webserver uses to serve the incoming HTTP requests.
+1. The git-server website, this is a directory that contains all the files to build the website. It is identical in structure to the directory that is created by `jekyll new`.
+1. And lastly a working directory (with git repository) that is used to create the files to be copied to the server website directory. This directory will be synchronised with the git-server directory when the website files are build.
+
+## The steps
+
+### Create git-server repository
+
+I use macOS Xcode-Server to create a git-server repository.
+
+Start 'Server' and select 'Xcode', then choose the 'Repositories' tab and create the repository.
+
+If you don't have macOS-Server and Xcode-Server installed, please google "git server macOS" for hints about how to setup a git server on the mac.
+
+For this example I will assume a site called 'mysite' and that the git-server repository has the same name.
+
+### Create a directory to use as a working directory for the cron script
+
+Any location will work, this example uses: `/Users/rien/Documents/Websites/mysite`. Of course your user name and site name will be different.
+
+Goto the `/Websites` directory and create the git repository that will be used by the script.
+
+    git clone <<path-to-repo>>
+
+The <<path-to-repo>> should be the path to the git-server repository and end in 'mysite' or 'mysite.git'
+
+This command also creates the directory `/mysite`
+
+### Create the update script
+
+This script is located at the user level (in this case: `Users/rien`) and lets call it `mysite-daily-update.script`.
+
+    #! /bin/bash
+    echo "$(date) start"
+    cd /Users/rien/Documents/Websites/mysite
+    echo "git pull"
+    git pull origin
+    echo "bundle exec jekyll build"
+    rm Gemfile.lock
+    JEKYLL_ENV=production /Users/rien/.rbenv/shims/bundle exec jekyll build
+    echo "sync site"
+    rsync -av _site/ /Library/Server/Web/Data/Sites/mysite
+    echo "$(date) ready"
+
+What happens:
+
+- The bash shell is used
+- The start time is logged to a console
+- The working directory is changed to the directory where the cloned repository is
+- The working repository is updated from the main site repository
+- The Gemfile.lock is removed (I believe this is not really necessary, a leftover from experimenting)
+- Jekyll compiles the site (the full path to `bundle` must be specified because the regular login profile is not executed in a cron job)
+- The site is copied to the directory where the server expects it.
+- The end time is logged to a console
+
+The path in the `rsync` command must of course be the path to the directory where the website is hosted.
+
+Note that when the website is being used the users may experience an inconsistent website for a very short time. For the type of updates that are targeted with this approach (page & post updates) this should not pose a problem. But when a website is completely redesigned it may be unacceptable. In that case a proper shutdown of the server is necessary before the rsync command is issued and a restart of the server afterwards.
+
+Important: Make the script executable!
+
+    chmod +x mysite-daily-update.script`
+
+### Create the cron job specification
+
+In the directory `~/Library/LaunchAgents` create a file with the name `com.mysite.plist`. Of course a different reverse-url notation will be needed for a different site.
+
+This file should contain the following:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.mysite.daily-update</string>
+    <key>StandardOutPath</key>
+    <string>/Users/rien/mysite-daily-update.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/rien/mysite-daily-update.error.log</string>
+    <key>Program</key>
+    <string>/Users/rien/mysite-daily-update.script</string>
+    <key>StartCalendarInterval</key>
+    <dict>
+        <key>Hour</key>
+        <integer>00</integer>
+        <key>Minute</key>
+        <integer>01</integer>
+    </dict>
+</dict>
+</plist>
+```
+
+One thing to notice is that this specification also tells the OS to create an error and a log file. These files are written to the users root directory and can be examined for error messages.
+
+The `Hour` and `Minute` keys and their values specify the time when the script should be executed. Take note of this because when you are in the habit of switching off the server at certain times, this may result in missing the site-generation for that day.
+
+Btw, a good resource for the capabilities and configuration of the launchd can be found at: [http://www.launchd.info](http://www.launchd.info).
+
+### Load the cron job (manually)
+
+The job will be loaded automatically at startup. But right now you will need to load the job by hand:
+
+    launchctl load ~/Library/LaunchAgents/com.mysite.plist
+
+Most likely you will also want to test the script, that can be done with:
+
+    launchctl start com.mysite.daily-update
+
+The first couple of times, make sure to check for an error log in the `StandardErrorPath`. (Which in this example is the user home directory)
+
+For completion, there are also the `unload` and `stop` options for `launchctl`. Only when the plist file is changed does one need to unload it.
+
+## In closing
+
+With the above information it should be possible to set up a daily re-generation of the site, and to automatically upload it to the appropriate server directory.
+
+If a dedicated server is used and the git-server directory is accessable from outside, this is also a very convenient method to create pages and posts from outside your local domain. I.e. when travelling. It is even possible to use this to contribute to the site by multiple authors.