Prerequisite: a Jekyll + Tailwind CSS site that works locally

This tutorial assumes you already have a working Jekyll + Tailwind CSS website that’s successfully built locally, but when you try to deploy it to GitHub Pages, styles are not applied.

If that’s not true and you’re looking for general help on how to use Tailwind CSS with Jekyll, I documented the steps in another article.

Step 1: update the lockfile

Open your Gemfile.lock. Do you see x86_64-linux under PLATFORMS? If yes, all good. If not, run this command in your terminal:

bundle lock --add-platform x86_64-linux

Step 2: confirm Jekyll config is correct

This step is technically not related to this tutorial, but it’s quite possible that someone might dismiss a working setup as broken because of a wrong stylesheet link, so let’s include it anyway.

Will you be using a custom domain? Great, your _config.yml should start like this:

# _config.yml

url: 'https://your-domain.com'
baseurl: ''

# ..rest of the config

Planning to go with your-name.github.io option? Nice, just make sure your _config.yml starts with the following:

# _config.yml

url: 'https://your-name.github.io'
baseurl: 'your-repo-name'

# ..rest of the config

Step 3: create a GitHub Workflow

Create a new YAML file in .github/workflows/ directory. Since it’s all about GitHub Pages, let’s call it github-pages.yml:

# .github/workflows/github-pages.yml

name: Build and deploy this site to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  github-pages:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1
          bundler-cache: true
      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '18'
      - run: npm install
      - name: Build site
        uses: limjh16/jekyll-action-ts@v2
        with:
          enable_cache: true
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: ./_site

You can now commit this file and push this and all previous changes to GitHub.

Since your repository now includes the above workflow, pushing to the main branch will trigger a custom build instead of a standard one, and the generated _site directory will be pushed to the gh-pages branch.

A couple notes about that branch:

1. It will be created and updated automatically by the workflow. You don’t need to create it manually now and you won’t ever need to push to it directly in future.
2. There’s nothing special about the name gh-pages [any more]: GitHub Pages can now work with any branch. But the GitHub action peaceiris/actions-gh-pages uses that name, and since our workflow relies on it, that’s what we’ll use.

Step 4: configure GitHub Pages

Open your repository on GitHub and navigate to Settings > Pages. In the Build and deployment section there are two dropdown controls: Source and Branch. Make sure their values are set to Deploy from a branch and gh-pages respectively.

It may seem confusing that we are not selecting the GitHub Actions option in Source, but we don’t need to: as far as GitHub Pages is concerned we are telling it to deploy a normal branch that contains a pre-built static website. It doesn’t even know (or care) that the website was built with Jekyll, or that it was styled via Tailwind CSS.

Does your screen look like that? 👆

Then, that should be it! 🥳 If I didn’t miss anything writing this tutorial, and you didn’t miss anything reading it, your Jekyll website should now look the same on GitHub Pages as it does on your machine.

If you are not convinced yet, read on. But know that you are now wasting 5 precious minutes you can otherwise spend on making your welcome emails less vulnerable.

Before we move on, let me clarify that this rule applies to welcome emails sent after direct email sign-ups. Sign-ups via OAuth providers like Gmail, Twitter, GitHub, etc. are by default more secured against the vulnerability I am about to discuss.

Here’s what happened to me 👇

I run a micro SaaS called Weightless. Funny enough, all this tool does is collect email addresses and send email messages, so if anyone’s taking their email security seriously, it should be me. And that’s what I thought I was doing.

However, all my security efforts so far have been around making sure none of my users abuse Weightless to send spam to their subscribers. That’s not where the attacker struck! Because to even attempt spamming someone with Weightless, they would need to become a paid user first, and then to slip through my world-class 👀 security filters. Not efficient! Instead, why not make me spam people on their behalf, and for free?

This became possible by me trying to be too helpful too early, even before confirming the email address used at sign-up belonged to the person who signed up.

This is how my typical welcome email used to look:

Now let’s see how the same email turned out after my attacker decided to put some imagination to it:

That’s an actual email my SaaS sent to someone. And there were hundreds more, before Postmark, mailer daemon bless them, paused outgoing emails on my account and reached out to me.

The attack is quite simple in retrospect: the attacker saw I was including some user-input text in the welcome emails, and started a slow brute-force attack, most likely through an automated bot that was going through the list of real email addresses, signing up everyone on it with some irregular time intervals (maybe it was even less sophisticated and I am giving someone some new ideas here!).

There must be countless spammers abusing countless websites with this technique right now. And your website may well be among them if you, like me, decided that your welcome email can contain anything other the the email confirmation link. Or if, for example, you are passing on unconfirmed emails, together with other user-input data like name, company, etc. to your CRM software, or to the hands of your marketing team.

