What it is

OneFlow is a Jekyll Theme designed to create stunning, clear and practical modern One-Pager Websites. It offers lots of features and customization options, so you can easily create a Site that matches your own or your client's wishes for design and structure.

It offers various customization options, like a sticky or non-sticky navigation bar and several diverse color skins. Furthermore, OneFlow comes with lots of build-in utilities like buttons, boxes, notices, galleries, round-images and image-text-rows. You can apply sections with alternating background color and can fuss-freely use a background image.

It is straightforward and easy to use. You just need to clone the GitHub Repository and can get started straightaway.

Table of Contents

Getting started & development

Fork and clone the repository

The vision of this theme is simplicity and accessibility, to easily create stunning websites from scratch. Therefore, it's not available as a classic gem-based Jekyll theme, but as a ready-to-use GitHub repository that you just need to fork and clone. So, get ahead and make a fork of this repository, rename it if you like to suit the name of the site you want to create, locally clone it, and directly start editing!

How to start a development docker container

To test your website and see all of your changes in real-time without deploying it online, you can easily build your site locally. OneFlow comes with build-in docker configuration using BretFisher's jekyll serve.
  • Make sure you have Bundler and Docker installed
  • Open up a terminal, navigate to your local repository, and run docker compose up.
Your site will then be visible at http://0.0.0.0:4000/ in any browser.

Markdown and HTML

Use raw and flexible HTML or clear markdown to write your content. Markdown is rendered with kramdown, which supports applying css classes to the Markdown. That means, you can add notices, boxes and other utilities even to your Markdown content, as simple as "Text you want to add the classes to {: .class1 .class2}". This documentation will show everything in HTML, but as shown in the lines above, applying css classes is also easily possible with Markdown.

Responsive Design

All of OneFlows features are 100% responsive and adapt to different screen sizes, so your site looks good on all devices!

License & Credits

License

OneFlow is Open-Source and licensed under the MIT License. That means, you can freely copy, use and customize it - whatever you like! You do not need to give credits to me (the creator), but of course I'm happy if you do. But don't feel obliged to do so.

Credits

OneFlow is based on the Minimal Mistakes Theme. Minimal Mistakes has been used as a starting point for OneFlow. Credits to it's creator, Michael Rose, for the awesome and versatile theme he created!

Start editing your Site

The main parts you want to edit are:
  • README.md for the readme of your repository,
  • /_data/navigation.yml for the navigation links,
  • /_pages/index.html for your main content,
  • /_pages/imprint.html for the imprint & privacy note,
  • _config.yml for the basic setup of your site,
  • /assets/images for all images and graphics you use on your site,
  • /assets/css/custom-styles.css if you want to add custom css styles,
  • /assets/fonts if you want to add custom fonts and
  • /_includes/editables if you create a website for a client who regularly wants to change parts of the site him/herself.

Color skins

OneFlow comes with 10 diverse color skins you can easily apply. These are: default, air, aqua, contrast, dark, dirt, neon, mint, plum and sunrise. Check the Minimal Mistakes documentation about color skins for example images. Define your preferred skin by changing the value of oneflow-skin in _config.yml..

Masthead

The Masthead, including the navigation bar, offers a few customization options. All of this configuration can be done in config.yml.

First, you can decide whether you like it to be sticky, meaning it will stay visible on top of the page even when you scroll down, or not. To make the masthead sticky, set sticky-masthead: true.

You can furthermore easily set the opacity of the masthead with masthead-opacity: xxx, where xxx is a number between 0 and 1. A good starting point that works good for most sites is 0.8 to 0.9.

The masthead can either contain a logo (or any other image), or your site title and optionally a sub-title. If you want to display your logo / image there, set logo: /assets/images/logo.webp or the respective path to the image and filetype you want to use. If you don't want your logo / image there, remove the logo path or out-comment it by setting # behind the : like so: logo: #/assets/.... By default, the site title, which is also shown in the browser tab, is then displayed instead of the logo. You can set the title by setting title: "your-website-title". Set the subtitle with subtitle: "your-subtitle" or set this to "" to have no subtitle. If you want to display a different title than your default site title in the masthead, you can set this with masthead_title: "your-masthead-title". Set this to "" to display no title. To edit the links in the navigation bar, head over to /_data/navigation.yml. Unter the main-variable, you can set the title and url each nav link should point to. For linking to a section on the main page, include a "#" before the id, and set the id-attribute within the section-tag or the header-tag of that section. For external links, you can set blank to true, so the page opens in a new tab, and as URL include the full url with https:// at the beginning.

Background

