A fresh, lightweight custom built styleguide template to use with Jekyll sites. Just download or clone from the github repo and start building your site upon it.
Add this line to your Jekyll site's Gemfile
:
gem "jekyll-sharp-styleguide"
And add this line to your Jekyll site's _config.yml
:
theme: jekyll-sharp-styleguide
Add to your Gemfile:
gem "execjs", "2.7.0"
And then execute:
$ bundle
Or install it yourself as:
$ gem install jekyll-sharp-styleguide
The project is all set up, you just need to serve it:
bundle exec jekyll serve
Or if you want to compile your project for production (minify, autoprefix, etc.), use this command:
JEKYLL_ENV=production bundle exec jekyll serve
This is the directory structure of the project:
jekyll-rapid-styleguide/
βββ _includes
βββ _layouts
βββ _sass
βββ _site
βββ assets
βββ css
βββ fonts
βββ img
βββ js
As in every Jekyll project, the base configuration file is _config.yml
in the project's root folder. Feel free to open it in your text editor and customize the basic details of the site:
title: Jekyll Sharp StyleGuide
tagline: A styleguide template in Jekyll.
description: A fresh, lightweight custom built styleguide template in Jekyll.
author: ErikTailor
locale: en
You can obviously modify other settings in the configuration file as well, however it's not needed for a typical usuage, as these settings cover the best setup for usuage of this styleguide template.
Favicon (or site icon) is the tiny picture near the tab title of your website in a browser. If you have your custom image ready, go to the favicon generator and select your image. Customize the settings if needed, and make sure that the last setting Favicon Generator Options is set for locate favicons from a custom path (instead of project root) and enter /assets/img/favicons
as a path. Finally download the generated package, and replace the original favicons in the project.
To modify the visual elements of the styleguide template, you have to adjust a the style setting variables in _sass/_variables.scss
file. Open it up in your text editor, and customize it.
Colors |
Change the theme color variablees |
---|---|
Fonts |
Change the font family of the theme |
Headings |
Set the size of the headings |
Radius |
Set the global border radius value |
Breakpoints |
The responsive breakpoints, where layout changes |
Spacer |
Spacer is a global variable used to define the spacing between elements. |
Every asset of the site is located in the assets
folder. You can:
_includes/scripts.html
file.The site partials and reusable components are located in the _includes
folder. You can always add / modify / remove any of the files, according to the usuage of Jekyll Includes as in the original documentation.
Let's say that you want to add a tagline below the site title in the hero section. To do this, you have to edit the _includes/header.html
partial, by adding the following code below the <h1>
tag:
<h1>{{ site.title }}</h1>
<h2>My amazing tagline</h2>
Save the file, and head to the frontend of your site at http://localhost:4000
address. You will see, that the new tagline has been nicely added in the header:
Note: when you removing an include file, make sure to delete every instances where that include was called, or you will get a Jekyll error in building. So assume you delete image.html partial, then you have to delete these everywhere in the project.
If you are familiar with Sass syntax, you can easily modify a component's style in it's .scss
file. Every component is in a separate file, so you will probably find the element part you are looking for.
For example, you want to change the background color of the button component to black. Open the _sass/buttons.scss
file, and change the background-color attribute's value to dark:
.btn {
background: $dark;
...
After the build (or serve), if you go to the frontend, you will see that the button's background changed according to your modification made:
Feel free to edit each
.scss
file to achieve the expected custom layout imagined for your website.
The concept was to make available a couple of css
helper classes in head of the most quick development / customizing workflow. The base idea is that you not neeed to write css code every time you want to do a minor adjustment for example, just use the classes on the element you want to style, and achieve the expected result with less time spent.
Let's say, you want to add a bigger bottom spacing to an element. The usual way would be to target the element with a class or id, and write a css code to achieve the requested spacing, like:
#mydiv {
margin-bottom: 50px;
}
Instead of this, you can just add the mb-5
class (which is 50px margin to the bottom) to to the element, and get the expected result immediately, without need to write a line of code.
The template has a few helper classes for adjusting the target's margin or padding values. The basic syntax is formatted like <property><direction>-<size>
.
m
for margin, and p
for paddingt
for tope
for right (end)b
for bottoms
for left (start)1
for 10px2
for 20px3
for 30px4
for 40px5
for 50pxActually this is the exact same method what Bootstrap uses for spacing helpers. So to grab things together, let's say you want to add a left padding of 30px to an element. Just add the class ps-3
.
.ps-3
<padding
> <start
> -<30px
> .mt-1
<margin
> <top
> -<10px
> .pb-5
<padding
> <bottom
> -<50px
> .me-4
<margin
> <end
> -<40px
>;
About painting, we will cover two types:
*Β coloring a background
*Β coloring a text
The syntax would be the following: .bg-<color>
. Colors can be these by default:
.bg-accent {
background-color: $accent;
}
.bg-white {
background-color: $white;
}
The syntax is: .text-<color>
. You can use the colors mentioned above. So let's see examples:
.text-dark {
color: $dark;
}
.text-white {
color: $white;
}
It works like this: .opacity-<number>
. Numbering is by tens, if it's lower, the opacity of the element is as low as that value:
.opacity-70 {
opacity: 0.7;
}
.opacity-20 {
opacity: 0.2;
}
The last one is making the display css attribute easier to implement. The syntax is .d-<value>
.
.d-block {
display: block;
}
.d-none {
display: none;
}
Note: You will find the sources of these helper classses in the
_sass/_helpers.scss
file.
In this styleguide template I only use a single layout, the default one at _layouts/default.html
.
You have to edit this file if you may want to:
<head>
contentsNote: You are always free to create as many layouts as you need, according to Jekyll's layout documentation for more information on using layouts.
When you feel ready, and satisfied with the result, you may want to deploy the project to a website. If you planning to use GitHub Pages, you can find a great tutorial on this written by me.
Note: these jekyll plugins are not supported by GitHub Pages, so if you plan to host your website with it, you have to know that these plugins won't work.