Consider this simple scenario:

You have a sign-up form with name and email inputs on it. Now pair it with a welcome email like this:

Hey NAME, thanks for signing up. Please click here to confirm your email.

So if Joe with the email joe@example.com signs up, they will get this welcome message:

Hey Joe, thanks for signing up. Please click here to confirm your email.

Nothing wrong, right? Wrong!

Here’s what that email looks like when someone is after Joe’s money:

Hey Joe. Here’s your $99 welcome gift! http://example.com/scam, thanks for signing up. Please click here to confirm your email.

To do this, the attacker only needs to enter Joe. Here’s your $99 welcome gift! http://example.com/scam in your name field. You are doing all the rest!

Pure evil!

If you look at my email screenshots again, you will see that, if anything, my attacker was not creative enough, and I believe they could have done much better. I used to display the same user-input text, mailing list name, twice: once in the subject line, and then in the body. And in both instances, the way they phrased it, resulted in an incoherent message:

Welcome to Weightless.so 🪶 Here’s your setup guide for ‘💳 BAM $1966: http://example.com/scam 💳’

Your mailing list 💳 BAM $1966: http://example.com/scam 💳 is ready.

Here’s what my subject line would look like if they put $1966’ welcome gift: http://example.com/scam ‘get it now as the mailing list name:

Welcome to Weightless.so 🪶 Here’s your setup guide for ‘$1966’ welcome gift: http://example.com/scam ‘get it now’

And here’s how their scam link would appear in the body, had they entered created has been, and our $1966 signup prize won you have, <(°.°)> and at http://example.com/scam it as the mailing list name:

Your mailing list created has been, and our $1966 signup prize won you have, <(°.°)> and at http://example.com/scam it is ready.

You see? A little more creativity and I would suddenly be helping someone run a Yoda-themed scam, and it’s not even the baby Yoda! Luckily enough, it’s not too hard to prevent something like that from happening:

Never include any user-input text in welcome emails, or any other type of emails triggered by submitting publicly accessible forms, where the receiver’s email address is part of the submitted data.

At the end of the day, all Jekyll does is generate a bunch of static HTML files. Anything non-static happens at build step. So yes, you can access your Airtable data, but not in real time. Each time you update your Airtable base, the website will need to be rebuilt to reflect those changes.

Okay, but why use a dynamic database for a static site? Reasons may vary. For most projects, you probably won’t need this but sometimes it makes sense. For example, things might become cumbersome if your website grows too data-heavy for a static site, or if you need to collaborate with non-developers. This is where Airtable comes in: instead of manually updating lengthy data files, you can work and collaborate on your data in Airtable.

Since this method makes use of the Jekyll-native _data folder approach, most existing Jekyll projects should be able to use it without any significant changes. If you stick with the attribute names present in your _data files and reuse them in Airtable, you shouldn’t even need to touch any of your template files.

I love when tutorials go with real-world examples instead of FooBar, to-do list, and now Wordl clone projects, so we will be creating a real website called UpToDate, which will keep us up to date with the latest releases of the libraries, frameworks or programming languages we care about.

UPDATE: UpToDate may have started as a pet project that helped me write this article but it’s grown into a real website now, that developers like you rely on to keep themselves updated. It’s even got a its own domain name: up-to.date!

Okay, Let’s go!

1. Create a new Jekyll project

If you are new to Jekyll or need a refresher, check out my in-depth guide on starting a new Jekyll site. Otherwise, these quick steps should suffice.

Initiate a new Jekyll project from you terminal:

jekyll new uptodate

CD to your project and bundle the gems:

cd uptodate
bundle

Let’s now update the default config. Open the _config.yml file and change its content to your liking. For UpToDate, it will look like this:

# Update default values
title: UpToDate
email: keep-me@up-to.date
description: >-
  Keep track of the latest releases of your favorite
  libraries, frameworks and programming languages
baseurl: ''
url: https://up-to.date

# Put my own twitter and github usernames
twitter_username: mzrnsh
github_username:  mzrnsh

# Keep the default theme and plugins
theme: minima
plugins:
  - jekyll-feed

Let’s confirm there are no issues so far:

bundle exec jekyll serve

Go to http://localhost:4000. If you see something like this, you’re ready for the next step:

2. Display some data the native way

Before we throw in Airtable, let’s add some data the native way and display it on a page to make sure it all worked before we started breaking things.

Add _data folder to the project’s root, and create a YAML file in it. In our case, it will be _data/things.yml file as we will be tracking the version numbers of all sorts of things. Let’s add a couple entries to it:

- name: Ruby on Rails
  version: 7.0.2.3

- name: Tailwind CSS
  version: 3.0.24

- name: Font Awesome
  version: 6.1.0

Next let’s display this data on the homepage. Open the index.markdown file and change its content to something like this:

---
layout: home
---

{% for thing in site.data.things %}
  - {{ thing.name }}: {{ thing.version }}
{% endfor %}

Since I am using the default Minima theme, the homepage comes with a blog section. Let’s get rid of it. The proper way to do this is overriding the default layout, or using a new layout but that is beyond the scope of this tutorial. Instead, let’s just delete the demo blog post file from the _posts directory. With no posts left, the theme will hide the blog section and the homepage will look nice and clean:

3. Create an Airtable base

With the initial version of UpToDate looking and working as intended, we can now start working on our Airtable integration.

First we need an Airtable base that houses the same data as we are displaying on our homepage. Head over to Airtable dashboard and create a new base. Here’s what it looks like for UpToDate:

Mind the capitalization of the table and column names. We will need to refer some of those values as strings in later steps.

I created this base manually as I have only 3 entries. If you have a lot more data, Airtable has various import tools to make things easier for you.

4. Add Airtable API credentials

To speak with the Airtable API, we will need to use an API key and the base ID. Ideally, we don’t want to make them a part of the source code. Instead, we want to use environment variables. Let’s use the jekyll-dotenv gem for this:

echo "gem 'jekyll-dotenv'" >> Gemfile
bundle

If using git, make sure to include .env file in your .gitignore:

echo ".env" >> .gitignore

Now create the .env file in the root directory with the following variables:

AIRTABLE_API_KEY='YOUR_API_KEY'
AIRTABLE_BASE='YOUR_AIRTABLE_BASE_ID'
AIRTABLE_TABLE='YOUR_AIRTABLE_TABLE_NAME'

Replace the sample values YOUR_API_KEY, YOUR_AIRTABLE_BASE_ID, and YOUR_AIRTABLE_TABLE_NAME with the actual values from your Airtable.

You can generate the API key on your Airtable account page.

And you can grab the Airtable base ID from the URL in your browser address bar. Open the desired base and copy the part of the URL right after airtable.com/:

As for Airtable table name, it’s the name you gave to your table. For UpToDate it is “things” string:

Important: Airtable API keys are unscoped, meaning they have the same permissions as your user account, across all the bases you have access to. If this concerns you, the ‘official’ way around it is to create a new account with limited permissions and generate an API key from that account.

5. Create a custom Jekyll plugin for Airtable

First let’s install the airtable and activesupport gems that we will need for our plugin:

echo "gem 'airtable'" >> Gemfile
echo "gem 'activesupport'" >> Gemfile
bundle

Next, we will be casually creating a custom Jekyll plugin! If you’ve already done this, you know there’s nothing scary about it. If not, see for yourself:

Create _plugins directory in the project root and a file named airtable.rb in it. That’s it, technically speaking, we already have a custom plugin. Now let’s make it do something.

Open the freshly created _plugins/airtable.rb file in the editor and paste the following:

require 'dotenv/load'
require 'airtable'
require 'active_support/all'

airtable = Airtable::Client.new(ENV['AIRTABLE_API_KEY'])
table = airtable.table(ENV['AIRTABLE_BASE'], ENV['AIRTABLE_TABLE'])

File.open("_data/#{ENV['AIRTABLE_TABLE']}.yml", 'w') do |file|
  data = table.records.map(&:attributes)
  warning = "# Do not edit this file manually \n"

  file.write(warning, data.to_yaml)
end

Let’s read the code above line-by-line to make sure everything is clear:

• Lines 1-3: import the libraries we will need
• Lines 5-6: connect to Airtable and retrieve the records from the table that houses our data. As you see, this is where we use the environment variables we set up earlier
• Line 8: open the existing data file. As both the data file name and the Airtable table name values are the same (in my case, “things”), I am using "_data/#{ENV['AIRTABLE_TABLE_NAME']}.yml" as file path. If for some reason those two values do not match in your project, you can simply specify the file path as a string: '_data/other_things.yml'
• Line 9: read the table records retrieved from Airtable and set the data variable’s value to it
• Line 10: Add a reminder for our future selves that this is an auto-generated file and shouldn’t be edited manually. Note that both the # at the beginning and the \n at the end are required to keep the YAML file valid
• Line 12: finally, complete the plugin’s work by uptading the file contents

Okay, let’s now confirm our plugin works. Start the Jekyll server, or if it’s already running, restart it:

bundle exec jekyll serve