As the background for your site, you can either stick with the background colors that come with your chosen color skin, or you can apply a background image instead. Background image settings are all done in config.yml. Set background-image: "/path/to/your/background-image.webp". To have no background-image, remove or out-comment this line. When working with a background image, it is strongly recommended to use a horizontal background image for the desktop version of your site and an upright image for the mobile version. You can easily do this, by using a horizontal image for background-image, and setting a different image (or different version of the same image) for background-image-mobile. Furthermore, it is also strongly recommended to apply a slightly transparent overlay to the background image, for better readability of all texts on your site. You can set this by setting background-image-overlay : rgba(255, 255, 255, 0.5) or any other rgba color value you like. As some countries, like Germany, require information and consent about cookie-usage and the usage of a CDN for example for deploying sites on GitHub pages, OneFlow comes with a build-in Popup for that purpose. You can enable or disable the Popup in config.yml with true/false for show-popup. Do not use quotation marks for setting true/false values in the configuration file.

The existing version of the popup is a suggestion and should (no legal advice given) fulfill german laws regarding cookie and cdn-usage consent.

To edit the content of the popup, navigate to /_includes/popup.html and edit its HTML. This file also contains a script-tag with the javascript for the popup. This script sets a cookie for one day, when the user clicks on the "Agree"-button, so the popup is not displayed on every page reload, but only after one day. Edit the line expiresDate.setDate(expiresDate.getDate() + 1); to set this to a different time interval.

Content & Basic home page setup

To start adding content to your main page, navigate to /_pages/index.html. Remove the example content, and start adding your own!

First, you need to set some basics in the YAML front matter. So, start with:
---
layout: page
title: "The Title That Should Display In Your Page Hero"
excerpt: "The Sub-Title Below Your Main Title"
permalink: /
---

You can furthermore customize the Page Hero, which is the first thing catching the visitors eyes! The Page Hero can include:
  • A title
  • A subtitle
  • An image
  • An image overlay
  • A caption
  • Action buttons
Set and customize them like so:
  header:
    overlay_image: /assets/images/header.webp
    overlay_filter: rgba(0, 0, 0, 0.6)
    caption: "Photo by **[Text](Link)**"
    actions:
      - label: "Get Started"
        url: "https://url-to-link-to.com"
        blank: true

Captions and labels support Markdown. You can add as many action buttons as you like. The have a label, a URL and a "blank"-characteristic. Blank is either true or false and determines, whether the link opens up in a new tab or not. If this is true, the HTML a-tag contains target="_blank" as well as rel="noopener noreferrer nofollow", which is important so that opening link in a new tab doesn't come with security and SEO impairments.

Remember that indentation is important for the YAML front matter.

Sections

OneFlow offers alternating colored sections.

If you do not want alternating colors, there is no need to apply any section tags, just write all of your content outside of any section tags. To separate different parts of your page, you can drop in a nicely styled big separation line easily with
<hr class="section-sep">. You can use this both with and without alternating colored sections.

To apply alternating colored sections, do the following:
Wrap every section that should be normally colored in
<section class="site-section" id="section-2">
// Content within the section
</section>
For every alternatively colored section, add the class alternative-color to the section.

Some notes about that:

Alternatively colored sections don't look too good before the footer. So, it is recommended to always let the last section of your site be a normally colored one.
Furthermore, if you want the first section of your site to be an alternatively colored one, also add the class first-section to it. This makes sure the color starts directly below the Page Hero, and there is no small space in a different color in between Page Hero and first section.

Utilities

Of course, OneFlow comes with build-in styles for normal Markdown/HTML tags like headers, paragraphs, anchor-tags (links) and so on. There are furthermore some utilities that you can use to organize and style your content in a good-looking and structured way. Check out the theme website to see example of all of these utilities!

Notices

Notices highlight a paragraph or a div. Just add the notice class to any element, easy as that.
Apart from the standard-notice, there are some others with different colors, which are:
  • notice--primary
  • notice--success
  • notice--warning
  • notice--danger
  • notice--info
Apply these classes, instead of the notice-class, to use the different colors.

Boxes

Boxes also highlight your content, but with a different styling. Just apply the box class to any div-element to put it into a box with a nice little rounded border and very subtle background. Just as notices, boxes offer the same color variations. Keep the box-class with your divs and add one of the following:
  • box--primary
  • box--success
  • box--warning
  • box--danger
  • box--info
Boxes furthermore can be put into a div with the class box-container. Within that container, you can apply the box-half class to make a box fill half of the width and therefore be able to fit 2 boxes next to each other, or the box-third class to make a box fill a third of the width and therefore be able to fit 3 boxes next to each other. On small screens, boxes stack below each other responsively.

Buttons

Add the btn class plus any of the following classes to any a-tag to style the link as a button:
  • btn--primary
  • btn--success
  • btn--warning
  • btn--danger
  • btn--info
  • btn--inverse
You can furthermore edit the size of the button with the following classes:
  • btn--x-large
  • btn--large
  • btn--small

Responsive video-embed

Embed a video from YouTube, Vimeo, Google Drive, or bilibili that responsively sizes to fit the width of its parent. This feature is taken un-edit from Minimal Mistakes, see the Minimal Mistakes Docu about responsive video embed here .

Galleries

