Jekyll DTF Basic Theme Documentation

Contents:

• Installation
• General Usage
  • Navigation
  • Layouts
  • Responsive Image Generation
  • Pagination
  • Github Pages
  • Other configuration options
  • Dark Mode and Cookies
• Using the Design Tags
  • The Feature Design Elements
  • The Project Feature Tag
  • The Post Feature Tag

For Theme developers, have a look at the DTF plugin TODO.

Installation

Add this line to your Jekyll site’s Gemfile:

gem "jekyll-theme-dtf-basic"

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

theme: jekyll-theme-dtf-basic

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-theme-dtf-basic

General Usage

Navigation

Put the main navigation under _data/navigation.yml, e.g.:

- title: Home
  url: /

Layouts

Available Layouts:

• page: A minimalistic page
• post: The page extended with general post styling, e.g., displaying the title, date, image, etc.

Responsive Image Generation

Will use imagemagick for responsive images, put these images under assets/img. The {% picture_element %} will load pictures based on the device width.

Pagination

The theme uses octopress-paginate (see USAGE)to allow for pagination of collections. To introduce a paginated site configure it in the front yaml of a page, e.g.:

paginate:
    collection: projects

Github Pages

This theme requires several Gems not whitelisted by Github Pages. You can use an Action like jekyll-build-pages instead.

Other configuration options

Useful configuration options:

lang: en

# brand_icon is used as favicon if generate_favicon == false
# default brand text is the title
brand:
  image: "assets/dtf_brand.svg"
  brand_icon:
  text:

# If you have multiple authors you can display them on projects/posts/etc.
show_authors: true

# Display the top 5 related posts
show_related_posts: true

# Activate optional dark mode, currently only "auto" is working
dark_mode: "auto"

# A Text prepended to the footer
footer: "© Markus Sosnowski"

# Generate Favicons from the brand.image
generate_favicon: true

# Generate collections from folders, like _projects
collections:
  projects:
    output: true

Dark Mode and Cookies

The theme uses cookies to save the preference for the dark mode. It should be fine to not have a cookie banner for these cookies, as they contain no personal data and are required for the function of the website, however, I am not a legal advisor and cannot guarantee anything. If you have doubts, deactivate the dark-mode.

Using the Design Tags

The concept is simple, the theme provides design_elements that can be used in the different pages. A design_element is usually grouped in a design_group. For example,

{% design_group title="My Group" %}
{% design_element title="Element 1" %}
{% enddesign_group %}

Instead of setting each argument as parameters, we can instead give a variable. For instance, we might to display elements of a collection or our posts, a quick and easy way to display this would be:

{% design_group title="My Group" %}
{% for post in site.posts %}
{% design_element post %}
{% endfor %}
{% enddesign_group %}

The DTF comes with several pre-defined tags that can be directly used, these are inspired by common design elements found on different Jekyll websites. The logic is almost the same, but the theme can display them differently. The parameter values are theme specific.

For example, the following code would not work and produce an error!

{% design_group title="My Group" %}
    {% for post in site.posts %}
        {% design_element post %}
    {% endfor %}
{% enddesign_group %}

The Feature Design Elements

display features with straightforward liquid tags, e.g.,

{% feature_group title="Our Features" %}

{% feature_element title="Intuitive Elements" icon-class="fa-solid fa-check" description="Description" %}
{% feature_element title="Good Design" icon-class="fa-solid fa-check" description="Description" %}
{% feature_element title="Documentation" icon-class="fa-solid fa-book" description="It even has a Documentation" url="/documentation" %}
{% feature_element title="Another Feature" icon-class="fa-solid fa-check" description="Description" %}
{% feature_element title="Another Feature" icon-class="fa-solid fa-check" description="Description" %}
{% feature_element title="Another Feature" icon-class="fa-solid fa-check" description="Description" %}

{% endfeature_group %}

will produce a grid like this

If you have a page for every feature, you could create a collection and loop over that, just like the projects in the next example.

The Project Feature Tag

To display a collection of projects you can use this:

{% project_group title = "Latest Projects" link = "/projects" %}
{% for project in site.projects limit: 5 %}
{% project_element project %}
{% endfor %}
{% endproject_group %}

This would result in cards like this:

Latest Projects

Project 1

Markus Sosnowski

A nice project description

More

Project 2

Markus Sosnowski

A much nicer project description

More

View all

The Post Feature Tag

To display a the latest 5 posts you can use this:

{% post_group title = "Latest Posts" link = "/posts" %}
{% for post in site.posts limit: 5 %}
{% post_element post %}
{% endfor %}
{% endpost_group %}

For this theme, this would look like this:

Latest Posts View all

01 January 2025

Another Testpost

Example Blogpost that shows how to hide the main image.

Read

30 December 2024

Testpost

A Post Showcasing the theme

Read

Author Logic

Each post should have an author. This theme uses the logic of the Jekyll SEO Tag, which means:

1. The author is defined in page.author, if empty site.author is used.
2. If the author is a YAML object, it is directly used, if it is a string, the corresponding entry in _data/authors.yml is loaded.

The logic is used by several elements, like the author_element:

{% author_element %}

which will render as:

Markus Sosnowski Jekyll Theme Designer