Did the command run without errors? Nice!

Now open your data file and check if it was updated. From something like this:

- name: Ruby on Rails
  version: 7.0.2.3

- name: Tailwind CSS
  version: 3.0.24

- name: Font Awesome
  version: 6.1.0

It should have changed to something like this:

# Do not edit this file manually
---
- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
  version: 3.0.24
  name: Tailwind CSS
  id: rec41IcxHOE3f9KU1
- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
  version: 7.0.2.3
  name: Ruby on Rails
  id: recXh3RJKAfcsM4Kx
- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
  version: 6.1.0
  name: Font Awesome
  id: recpx0BkIPC8VWkD9

Yes? Great! 🎉 Your Jekyll site is now connected to Airtable and each time you build or serve it, the fresh data will be fetched from Airtable.

6. Automate rebuilds

Hold on, we’re not quite done yet! We likely want changes in Airtable to reflect on the website automatically, without manual rebuilds and redeploys.

There are multiple ways to achieve this, and the best option might depend on your Airtable plan, production hosting and personal tastes. At the time of me writing this, Airtable only supports webhooks on their enterprise plan, so unless you have that, the outline of your automation will probably look a little something like this:

• Your hosting platform allows redeploys by URL pinging
• A ‘bot’ regularly checks your Airtable base for changes
• When the bot detects changes, it pings the redeploy URL

But wait, this way the website will be redeployed from the same commit as before, so there will be no changes, right? Wrong! When the website is re-built, the plugin we just wrote will make a fresh request to Airtable during the build step, fetching the updated data, resulting the contents of your _data folder on production environment to differ from what you have in your latest commit.

Really good, it should all work fine, in theory. But let’s go with an example to make sure it works for real. To host UpToDate I am using Netlify, and here’s how I automated rebuilds there 👇

Example: Auto-deploy on Netlify via Pipedream

Pipedream is a low code automation platform with a generous free plan and some powerful features, and it’s perfect for our use case.

The next steps assume that you have a working Netlify deployment and a Pipedream account.

a. Generate a Netlify build hook

Let’s start by creating a deploy URL in Netlify. They call such URLs “Build hooks” and they’re created from your project’s “Build and deploy” settings:

https://app.netlify.com/sites/YOUR_PROJECT/settings/deploys#build-hooks

It’s a good idea to give build hooks descriptive names to remind your future self what it is used for, and so what is likely to break if you delete it.

b. Connect Airtable to Pipedream

Let’s now head to Pipedream and open the “Accounts” menu. Click “Connect an app” button and select “Airtable” in the options. Then follow the steps in the wizard to complete the connection.

c. Create a Pipedream source

With Airtable connected to our Pipedream, let’s add a new source that will make use of this connection. This will be the bot I mentioned above, tirelessly checking our data, hoping to detect any changes in it.

• Go to the “sources” menu
• Click “New +” button
• Pick “Airtable” as the app and “New or Modified Records” as the action

Now you need to configure your source:

• Choose values for the “Airtable account”, “Base” and “Table” dropdowns
• Set up the timer. I went with “Every 24 hours” but you can do it more frequently if you like. Just make sure you are staying within your Pipedream plan allowance
• Name the source. I went with “UpToDate changes”

Here’s what my source config screen looks like:

Once you create the source you need to make a couple changes, otherwise the out-of-box version of the source will emit an event for each change. We don’t want that as it will cause multiple Netlify deploys in case there are multiple changes since the last check.

Open the source and go to the “Configuration” tab. Here, in the code editor locate the guard clause that returns from the function in case there are no changes. Right now it’s this piece of code on line 45 (this may change):

if (!data.records.length) {
  console.log("No new or modified records.");
  return;
}

We don’t want to touch this part code, or anything that comes before that. Only the parts after it, up until the following lines close to the very end:

// We keep track of the timestamp of the current invocation
this.updateLastTimestamp(event);

I replaced everything between those two pieces of code with this:

// ...

if (!data.records.length) {
  console.log("No new or modified records.");
  return;
}

/* 👇 My changes 👇 */

this.$emit(data, {
  summary: `Changes detected: ${data.records.length}`
});

console.log(`Emitted changes.`);

/* 👆 My changes 👆 */

// We keep track of the timestamp of the current invocation
this.updateLastTimestamp(event);

// ...

d. Create a Pipedream workflow

Go to “Workflows” menu and click the “New +” button. It will pull up a menu to select a trigger, where you want to click the “USE ONE OF YOUR EXISTING SOURCES” button. This will let you select the source we created on the previous step.

Then add a step to this workflow. Pick “Send any HTTP Request” option. In the request configuration pick POST request type (that’s what Netlify build hooks expect) and paste the build hook URL we generated on step a.

