Developing Tailpages: A Jekyll Template based on Tailwind CSS

4 min readJan 12, 2022

Tailpages Developer Tutorial

Tailpages (Tailwind + Github Pages) is a Jekyll website template based on TailwindCSS, which can be hosted by Github for free. You can visit the demo site at https://harrywang.me/tailpages/.

Key features are:

Minimalist design inspired by the indigo template
Elegant typography via TailwindCSS Typography plugin and Inter font
Markdown support for content authoring (static pages and blogs)
Code highlighting and styling via highlight.js] (see code example)

This is a technical tutorial to show how to set up the development environment for Tailpages from scratch. Another no-code tutorial shows how you can use Tailpages template to quickly set up your website and blogs without coding, which you can access at medium or blog.

Let’s get started by creating an empty Github repo:

Fork and clone the repo on your computer and go to the cloned folder:

Setup Jekyll

NOTE: for Mac M1 users: follow https://www.earthinversion.com/blogging/how-to-install-jekyll-on-appple-m1-macbook/ to install jekyll ARM compatible version:

create a new Jekyll site: jekyll new tailpages, which create a tailpages folder within the repo folder:

move all files in the tailpages folder created by Jekyll one level up and then remove the folder:

After this, your folder structure should look like:

Open Gemfile file and add a Jekyll plugin we will need for processing Tailwind:

Now, you can test the site locally:

at the root of this repo folder run bundle install
run bundle add webrick according to https://github.com/github/pages-gem/issues/752
run bundle exec jekyll serve
Open it in your browser: http://localhost:4000

Setup TailwindCSS

Add TailwindCSS:

Create tailwind.config.js and postcss.config.js by running yarn tailwindcss init -p

We use Tailwindcss Typography plugin and Inter font family to style Markdown. I also modify the default Typography CSS to make the code style look better.

Add typography plugin and the font:

Then, enable typography plugin, inter font, and customizations by updating tailwid.config.js as follows:

NOTE: If this is your first time with Tailwind (just like me), you should know that Tailwind is “just-in-time”, i.e., Tailwind CSS is generated on-demand as you develop your html pages/templates instead of being generated in advance at initial build time. For example, if you specify content: ['./**/*.html'] in tailwind.config.js as shown above, the just-in-time engine scans all html files in this folder and generates the used styles into a tailwind output css file. For example, if you never used m-6 in any html file - it won't be outputted into the file.

Now we are ready to generate the Tailwind CSS file. First, create a new CSS file at /assets/css/main.css with the following content:

Then run npx tailwindcss -i ./assets/css/main.css -o ./assets/css/tailwind.css --watch to build the css file at ./assets/css/tailwind.css. --watch makes sure that the css is regenerated whenever a change is detected in HTML files.

Now, we can add a default layout HTML file to use Tailwind css at _layouts/default.html. Note that I also use FontAwesome for the icons and highlight.js for code highlighting.

Page Templates

_layouts folder has all page templates, which may include page components, such as Navigation menu, footer, social media icons from files in _includes folder:

default.html is the base template that all other templates use
home.html is the template for the Homepage
page.html is the template for different pages
post.html is the template for blog posts
tag.html is the template for the tag page

Customize Homepage and Add Pages/Blogs

You can refer to part I of this tutorial for how to customize the homepage and add new pages/blogs.

Github Pages Settings

you have to change baseurl and url in _config.yml to make the site work for Github Pages:

Now, you can test the site: jekyll serve and open http://127.0.0.1:4000/tailpages/ note now the address includes the baseurl, you should see the markdown file is styled with beautiful TailwindCSS.

Host with Github Pages

You just need to commit all changes and push to the repo. Then, enable Github Pages and you should be able to visit your site at https://<username>.github.io/<your-repo>, such as https://harrywang.github.io/tailpages (note that I used a custom domain in the following screenshot):

References

I referred to the following tutorials and code repos to develop this tutorial:

Originally published at http://harrywang.me on January 12, 2022.