Host your blog on a subdirectory using Cloudflare Workers

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

• A blog created on Hyvor Blogs.

• A domain that uses Cloudflare for DNS. It must be proxied through Cloudflare (orange cloud turned on).

• A GitHub account (free)

Step-by-step

1. Hyvor Blogs

   • 1.1 Hosting URL

   • 1.2 Delivery API Key

   • 1.3 Webhooks

2. Cloudflare Workers

   • 2.1 KV store

   • 2.2 Deployment

   • 2.3 Variables

3. Cloudflare Workers Routes

   • 3.1 Set up Workers Routes

4. Finalizing & Debugging

   • 4.1 Verify Features

   • 4.2 Cloudflare Worker Logs

   • 4.3 Clear Cache

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.

Then, save.

1.2 Delivery API Key

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

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

1.3 Webhooks

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

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

2. Cloudflare Workers

Let’s create our worker.

2.1 KV Store

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

Then, create a new namespace with a descriptive name.

2.2 Deployment

Click the button below to initiate a new deployment 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.

Next, select “I have an account”

For the next step, we will need your Cloudflare Account ID and an 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.

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

Use the Edit Cloudflare Workers template.

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

Create your API token.

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

Then, Connect your account.

Next, fork the github repository.

Go to the Github Actions page.

Enable Github Actions.

Click Workflows enabled.

Finally, DEPLOY!

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

2.3 Variables

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

Then, Settings → Variables → Edit Variables.

Click Save and Deploy.

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

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.

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.

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.

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.

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:

• Worker script: hyvor/hyvor-blogs-cloudflare-workers

• Cloudflare Workers Homepage

• Hyvor Blogs Docs