Now give this workflow a good name it deserves. I went with “Rebuild UpToDate”. And click “Deploy”. Did you? Then you’re DONE! 🤩

From now on, when you, or others, update the data in Airtable, Pipedream will catch the changes, and trigger a Netlify deploy. And Netlify will run our plugin that will update Jekyll’s _data folder to reflect those changes, meaning the the website will get updated without any extra effort from us 🙀

It’s definitely no rocket science, but every now and then things don’t go so smooth: a new device, something out of date, something I forgot.. So I decided to document the process as a detailed guide to help me, or someone else, when that happens.

I tried to keep it beginner-friendly, so if you are a seasoned developer, don’t be surprised if you see me telling you things like how to add a line to a file from terminal, or that you should be using git.

UPDATE: I made a Jekyll + Tailwind boilerplate based on this guide. It will save you some time with fresh projects. Adding Tailwind CSS to an existing Jekyll site? Read on ⤵

0. Development environment:

If this is the first time you are building a Jekyll website on your machine, you might want to check out the official Jekyll documentation regarding the prerequisites.

Here’s my current development environment:

• macOS 12.2.1
• Ruby 3.1.1
• Bundler 2.3.7
• Jekyll 4.2.2
• Node.js 16.14.2

The differences with the minor [x.x.X] and patch [x.X.x] version numbers shouldn’t matter but with the major [X.x.x] numbers might.

1. Start a new Jekyll project

Let’s create a little static website called UpToDate. Run this in your terminal:

jekyll new uptodate --blank
cd uptodate

2. Set up Git:

In your terminal, run:

git init

In the root directory of your project create a file named .gitignore and paste the following in it:

_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
node_modules

3. Install Ruby gems

The --blank flag makes things really blank, so the Gemfile needs to be created manually. Add a file named Gemfile to the root directory with the following content:

source 'https://rubygems.org'

gem 'jekyll'
gem 'webrick'

Now let Bundler install those gems. In your terminal, run the install command:

bundle

If you see a message starting with “Bundle complete!”, it means everything went according to the plan. Let’s confirm this by firing up the Jekyll server from terminal:

bundle exec jekyll serve

Open localhost:4000 in your browser. You should see something like this:

4. Add PostCSS

In order to use Tailwind CSS, we first need to install and configure PostCSS.

Let’s install the PostCSS gem for Jekyll. Run the following in your terminal:

echo "gem 'jekyll-postcss'" >> Gemfile
bundle

For this plugin to work properly, some changes need to be made in Jekyll configuration. Open the _config.yml file and add the following lines at the end:

plugins:
  - jekyll-postcss

postcss:
  cache: false

Disabling cache is needed for Tailwind CSS’s JIT engine. Without this, the server would need to restart after each change.

Now create a postcss.config.js file in the root directory and paste the following in it:

module.exports = {
  plugins: [
    require('tailwindcss'),
    require('autoprefixer'),
    ...(process.env.JEKYLL_ENV == 'production'
      ? [require('cssnano')({ preset: 'default' })]
      : [])
  ]
}

Autoprefixer and cssnano packages are optional, but they are recommended for production builds.

Now let’s install those packages. I use Yarn (NPM is fine as well):

yarn add postcss@latest tailwindcss@latest autoprefixer@latest cssnano@latest -D

5. Add Tailwind CSS, finally

First create a tailwind.config.js file in the root directory with the following contents:

module.exports = {
  content: [
    './_drafts/**/*.html',
    './_includes/**/*.html',
    './_layouts/**/*.html',
    './_posts/*.md',
    './*.md',
    './*.html',
  ],
  theme: {
    theme: {
      extend: {},
    },
  },
  plugins: []
}

The above config lets Tailwind know where its utility classes might be located. If you add new directories for your posts, pages, or partials, you will need to update the content array accordingly.

By default, Jekyll works with SASS so we need to make a couple more changes.

Locate the assets/css/main.scss file and change its extension from .scss to .css. Unless you’re planning to use SASS, you might want to delete the _sass directory.

Now open assets/css/main.css and change its content to the following:

---
---

@tailwind base;
@tailwind components;
@tailwind utilities;

Note those hyphens at the beginning. That’s YAML front matter and our main css file must start with it.

Once again, let’s confirm everything’s working as intended. Start the Jekyll server, or if it’s already running, restart it:

bundle exec jekyll serve --livereload

Open localhost:4000 in your browser.

Things should look a little bit different from what we last saw, and a keen eye might even recognize Tailwind Preflight at play, stripping the browser default styles, but of course we need to make things red to be super sure.

