Quicktstart for testing

  • Clone the repository

  • Run bundle exec jekyll serve --config _config.yml,_data.yml

  • Open http://127.0.0.1:4000/ to view a page using this theme

Installation

Add this line to your Jekyll site’s Gemfile:

gem "jekyll-theme-endless"

And add this line to your Jekyll site’s _config.yml:

theme: jekyll-theme-endless

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-theme-endless

General information

The theme is styled using Bootstrap that is added via a content delivery network (CDN; here: https://www.jsdelivr.com/).

The output of page variables (e.g. page.title or page.menu_label) is not escaped by the theme-layout. The reason is, that Jekyll-AsciiDoc (in contrast to Markdown) escapes HTML by default. Thus, using (unescaped) HTML-commands e.g. in titles of Markdown posts/pages might break the layout. If you want to use Markdown AND have HTML-commands in the title, simply escape them (e.g. use < instead of <).

Usage

Here I describe available layouts, includes, sass and/or assets here.

Layouts

_layouts/html.html

HTML boilerplate code used for all layouts.

_layouts/default.html

Default website structure (menue, tag cloud, …​) used for pages and posts.

Contains a navigation bar with a configurable brand-label. Set brand in your _config.yml, to determine what is shown on the left side of the navigation. Example:

brand: '"<i>endless</i>"-Theme'

Contains a configurable title bar. Set title and subtitle in your _config.yml, to determine what is shown below the navigation bar. If none of the two values is set, the title bar is omitted. Example:

title: 'Brandname'
subtitle: 'Vision statement'

Contains a configurable footer. Includes content_footer-usernames.html to generate a list of contact options. Configure values in _config.yml. Example:

author: Sven Boekhoff
copydate: 2020
disclaimer: >- # this means to ignore newlines until the next entry
  I'm creating this Jekyll theme because I want to use it myself.
  Therefore, many things (e.g. the support of AsciiDoc) are based on personal requirements.
  You are welcome to use the theme (at your own risk) and contribute to the development.
_layouts/page.html

Layout of page-content.

Start a new page in AsciiDoc by adding a file ending with .adoc. Do not forget the page--prefix when setting page variables. Jekyll-AsciiDoc has an auto-detection mechanism for the layout. Thus, you typically do not have to set the layout to page or post.

= Page title
:page-layout: page

Content.

Start a new page in Markdown by adding a file ending with .md.

---
layout: page
# Use either a `# Heading` OR set the title in the frontmatter.
# Using both will result in two headings.
---
# Page title

Content
_layouts/page-postlist.html

Layout of page-content with a list of blog posts at the end.

_layouts/page-tag.html

Layout of pages containing a list of those posts being tagged with a given tag. This file is required by the generate-tagpages-plugin.

_layouts/post.html

Layout of blog-posts.

Start a new post in AsciiDoc by adding a file ending with .adoc to the _posts/-folder. Do not forget the page--prefix when setting page variables. Jekyll-AsciiDoc has an auto-detection mechanism for the layout. Thus, you typically do not have to set the layout to page or post.

= Page title
:page-layout: post

Content.

Start a new post in Markdown by adding a file ending with .md.

---
layout: post
# If the title of the post should be different from parts of the filename,
# change it using the title variable.
# Using a `# Heading` will result in two headings in the post.
title: Page title
---

Content

Includes

_includes/function_list-pages.html

Generates the code containing links to each page. The text of the link is the title of the page.

If the text should be different from the page-title, set the page variable menu_label. In AsciiDoc files this could be e.g.: :page-menu_label: 'AnotherText'.

The order of the links can be determined with the help of the page variable menu_label (in AsciiDoc e.g. :page-menu_position: 100; in frontmatter e.g. menu_position: 50). Pages with higher numbers appear on the left side of the menu. Pages with a negative value for menu_label will be hidden from the menu. This can be useful for your 404 page, which should be generated by Jekyll, but not visible in the menu.

_includes/function_list-posts.html

Generates the code containing links to each blog-post. The text of the link is the title of the post.

_includes/function_tag-cloud.html

Generates a tag cloud.

_includes/content_footer-usernames.html

Creates a list of contact options based on provided usernames and addresses. The entries are preceded with the icons of (e.g.) the social network and are linked to the corresponding profile.

In your _config.yml use for example:

email: [email protected]
username_gitlab: XXXX
username_github: XXXX
username_xing: XXXX
username_linkedin: XXXX

Plugins

_plugins/generate-tagpages.rb

Generates a page for each tag listed in site.tags. The files created are by default named tags/<tagname>/index.html. The content is generated using the layout file _layouts/page-tag.html

The following values can be set in _config.yml:

# Settings for tag cloud:
# The name of the directory in which the files for each tag are created
# default: `tags`
tag_dir: post-for-tag
# Prefix to be used for the title of the tag-page
# default: `Tag: `
tag_title_prefix: "Posts tagged with: "

Styles

In order to contribute SCSS-code, simply add a file _sass/user.scss, containing your SCCS-code. This file is included by assets/css/main.scss.

Settings

Language

The language of the content can be set using page.lang which overrides site.lang. The default is en.

  • use e.g. :page-lang: en in AsciiDoc

  • use e.g. lang: en in frontmatter

  • use e.g. lang: en in _config.yml

Contributing

Bug reports and pull requests are welcome on GitHub at https://gitlab.com/jekyll-theme-endless/jekyll-theme-endless.gitlab.io. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Development

To set up your environment to develop this theme:

  1. clone this repository

  2. run bundle install

The theme is setup just like a normal Jekyll site! To test the theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. To test the theme with example-data, run bundle exec jekyll serve --config _config.yml,_data.yml. Values for theme specific configurations are stored in _data.yml and not in the themes _config.yml. Since the _config.yml is shipped with the gem, the users of your theme would otherwise have to unset the values in their own config.yml.

Add pages, documents, data, etc. like normal to test your theme’s contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When your theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in jekyll-theme-endless.gemspec accordingly.

License

The theme is available as open source under the terms of the MIT License.