Developing Tailpages: A Jekyll Template based on Tailwind CSS
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:
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:
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 add webrickaccording to https://github.com/github/pages-gem/issues/752
bundle exec jekyll serve
- Open it in your browser:
postcss.config.js by running
yarn tailwindcss init -p
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:
npx tailwindcss -i ./assets/css/main.css -o ./assets/css/tailwind.css --watch to build the css file at
--watch makes sure that the css is regenerated whenever a change is detected in HTML files.
_layouts folder has all page templates, which may include page components, such as Navigation menu, footer, social media icons from files in
default.htmlis the base template that all other templates use
home.htmlis the template for the Homepage
page.htmlis the template for different pages
post.htmlis the template for blog posts
tag.htmlis 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
_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):
I referred to the following tutorials and code repos to develop this tutorial:
Originally published at http://harrywang.me on January 12, 2022.