Open _layouts/default.html and add class="text-red-500" attribute to the <body> tag. Now switch back to your browser. Since we used the --livereload flag, you should be seeing this already:

YES? Congrats! You are ready to use Tailwind CSS in your project 🥳

6. Bonus content: production deployment

6.1. Netlify

Netlify is my favorite tool when it comes to hosting static sites. For some reason, their default settings for deploying Jekyll sites seem to not play that well with my guide above.

If you experience any issues related to PostCSS during deploy, specifying JEKYLL_ENV in the build command might help. Instead of the Netlify-provided bundle exec jekyll build, use JEKYLL_ENV=production bundle exec jekyll build.

My build settings look like this, and it works:

6.2. GitHub Pages

If you set up your Tailwind CSS + Jekyll website according to this guide and you now wish to host it on GitHub Pages, it won’t work out of box. Long story short, you need to do it via GitHub Actions.

Luckily, I wrote about that as well.

Wasn’t all roses though, especially in the beginning. There’s this thing I call the Freelance Ladder, and I had to climb it, just like most other freelancers I know. When I say had to, you might think there was no other option for me, and that’s true. But even if there was, I strongly believe that this is also a ladder you want and need to climb to achieve a long-term success. I’ve seen a few aspiring freelancers take shortcuts. Some, I helped do it. But this doesn’t usually end well.

Moving up the ladder is not only about earning more, but also about learning more. And you have a lot to learn and figure out: how to sell yourself, how not to sell yourself short, what kind of clients you like and dislike to work with, whether you should specialize or generalize. These things take time and practice. There’s no shortcut around them.

Here’s the Freelance Ladder, and how you climb it:

1. Noob: sell output for low fixed price
2. Amateur: sell input for low hourly rate
3. Pro: sell input for high hourly rate
4. Legend: sell outcome for high fixed price

Illustration by unDraw

A few notes before we dive in:

• It should go without saying, that the absolute key to your success is you always doing everything within your power to deliver the value you promised. This article won’t give you any tips or tricks how to cheat your way up
• This is all based on my personal experience being a freelancer. I build software, so my path might be most relevant for professionals from the software development industry. But I believe that for the most part, it can also apply to aspiring freelancers from other industries
• I am not claiming this is the only or the best way to succeed as a freelancer. But this is the one I know and has served me well

Let’s go.

1. Noob: sell output for low fixed price

You may already be an expert in your field, but until you have something to show for, you are a noob. Know it, and own it.

Get on those freelance platforms and start bidding. But don’t waste time chasing exciting and well-paying jobs. Those attract the freelancers you aren’t yet equipped to compete with. Instead focus on boring, low-paying gigs that require one or more of your specific skills.

The best jobs, both in terms of your chances to land it, and their usefulness towards your ascent on the ladder, are highly descriptive tasks with clear deliverables that leaves not much room for imagination and uncertainty. The client knows what they want and how much they are willing to pay for it. The input, or the effort you put in, doesn’t matter to them. They are paying for the output.

Let’s go with an example. Say I am a freelance WordPress developer on the noob level. This is what a perfect job would look like for me:

Update Plugin X from version 2.3.1 to version 4.7.5. I don’t want it to be updated to the latest 6.0.0 version as it’s not compatible with the Plugin Y version 1.0.6 that we need to keep using. Our previous developer changed its code and we can’t touch it.

Budget: $100

It’s perfect for a few reasons:

• Not a reusable experience: chances of someone else having the exact same problem is close to 0
• Low fixed budget: it’s a safe bet that not a single non-noob freelancer will bother to bid on it. The upside has a hard limit, the downside does not
• The project is likely a mess: the previous developer could have left other easter eggs to make your life miserable. Even not every noob would bid on this, only the ones as desperate as you to land a job
• It’s specific enough to stand out: since most other applicants are noobs, no-one stands out by default. This is a perfect chance for someone with relevant skills and experience to shine

As a noob, winning hourly jobs is very hard. But there’s one more reason why you don’t even want such jobs just yet. If you are bidding on platforms like Upwork or Fiverr and you land an hourly job by selling yourself too short, this will stick out in your work history and might devalue you in the eyes of your future clients, making your climb longer than necessary.

2. Amateur: sell input for low hourly rate

After winning and successfully completing a few noob jobs, you should have built up some reputation on your freelance platform. You are now ready to step up. You may be tempted to continue winning the noob jobs, as it has become easier for you, but that’s not how you move up.

You already proved your input equals to an output of a certain value. Time to capitalize on this. You now have a chance to win more appealing jobs that pay hourly and last longer. Landing such a job will make your freelance journey more stable, enjoyable and profitable.

