|Created:||11:42 on Tuesday, 12. September 2017|
|Modified:||10:14 on Wednesday, 17. November 2021|
|Keywords:||help, site, docs|
More or less internal document describing the Jekyll-based framwork this site is based upon. Usage instructions for all the macros and includes, known and supported frontmatter variables and more.
The following is meant to be a cheat sheet for the site owner. It documents various template fragments (includes) and outlines conventions that are valid site-wide.
The theme should be compatible with all modern browsers that are not older than about 2 years, including Firefox, Opera, all Chromium-derived browser, Internet Explorer 11, Edge, Safari and basically all modern mobile browsers. It does use CSS3 features and things like hyphenation, sticky positions and advanced font rendering properties, but these are optional. The site does not depend on such features.
all file names should be all-lowercase. This applies to template fragment in
_includesas well as for all kind of embed able content (images, style sheets, scripts).
The template includes for embedding images assume that all media resides below
assets/gfx. File names must be relative to this location, file names, including sub-folders and extensions, should be all-lowercase. It is possible, though not recommended, to specify the prefix explicitly as a parameter for
menu templates for entire menu systems are expected in
site_headertemplate expects the parameter as base name only, without the .HTML extension and the path prefix.
menu templates for (optional) pull down menus must be in
_includes/menus/custom. Other than that, all the rules listed for menu systems apply here. The custom menu name must be passed to the site header template as
custom_menuparameter, but may be an empty string in which case no optional menu will be rendered.
Most posts, articles and automated lists (tags, categories) use the
pretty scheme with the
document, category or tag name as a sub folder and the document itself using
exception of this rule are site documents like
/help/contact.html for example.
The site is designed both protocol- and base path agnostic. The variable is always used, so it should be easy to transfer the entire site to a prefixed url (e.g. http://mysite.foo/ to http://mysite.foo/blog/).
Collection and category root folders must have a
sbar.html document with front matter. This will
define the dynamically retrieved (via ajax requests) side bar when using the modern layout without a
static side bar. Consequently, it should list related documents in the same category / collection.
The implementation simply includes
respectively, passing the category or topic name as parameter.
Frontmatter variables for posts and articles
The following variables are supported
first- This is mandatory and must be set as a TAG for all posts and pages that should appear in listings and indexes. Basically, every page should have this tag unless it’s either hidden or a followup page that should not appear in listings or indexes.
disqus- Set to 1 if disqus should be embedded for the article/post.
share- Set to 1 if a share bar should appear below the content.
menucontext- which entry of the menu bar should be highlighted. Can be
home, about, contact, blog, topics or got. Defaults to ‘blog’.
share_url- will be used instead of
page.urlwhen present. Useful for followup pages when the first page should be the target to share.
reduced- if present, the content will be wrapped in a
DIVelement using the CSS classes
reduced foowhere foo is the value of the variable in the front matter.
reduced: bigwill result in the content being wrapped in a
<div class="reduced big">. The CSS definitions should be in
content.css. It’s useful to wrap the content in DIVs for adding margins and padding to reduce the maximum text width for better readability.
wrapperclass- CSS class(es) added to the
#content-wrapperDIV element. Can be useful to set custom backgrounds.
header- Custom header block. Default is
headers/default.html. The name must be given without path and extension, so
header: foowill include
headers/foo.htmlas the header block. Note that this is only the top header bar without the menu, but including the site title and contact button bar.
menu- The menu to use. Menus reside in
_include/menus/and must be specified without extension. Same as for
footerclass- The CSS class for the footer wrapper element.
footercontent- The footer to use for this page. Footers reside under `_include/footers/’.
style- a multiline string containing CSS definitions. These will be wrapped with style tags and embedded into the header.
styleinclude- a list of base filenames relative to _includes/css that will be part of the header. Example:
styleinclude: [1,2]will include
_include/css/2.css. Must contain valid CSS classes, no style tags.
permalink- The final link for this document. If specified, posts will not follow the default URL scheme
YYYY-MM-DD/document_namebut use the permalink instead.
modified- mandatory time stamp of last modification. Can be the same as
date. This is always used to sort lists and indexes, so it’s required. Always. Format must be ISO.
date- date of first publishing. Mandatory for all content without the date specified in the file name, so basically for everything except blog posts. Must be in ISO format.
The main includes for embedding images are
gfx/FD.html (for floating images aligned to the left or
gfx/BD.html for block images taking usually the full width. The includes accept the
image: A data element, either in
site.dataor in the page itself. The element is required to have the following fields:
name:The name of the image, without path name but including its extension. Case sensitive on some systems.
path:The path relative to the base, which is
assets/gfxunless otherwise specified (see below). Must end with a / character.
desc:A short description that will appear below the image and as ALT text.
long:Optional - when present, a info symbol will be overlaid over the image. Hovering it will reveal a tool tip with the long description. This can be markdown text and will be fed through the
url:For linked images, the URL of the image. When present,
pathwill be ignored.
thumb:For local images only (does not work for linked images using
url). When set to 1, a thumbnail version of the image is expected to exist in the same folder, prefixed with
alignThe alignment, either left or right. Only for
widthThe width of the image, including the unit. Example: “250px” or “50%”.
prefixThe file system prefix when the default (assets/gfx) should not be used for whatever reason.
nolinkCan be set to 1, if the embedded image should not link to the full size version. This will disable the fancybox link, so the image won’t be view-able in full size.
omitbottomcaptionDo not show the caption below the image. It will still be set as ALT text.