User Manual for v1.9.2
Welcome to Classic-Jekyll-Theme. This theme centers around one of the most used website structures on the web. A banner, navigation menu (dropdown), (up to) three columns and a footer. The design is fully responsive for three different screen widths: wide, medium and narrow. It is probably best shown in an example:
The columns are called Primary (blue), Secondary (grey) and Tertiary (pink). In the above layouts the secondary column is on the left side. If it had been on the right side, the medium layout would have looked like this:
The menu bar (in yellow) is always deployed in the wide layout. In the medium and narrow layout the menu bar is shown in the deployed state. When not deployed, a menu-item symbol is shown in the banner that switches the menu between deployed and not.
An example screenshot:
Secondary and Tertiary Columns can be specified by default and on a page by page basis for presence, location and content.
Navigation bar with drop-down menu is created automatically from the available pages when these have the proper YAML frontmatter. The navigation bar contains the top level menu items, while the submenu items show up as a drop-down menu when the cursor hovers over the corresponding menu item.
Category pages are created semi-automatically; the web designer has to identify the categories for inclusion, but the menu entry and category pages are created automatically.
Cookies policy for european users is included by default. It can be easily disabled for non-european websites though.
Language customization (not multi-language support!).
Icon support for an icon in the upper left corner of the site.
Background images and Background color settings for major site elements.
- Widgets the following widgets are included:
- recent-posts: Shows a list of the N most recent posts (N is configurable).
- social-media: Shows a list of social media sites with their links (Edit to add).
- subscribe: Shows how a visitor can subscribe to your site (Edit to add).
- youtube-player: Shows a youtube player that scales with the column it is used in (video id parameter).
Normalize.css As of release 1.5.0
normalize.cssis used directly instead of through the Jekyll adaptation. This allows for faster upgrade cycles.
Excerpt on pages Pages defining an explicit “excerpt” in their YAML will use this as the description for the header description meta tag (necessary for SEO purposes). Note that Jekyll does not generate excerpt information for pages, only posts. Hence it is necessary to define the excerpt as a YAML tag.
Blocked layout support Styles and includes support the creation of blocked layout (like product pages). To see an example of blocked pages, see the http://balancingrock.nl home page.
Enable/disable banner The banner at the top of the page can be disabled.
Move banner/menu to main column The banner & navigation can be moved to within the main column only. The secondary and tertiary columns will then run right up to the top of the screen.
- Split files for the menus It is possible to generate the menu file separate from the content file. While this may slow down the loading of the site a little, it is a huge speed up for site generation under Jekyll.
Like to help out?
You can support further development of this theme, or just say ‘thank you’ via paypal by donating to email@example.com or wire bitcoins to address: 1GacSREBxPy1yskLMc9de2nofNv2SNdwqH
Suggested donation for personal websites is the price of a good cup of coffee: $4
Suggested donation for commercial sites is the price of a good meal: $20
Installation & setup
On MacOS the gems are located in:
Library/Ruby/Gems/<version>/gems/classic-jekyll-theme-<version>. Replace the versions with the appropriate numbers (note: these are two different unrelated version numbers). These pages not only contain examples, but also some information about using the theme. Some of the steps below need the path to the gem, so make sure you know it (do ‘bundle show classic-jekyll-theme’).
Install the theme:
$ sudo gem install classic-jekyll-theme
Create a new project:
$ jekyll new great-site
Goto to the directory:
$ cd great-site
Change in the Gemfile:
From `gem "minima", "~> 2.0"` to `gem "classic-jekyll-theme"`
Change in the
From `theme: minima` to `theme: classic-jekyll-theme` Add `jekyll-data` to the gems.
Delete the file
$ rm about.md
It is possible to start the jekyll server now:
$ bundle exec jekyll serve
Then the site will show up at
To add sample content that illustrates how pages and categories are implemented, copy the folder
pages from the gem to the current project. To use the ‘separate navbanner file’ feature, also copy the
navbanner.md from the gem to the project.
The theme is configured in:
_sass/classic-jekyll-theme.scss: For the graphical elements.
_data/setup.yml: For general layout and widget configuration.
_data/text-for.yml: For language customization of the textual elements of the theme.
If it is necessary to change any of these settings, copy the file to your site (keeping the folder structure) and modify them as necessary.
main.scss file has been emptied. Hence all CSS configuration is done in the theme sass file.
The following values are configurable:
Controls the default placing of the secondary column on either the
noneat all. Note that the YAML front matter variable
secondary-columncan be used to override this value on a per-page basis.
When the secondary column is present its contents is taken from the file:
_includes/secondary-column.html. Note that this can be overriden by the YAML front matter variable
Controls the default presence of the tertiary column, either
none. Note that the YAML front matter variable
tertiary-columncan be used to override this value on a per-page basis.
When the tertiary column is present its contents is taken from the file:
_includes/tertiary-column.html. Note that this can be overriden by the YAML front matter variable
By default set to 5, thus 5 posts will be shown in full on the home page.
The number of posts (titles) that will appear in the “Recent” widget.
yesto enable the cookies warning,
noto disable. The cookies warning is from Silktide, distributed under the MIT license.
top: The navigation banner will be placed over the entire site (all columns)
main: The navigation banner will be placed at the top of the main column. Possibly next to or in between the secondary and tertiary columns.
yes: Use a separate file for the navigation banner. This may cause a slight performance hit for browsers, but is a huge performance enhancement for the site generation process. Note that this option necessitates a JQuery library. By default the google JQuery library is loaded. Update the
_includes/head.htmlif a different JQuery library should be used or if the library should be upgraded.
no: Generate the navigation banner in-line into the posts and pages.
Some of the text elements in the theme can be translated with the following definitions:
Typically you will need to copy some files from the gem itself to the project (web site) directory. The most common files are:
_sass/classic/_normalize-override.scssif site wide updates must be made to
_includes/secondary-column.htmlfor the secondary column contents.
_includes/tertiary-column.htmlfor the tertiary column contents.
navbanner.mdfor the navigation bar menu. This is mandatory if the
useSeparateNavBannersetting is used, optional when not. Hence its easier to always copy this file.
These files can be found in the gem directory. Try the command
bundle show classic-jekyll-theme to see where the theme is located. When you copy these files, make sure they are in the same relative directory as in the gem itself.
Besides the above mentioned files you should avoid making changes to the files provided in the gem. The more changes you make, the more difficult it will become to upgrade. Instead of changing a file, include a new file that contains the stuff you want and include that file.
For example, if you need to add to the SASS files, create a new file and include that at the end of
Posting is done exactly like in the standard Jekyll environment.
Creating a Category Page
A category page is a page that contains links to all posts published in that category.
To kick-off the creation of a category page, create a new page and include the following front matter:
--- layout: category-page title: classic ---
The rest of the page can remain empty, it will be automatically created. The category-page triggers the generation of a category page. The title is the category the page is created for. The category (and thus also the title) are case sensitive.
Creating Pages for the menu bar
To create a page that must be included in the menu bar, add the following front matter to that page:
--- ... menuInclude: yes menuLink: yes menuTopTitle: Classic menuTopIndex: 2 menuSubTitle: "About Pages" menuSubIndex: 4 ---
- menuInclude: Set to “yes” to consider this page for a navigation bar menu item.
- menuLink: Set to ‘no’ to disable a link creation from the navigation bar to this page. However the menu title or subtitle will be included. This allows the ordering of menu items that do not have an associated page. The default behaviour assumes ‘yes’. So not including this tag will create a link. Note: This allows ordering of top level menu items. For submenu items this probably only makes sense if some kind of “divider” must be shown. Otherwise showing a submenu item without a link will probably confuse users.
- menuTopTitle: The title of the menu item in the navigation bar. When used in conjunction with a menuSubTitle, this will be the title of the menu item to which this submenu item will be added in the drop down menu.
- menuTopIndex: The place of the title within the menu bar. Lower numbers will be to the left of higher numbers. Be aware that the “Home” menu item will always be first and the “Categories” will always be last.
- menuSubTitle: The title of the submenu item in the drop down menu.
- menuSubIndex: The place of the submenu item within the dropdown menu. Lower numbers will go above higher numbers. This theme only sorts on menuIndex numbers, not on other properties.
For a consistent user experience in the narrow layout, it is recommended not to link pages to top level menu items if these menu items have a drop-down submenu.
Creating pages with custom second and tertiary columns
There are 4 YAML tags that control the custom placement and content of the secondary and tertiary columns:
--- ... secondary-column: <'left'|'right'|'none'> secondary-column-content: <include-file> tertiary-column: <'present'|'none'> tertiary-column-content: <include-file> ---
These YAML variables can be used to override the default settings and provide custom content for the columns.
Notice that these settings take effect by their presence. Example: if a
secondary-column YAML variable is present, it will prevent the global setting in the
_data/setup.yml from having any effect.
Specifying html header description meta tag content for pages
The “description” meta tag is possibly the most important SEO information that we can put in our pages. It shows up as the “description” for a link in search engines. Jekyll does support this as the “excerpt” tag in YAML front matter. And if the “excerpt” is not defined, Jekyll will grab the first part of the post as its description. However, for pages there was no such support. As of verion 1.5.2 this theme adds a limited form of this support. If a page defines an excerpt in its YAML front matter, that excerpt information will be used as the information in a description meta tag.
--- ... excerpt: "Up to 160 characters can be used to provide a text for the description meta tag" ---
Note that the “excerpt_separator” does not work on pages, only posts.
Editing the secondary and tertiary columns
The prime column is populated by the ‘normal’ pages and posts. The secondary and tertiary columns have a fixed content that is created by directly editing the
_include/tertiary-column.html. These files must be copied from the gem dictionary to the directory with the jekyll files for the website at the path
Documentation for the widgets is included in the widget files themselves. The are located in the gem directory at
- Allow banner area to be removed.
- Allow banner & menu area to be placed at the top of the main column only.
- Added controls for setting the top and bottom free room of the column dividers.
- Bugfix: sites not hosted at the domain root would have the wrong ‘home’ link.
- Quickfix for screwup in 1.8.1
- Bugfix: corrected a liquid error in
- Bugfix: Fixed the sometimes horizontal scrollbar bug
- Feature: Added option to generate a separately loaded navbanner file.
- Bugfix: Added navbanner.md to the gemspec (file was missing)
- Bugfix: David Crossley fixed a bug where the filename of the column content was not properly used.
- Removed pre v1.8.0 notes and update instructions to shorten the readme.
from 1.8.0 to 1.8.1
- The file
from 1.8.0 to 1.8.2
- The file
from 1.8.2 to 1.8.3
- The file
_layouts/default.htmlwas changed (3rd line)
from 1.8.3 to 1.8.4
- The configuration file
_config.ymlupdated to Jekyll 3.5 standard
- Updated the file
_layouts/default.htmlagain (3rd line)
from 1.8.4 to 1.9.0
- The setup file in
_data/setup.yml(added option to enable/disable separate navbanner file generation)
- The following files have been updated or added:
_data/setup.yml _includes/head.html _includes/navbanner.html _layouts/default.html _layouts/navbanner-layout.html _sass/classic/_formatting.scss navbanner.md
- To use the separate navbanner file, copy the “navbanner.md” file from the theme folder to the project folder (at the same relative level)
from 1.9.0 to 1.9.1
No changes needed.
from 1.9.1 to 1.9.2
_layouts/default.html was updated.
Comments, bug reports, feature requests and improvements are eagerly anticipated via email: firstname.lastname@example.org or via github.
The theme is available as open source under the terms of the MIT License.