Your competition has changed though: instead of noobs, you are now competing with other amateurs and pros. This means your first few jobs will likely be close to the lower end of your desired hourly rate range. That’s okay, it will increase over time. Once you have established your place as an amateur and have a decent, long-term job, you can shake things up a bit to accelerate this growth. There’s no risk in failing. Here are a few things you can try:

1. Try to get a parallel job that pays slightly better than the current one
2. Ask for a raise from your current client. Make sure to have the power to walk away. Another job or an offer for one gives this power to you
3. Get yourself listed on a other freelance platforms - diversify
4. Start reaching out to potential clients directly, without a freelance platform as the middleman

If you are not in the acceleration game, no worries. Keep climbing up calmly. But make sure you are climbing. A good way to tell is whether or not your hourly rate and overall work satisfaction is growing. It should be, slowly but steadily.

3. Pro: sell input for high hourly rate

There’s no clear line between the amateur and pro levels. It’s more like you keep doing things as an amateur until you one day realize you have become a pro.

And there are ways to tell. Things will have changed:

• You can earn more while working less
• Winning jobs has become easier, the clients come to you now
• You have become picky who you want to work with
• The work you do is different. You have either specialized or generalized, or both
• You have more potential work than you can handle. You now casually reject job offers you’d only dream of as an amateur
• You have hired other freelancers
• You shake your head in disapproval while reading this article and go write a better one yourself

If you find yourself doing some or all of the above, congrats - you made it! 🥳 You are now a pro freelancer.

But the biggest change by far, is realizing that your input is no longer measured by your output. Rather, it’s now measured by the outcome.

Your actions now directly affect you client’s bottom line. Sure, this was true before as well, to an extent. That’s why you were getting paid in the first place. But it was not under your control and was limited. Heck! Remember when you were a noob? Most of the times, you weren’t even told why you had to do what you had to do. Fast forward to now, and I bet that often it’s you who decides what to work on and what to not. The clients only tell you what goals they want to achieve and you figure out the rest.

One more round of congratulations is in order, you deserve it. Keep going, you are doing great! And don’t forget to keep increasing your hourly rate.

4. Legend: sell outcome for high fixed price

Be on the pro level long enough, and you will inevitably notice that your hourly rate growth is slowing down. That’s a sign you are closing in on the ceiling. The ceiling is imposed by the industry you work in and once you hit it, your hourly rate growth depends on the industry salary growth and is mostly out of your control.

Hitting the ceiling is an amazing achievement though - it can make you one of the top paid professionals in your field. This also makes it is quite unlikely. I am nowhere near the ceiling myself and only a couple of wildly successful freelancers I know of may have glimpsed it from afar. I believe it’s a lot easier to move up the ladder once again than it is to actually hit this ceiling.

But the next level is being a legend. How do you become one? Well, I am no legend either, but I have been in the vicinity of that territory a couple times and I can tell you what I know.

Let’s start with the term “fixed price”. You may have already signed a few high paying fixed budget contracts as an amateur or a pro. But that didn’t necessarily make you a legend. For the purposes of this discussion, most fixed budget contracts are still hourly, you just agreed to calculate it upfront, based on estimations and assumptions. This is one more way to increase your hourly pay if you know what you’re doing, or a way to decrease it, if you don’t.

You are a legend when your compensation is completely detached from, and thus no longer limited by the time and effort you put in. Oh, you still put those in, and they’re worth more than most of your competitors’, but that’s not what you are getting paid for. You are getting paid for the outcome your input brings in for the client.

And so, pros still get paid, albeit handsomely, for turning the screws. Legends get paid for knowing which ones to turn.

If you are such a merchant, or a content manager who’s also in charge of technical maintenance, this article will give you a few ideas on how to keep your store fast, secure and easy to maintain.

1. Remove apps you no longer use

Make it a habit to go through the list of apps installed on your store and remove ones that you don’t use any more.

Before clicking the “Delete” button, check if the app has an uninstall guide. If it does, make sure to follow it BEFORE removing the app. This is because if the app has changed your theme, or added metafields to your store, and is responsible enough, they should have a button to clean it all up. And they won’t be able to do it after you have uninstalled the app.

Regular cleanups help you in a couple ways:

• Your store is not slowed down by an app you don’t use
• You are not sharing your & your customers’ data with a 3rd party that shouldn’t have access to it

2. Disable theme features you don’t need

Themes purchased on Shopify theme market or on 3rd party marketplaces tend to have a lot more features than you will ever need. This is because they are designed to support as many store types as possible. Some of these features can slow down your store. It’s not easy to guess which ones so it’s better to treat every feature as a suspect.