The gallery is as well taken from Minimal Mistakes, slightly edited in style to better fit OnePager Websites. Check the Minimal Mistakes Docu about galleries here .

Rounded images

Rounded images are a cool helper that displays a circular image in the top of a box, so that you can add header and a caption below the image. They add a cool visual element and can provide good structure as well. They can be included easily via YAMl front matter. Set the front matter like so:
round-images:
   - image-path: "/assets/images/image.webp"
     size: "full"
     header: "text for the header"
     caption: "text for the caption"

You can include further rounded image boxes by adding a next "- image-path" and all other necessary variables. Size can be either "full", "half" or "third" and determines, how much of the page width the box with the rounded image is going to take. With half, two boxes fit next to each other, with third, it's three.
Include the rounded images anywhere with {% include rounded-images %}.
You can use any other name than "round-images" for the rounded images. Then, you need to include an id in the include, like so: {% include rounded-images id="id-you-chose" %}.
Half or third boxes stack below each other responsively on smaller screens.

Image-text-rows

Image-text-rows include an image either on the left or right side, and a header + caption on the other side. They optionally can include a button with a link.
They can be set via YAMl front matter, and offer huge customization options. Create them like so:
image-text-row:
   - header: "text for the header"
     excerpt: "text for the caption/excerpt"
     btn-url: "https://your-url.com"
     btn-class: "primary/success/..."
     btn-label: "label for the button"
     blank: false
     image-url: "/assets/images/image.webp"
     alt-text: "alternative text for the image"
     image-width "400px"
     image-right: true
Leave out btn-url and the other btn-variables to not include a button.
"Blank" determines whether the link from the button is opened in a new tab or not.
"Image-right" sets whether the image is on the right side. With true, it is, with false, it is left.
Image and text responsively stack below each other on smaller screens, with the image always on top. You can easily customize the footer in config.yml. Under footer links you can set the social links that you want to include in the footer. Just set the url attribute for every social link you want to include, and out-comment the url attribute for every social link that you do not want to include.
Furthermore, you can set copyright to anything you like, like your or your clients name, which will display in the footer as '© [year] [name]'", with 'year' and 'name' being replaced by the respective values.
Also, you can include a creator name and url, if you like, which will then display in the footer as "Created by". If you remove or out-comment the creator attributes, no "Created by" will be shown.

Custom styles

If you want to add your own custom css, you can do that in the ready-to-use custom-styles.css file that is located with in /assets/css. Just add your css in there, nothing else you need to do as setup.

Fonts

Just like Minimal Mistakes, OneFlow uses system fonts for all font stacks, to provide a clean look and to improve performance. More information about that in the Minimal Mistakes Docu about Fonts.
Furthermore, you can easily apply custom fonts within OneFlow. Google Fonts offer high versatility and are free to use (you just might need to include a license, depending on the font). They can be hosted locally with ease. I recommend using Google Webfonts Helper for that. Select the font and font-styles you want there, download the files, and place them in /assets/fonts. Then open up /_sass/oneflow/_fonts.scss and put the css you got from Google Webfonts Helper there. That's it, you now host the font locally and can apply it to any text you like.

Icons

OneFlow comes with build-in support for Font Awesome Icons. Font Awesome 6.5.1 is included and hosted locally within OneFlow. Nothing for you to do but apply the icons! Just add an i-tag with the respective classes, check out the Font Awesome Website to find all their icons.

Editables

As a Web Developer, especially for private customers or small companies, I've came across the following situation a few times: The client wants to edit parts of the website him/herself regularly, for example to add or delete upcoming events or dates. Large companies can pay web developers for that, but private customers or small companies often understandably can't afford long-term maintenance costs.
To make this as easy as possible, utilize the editables-feature from OneFlow! Put any HTML/Markdown part that the client needs to edit in a separate file and place this file in the /_includes/editables folder, then include it on the main page with {% include /editables/filename.html %}.
The client then only needs to make changes within the given file, which makes it as as simple and as little error-prone as possible.

Further customization

OneFlow offers huge customization options without the need to touch any of the layouts, includes or sass files. If you need even further customization, these directories and files are included in the GitHub Repository, so you can go ahead and edit all files in every way you want for further customization and fine-granular styling. The layout structure can be edited within /_layouts/default.html or page.html. The scss stylesheets are located within the/_sass directory, and includes like the page hero, footer, masthead and also utilities like the gallery, rounded images or image-text-rows are located within the /_includes folder and can be edited right there.

Support / Contact

If you have any questions or feedback, don't hesitate to contact me! You can reach me via Email: info@perstarke-webdev.de, Instagram or by writing a GitHub Issue in the OneFlow Repository.

Contribution

If you have any suggestions on how to improve OneFlow, I appreciate any Pull Requests or Issues on GitHub. Feel free to contribute in any way!

Share your experience and results

If you created a Website using OneFlow, I am very happy to see and share the results! Message me, or create a Pull Request where you link your Website in the ReadMe of the OneFlow Repository. Happy website crafting y'all!