Host your blog on a subdirectory using Cloudflare Workers

A step-by-step guide on how to set up a blog on a sub-directory using Cloudflare Workers. No coding required.

At Hyvor Blogs, we have been working on several different solutions to allow hosting a blog on a sub-directory. Out of all the solutions, Cloudflare Workers is by far the easiest solution if you are already using Cloudflare for DNS. It will only take about 10-15 minutes to complete the setup. No coding is required.

If this is the first time hearing about Hyvor Blogs, see our homepage for more details on how we make blogging easy!

How it works

Sub-directory hosting is handled by our hyvor/hyvor-blogs-cloudflare-workers script, which you can easily deploy to your own Cloudflare account as a Worker. Here’s what it does under the hood (you don’t have to understand any of this to use it 🙏)

  • It uses Cloudflare Workers to create a serverless application to serve your blog.

  • It uses Hyvor Blogs Delivery API to fetch serving instructions from Hyvor Blogs.

  • Then, it caches responses in Cloudflare KV (key-value storage). All resources in your blog (images, CSS, JS, and even HTML files) are cached in Cloudflare’s global network. This means everything in your blog is served to end users from the nearest node in the network. Your blog will be blazingly fast!

  • Then, it uses Hyvor Blogs Webhooks to clear the cache when you update your blog posts. (Due to this, there can be a delay of a few seconds before you see updates in your blog after updating a post.)

  • Finally, we use Cloudflare Workers Routes of your domain to route all example.com/blog* requests to the worker.

Let’s get started!

Prerequisites

Step-by-step

  1. Hyvor Blogs

  2. Cloudflare Workers

  3. Cloudflare Workers Routes

  4. Finalizing & Debugging

1. Hyvor Blogs

First, let’s make your blog hostable on a sub-directory.

1.1 Hosting URL

Go to Hyvor Blogs Console → Settings → Hosting and set the following options.

Option

Value

Hosting on/at

Self-hosting

Self-hosting URL

The full URL you will be hosting your blog at (including https://).

ex: https://example.com/blog

Changing Hosting URL in the Hyvor Blogs Console
Hosting URL

Then, save.

1.2 Delivery API Key

Go to Hyvor Blogs Console → Settings → API Keys and generate a Delivery API key.

Generate Delivery API key in the Hyvor Blogs Console
Generate Delivery API Key

We’ll need the generated API key in a later step, which you can copy from the API Keys section.

How to copy the Delivery API Key
How to copy the Delivery API Key

1.3 Webhooks

Next, go to Hyvor Blogs Console → Settings → Webhooks and create a webhook with the following values.

Option

Value

URL

https://example.com/blog/_hb_webhook

(make sure to replace https://example.com/blog with your blog URL)

Events

Select these three:

  • cache.single

  • cache.templates

  • cache.all

Create Webhook
Create Webhook

We’ll need the webhook secret in a next step.

Copying Webhook Secret from the Hyvor Blogs Console
Copying Webhook Secret

2. Cloudflare Workers

Let’s create our worker.

2.1 KV Store

Log into the Cloudflare Dashboard. Then, navigate to Workers & Pages → KV.

Cloudflare KV Settings
Cloudflare KV

Then, create a new namespace with a descriptive name.

Create KV namespace in Cloudflare Workers
Create KV Namespace

2.2 Deployment

Click the button below to initiate a new deployment to Cloudflare workers.

Deploy to Cloudflare Workers

Next, we’ll follow the steps shown on the deployment page.

First, authorize Github to use Workers. You will need a free GitHub account to do this.

Authorize Workers
Authorize GitHub with Workers

Next, select “I have an account”

I have an account on Cloudflare workers deployment

For the next step, we will need your Cloudflare Account ID and an API token.

Account ID and API Token requirement
Account ID and API Token

The easiest way to find this is by going to the Overview section of your domain and finding the Account ID on the right. Copy and paste it in the deployment page.

Copy Account ID in Cloudflare
Cloudflare Account ID

Then, click the “Get your API token” link below the account ID.

Create Token
Create API Token

Use the Edit Cloudflare Workers template.

Create Token - Select Cloudflare Workers

In the configuration, set the Account Resources to ‘All accounts’ and Zone resources to your domain name.

Create Token - Select Resources Options

Create your API token.

Create your API token - confirm

Copy the API token and paste it on the deployment page.

Copy API token

Then, Connect your account.

Connect your Cloudflare acccount for the deployment

Next, fork the github repository.

Fork the github repository

Go to the Github Actions page.

Go to github actions page

Enable Github Actions.

Enable github actions

Click Workflows enabled.

Workflows enabled

Finally, DEPLOY!

Deploy the worker

It will take a couple of minutes to complete the deployment. You can refresh the page to see the deployment status.

Worker deployed - pending

2.3 Variables

Once the deployment is completed, go to your worker settings page.

changing worker variables

Then, Settings → Variables → Edit Variables.

editing variables in the worker

Option

Value

Encrypt

BASE_PATH

Base path of your blog. Ex:
/blog
/news

No

DELIVERY_API_KEY

Delivery API key from the above step 1.2. Get it from Console → Settings → API Keys

Yes

SUBDOMAIN

Subdomain of your blog. Get it from Console → Settings → Hosting. Note that this is not the subdomain you will be hosting your blog on, rather the subdomain of hyvorblogs.io, which is used to identify your blog.

No

WEBHOOK_SECRET

Webhook secret key from the above step 1.3. Get it from Console → Settings → Webhooks

Yes

Click Save and Deploy.

saving edited variables in the cloudflare worker

Then, scroll down to the KV Namespace Bindings section, and add a new binding.

setting up KV namespace in the cloudflare worker

Option

Value

Variable Name

BLOG_CACHE

(this should be exact)

KV Namespace

Select the KV namespace you created earlier.

cloudflare worker KV setup

Now, our Worker is complete.

3. Cloudflare Workers Routes

The final step is to route traffic from your domain to the Worker we just created. To do that, we’ll use Cloudflare Workers Routes.

3.1 Set up Workers Routes

Go to Cloudflare Dashboard → Your Domain → Workers Routes.

cloudflare worker routes

Add a route with the following values (make sure to replace example.com with your domain name. Also, /blog if you are using a different base path). Then, click Save.

add route to your DNS

Now, open your blog URL in your browser. You should see your blog perfectly rendered.

4. Finalizing & Debugging

4.1 Verify Features

Follow these steps to make sure everything is working.

  • Make sure /blog is loading

  • Make sure posts with images are loading

  • Update one of your posts from the Console. You should see the changes on your blog in a couple of seconds.

  • Open https://{yourdomain.com}/blog/_cache_health. You should see a “Healthy ✅” message. If not, make sure you have connected the KV store correctly as explain above.

4.2 Cloudflare Worker Logs

If the blog is not loading at all, if you see an error on your blog page, or if updates are not shown on your blog, use Worker Logs to debug.

logging for debugging

4.3 Clear Cache

If you have any issues with styles or fonts in your blog, you can try to clear cache of your blog at Console → Settings → Danger Zone → Clear Cache. Select All as the Type.

clear cache in Hyvor Blogs Console

The End

I hope this guide helped you set up your blog on a sub-directory using Cloudflare workers. If you need any help, feel free to comment below or contact Hyvor Blogs support. If you found anything confusing, please leave a comment below. It will help us make this guide better for future readers.

Resources:

Comments

Published with Hyvor Blogs