Head to your theme editor, and inspect page sections and theme settings. If you a see a feature you are not using and the theme editor has a button to disable it, click it.

3. Back up before changing code

First of all, if you have 0 idea what Liquid, JavaScript, HTML, or CSS is, you probably shouldn’t change anything from the theme’s code editor.

But if you are going to change it, make sure to back up your theme before touching a line of code. With backup I mean duplicating your live theme. Make sure to rename the duplicated theme in a way that indicates when and why this backup was made.

But you shouldn’t be making backups before every change. Rather do it before applying a set of changes. For example installing a new app that requires code changes, or adding a feature according to a guide you found online.

You are limited to 20 non-published themes per store. When you hit that number, you will have to delete some of the old backups to make room for new ones.

If you feel adventurous, you can also set up the Shopify + Github sync. This will automatically keep track of every change ever made to your theme. If you manage to complete this successfully, the developer you hire (or become) in future will thank you for it.

4. Understand and limit the permissions you grant others

Chances are high that other parties will need to access your store. Never share your password with anyone and if possible, enable 2-factor authentication on your account. Shopify has multiple ways to share access with different parties and it should be enough for all use cases:

• Staff accounts: used for inviting employees
• Collaborator access: used by 3rd party app support or developers
• Private apps: used to give access custom apps built for your store, or to 3rd apps that are not on Shopify App Market

Technically, you can invite hired developers as employees, but that will count toward your staff account quota, while collaborators won’t.

All these access types can and should have limited permissions. When at the permissions step during invitation, start by unchecking all options, then check the that are actually needed one by one. You can always grant more permissions later, if you miss something.

Actually, this step shouldn’t be on the list of things DIY merchants should do. EVERY Shopify merchant has to deal with this, so make sure you deal with it the least risky way.

5. Style the checkout page

The number of stores I see with the default checkout styles is surprising. Now, I am not a marketer who has studied how this affects your conversion rates. But I believe it falls under common sense that different pages of the same website should look similar to avoid confusing its visitors.

Shopify doesn’t allow changing much on the checkout page. Make sure to make use of what it does. Add your logo, change some colors.. takes 2 minutes.

He decided to start his own thing. He personally knew and had earned the respect of many restaurant owners in the town. And the delivery guys just loved him. People would follow.

Just one problem: he didn’t have the software or the money to build it. He got a few quotes, all beyond his budget and reached out to me to make sure he wasn’t getting ripped off. He was not. He’d get a website, an admin panel, mobile apps… in 3-4 months. He didn’t have the time either.

So I did what any developer friend would do - I said I could build it over the weekend. It was Friday. Whatever we did that weekend made it possible for him to onboard the first restaurant on Monday. But this story is not about me being a superb engineer, which I am not. It’s about scaling down.

And down we scaled!

When you hear a “food delivery app” you probably imagine something similar to what you already have on your phone: list of restaurants with menus, placing orders with a few taps, tracking how your food moves on the map, tipping couriers and leaving feedback. We didn’t have any of that. We didn’t have push notifications or online payments either. In fact, there was no mobile app at all.

We had to work with some serious, immediate constraints: we only had that weekend as I was working full time back then. And even if we had the time, neither of us knew how to build a mobile app.

So we “scaled down” all the way to B2B. Turns out, more than a few restaurants in town would gladly handle the sales and marketing themselves and keep 100% of the order value minus fixed delivery fees.

All we built was a basic web app with a couple forms, and this is how it all worked:

• Restaurants would accept orders by phone, Facebook, Whatsapp, Instagram… Didn’t matter.
• They’d then fill in a form in our app with customer address.
• The app would assign the order to a free courier, triggering an email. Their Gmail was our mobile app!
• The courier would then pick it up, deliver, take cash on delivery, and mark themselves as “available” again.
• At the end of the day the couriers would bring in the cash, minus their cut.
• At the end of the month, my friend would wire the money to the restaurants, minus his cut.

This CRUDe (pun intended), ad-hoc and free MVP functioned for over a year, keeping all sides happy and profitable. Later my friend was able to afford building a fully-fledged app and eventually, to exit on his terms.

Each time I start a new project, I remind myself of this story and the important lesson I learned from it. It’s not about making friends with a developer, although having me at his side did help my friend save a few bucks. No, it’s about embracing the constraints. They proved to be his true allies, pushing him towards less features, faster launch and a better business model. Pushing him into profitability from day 0.

When you have the money and the time, it’s tempting to throw them at your problems. That way you have a good chance to get what you expect. But when all you have is your creativity, you might end up with something much better, something you would never expect.