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
- Hyvor Blogs
- [1.1 Hosting URL](https://hyvor.com/blog#hosting-url)
- [1.2 Delivery API Key](https://hyvor.com/blog#delivery-api-key)
- [1.3 Webhooks](https://hyvor.com/blog#webhooks)
- Cloudflare Workers
- [2.1 KV store](https://hyvor.com/blog#create-kv)
- [2.2 Deployment](https://hyvor.com/blog#deployment)
- [2.3 Variables](https://hyvor.com/blog#variables)
- Cloudflare Workers Routes
- [3.1 Set up Workers Routes](https://hyvor.com/blog#worker-routes)
- 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.
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
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
1.3 Webhooks
Next, go to Hyvor Blogs Console → Settings → Webhooks and create a webhook with the following values.
Create Webhook
We'll need the webhook secret in a next step.
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
Then, create a new namespace with a descriptive name.
Create KV Namespace
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.
Authorize GitHub with Workers
Next, select "I have an account"
For the next step, we will need your Cloudflare Account ID and an API token.
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.
Cloudflare Account ID
Then, click the "Get your API token" link below the account ID.
Create API Token
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.
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 loadingMake 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:
Top comments (0)