Put your docs on a sub-folder with Cloudflare

Follow this guide to host your Ferndesk help center at a custom subfolder (like yourdomain.com/help) using Cloudflare Workers as a reverse proxy.

Prerequisites

• A Ferndesk workspace with admin access

• A domain you own (already pointed to Cloudflare)

• Basic familiarity with Cloudflare's dashboard

Step 1: Set up the custom subfolder in Ferndesk

First, configure your Ferndesk help center to use a custom subfolder path.

1. Log in to your Ferndesk workspace, expand Help Center in the left sidebar, then click Customize.

2. Click Custom domain

   

3. Select the Custom sub-folder option

   

4. Enter your domain in the Domain field (e.g., yourdomain.com).

5. Enter your desired subfolder path in the Subdirectory field (e.g., /help or /docs).

6. Click Configure sub-folder.

Step 2: Create a Cloudflare Worker

Now create a new Cloudflare Worker that will act as a reverse proxy.

1. Log in to your Cloudflare dashboard.

2. Under BUILD → Compute & AI, navigate to Workers & Pages from the left sidebar .

   

3. Click Create application in the top right corner.

   

4. Under Start with Hello World!, click Get started.

   

5. Name your Worker something descriptive like ferndesk-reverse-proxy, then click Deploy.

   

Step 3: Configure the worker routes

Set up the routing rule that directs traffic from your custom subfolder to the Cloudflare Worker.

1. In the Worker settings, navigate to the Settings tab.

   

2. Scroll to Domains & Routes and click Add.

   

3. A modal window will open. Select the Route option.

   

4. In the Zone dropdown, select your domain (e.g., yourdomain.com).

5. In the Route field, enter the pattern for your subfolder path. Use *yourdomain.com/help* to capture all requests to the /help path and its subpaths.

6. Leave Failure mode set to Fail closed (block) for security.

7. Click Add route.

   

Step 3b: Adding the _ferndesk route

1. Scroll to Domains & Routes and click Add.

   

2. A modal window will open. Select the Route option.

   

3. In the Zone dropdown, select your domain (e.g., yourdomain.com).

4. In the Route field, enter the pattern for your subfolder path. Use *yourdomain.com/_ferndesk* to capture all requests to the /_ferndesk path and its subpaths.

5. Leave Failure mode set to Fail closed (block) for security.

6. Click Add route.

   

Step 4: Edit the Worker code

Now update the Worker code to handle the reverse proxy logic. The Worker will intercept requests to your subfolder and forward them to Ferndesk.

1. Click Edit code (or access the code editor from the Worker dashboard).

   

2. Replace the entire worker.js code with the reverse proxy script below.

   const HELP_HOST = 'your-company.hc.ferndesk.com'; // your Ferndesk help domain
   const PROXY_PREFIX = '/help'; // the subfolder you chose in Ferndesk
   const PROXY_VERSION = '2';
   
   addEventListener('fetch', (event) => {
   	event.respondWith(handleRequest(event.request));
   });
   
   async function handleRequest(request) {
   	const originalUrl = new URL(request.url);
   
   	// Keep canonical trailing-slash behaviour on the edge
   	if (originalUrl.pathname.endsWith('/') && originalUrl.pathname !== '/') {
   		originalUrl.pathname = originalUrl.pathname.slice(0, -1);
   		return Response.redirect(originalUrl.toString(), 301);
   	}
   
   	// Only intercept the help subtree (and the help assets)
   	if (
   		originalUrl.pathname !== PROXY_PREFIX &&
   		!originalUrl.pathname.startsWith(`${PROXY_PREFIX}/`) &&
   		!originalUrl.pathname.startsWith('/_ferndesk/')
   	) {
   		return fetch(request);
   	}
   
   	// Build the upstream request with the prefix removed
   	const upstreamUrl = new URL(originalUrl.toString());
   	upstreamUrl.hostname = HELP_HOST;
   
   	if (upstreamUrl.pathname === PROXY_PREFIX) {
   		upstreamUrl.pathname = '/';
   	} else if (upstreamUrl.pathname.startsWith(`${PROXY_PREFIX}/`)) {
   		upstreamUrl.pathname = upstreamUrl.pathname.slice(PROXY_PREFIX.length) || '/';
   	}
   
   	// Enables edge caching: tells Ferndesk this render belongs to your
   	// subfolder so it gets its own cache entry.
   	upstreamUrl.searchParams.set('__bp', PROXY_PREFIX);
   
   	const proxyRequest = new Request(upstreamUrl.toString(), request);
   
   	// Let the help app know we are hosted under the subfolder
   	proxyRequest.headers.set('X-Ferndesk-Base-Path', PROXY_PREFIX);
   	proxyRequest.headers.set('X-Forwarded-Host', originalUrl.host);
   	proxyRequest.headers.set('X-Ferndesk-Original-Host', originalUrl.host);
   	proxyRequest.headers.set('X-Ferndesk-Proxy-Version', PROXY_VERSION);
   
   	// Handle redirects ourselves so renamed articles redirect visitors on
   	// this domain instead of being followed silently.
   	const response = await fetch(proxyRequest, { redirect: 'manual' });
   	if (response.status >= 300 && response.status < 400) {
   		return rewriteRedirect(response, originalUrl);
   	}
   	return response;
   }
   
   // Translates an upstream redirect (on the Ferndesk help host) back onto
   // this site's host and subfolder. External redirects pass through as-is.
   function rewriteRedirect(response, originalUrl) {
   	const location = response.headers.get('location');
   	if (!location) return response;
   
   	const target = new URL(location, `https://${HELP_HOST}`);
   	if (target.hostname !== HELP_HOST) return response;
   
   	target.protocol = 'https:';
   	target.host = originalUrl.host;
   	target.searchParams.delete('__bp');
   
   	const alreadyPrefixed =
   		target.pathname === PROXY_PREFIX || target.pathname.startsWith(`${PROXY_PREFIX}/`);
   	if (!alreadyPrefixed) {
   		target.pathname = target.pathname === '/' ? PROXY_PREFIX : PROXY_PREFIX + target.pathname;
   	}
   
   	// Response headers from fetch are immutable; copy to edit Location.
   	const rewritten = new Response(response.body, response);
   	rewritten.headers.set('location', target.toString());
   	return rewritten;
   }
   Replace HELP_HOST with the actual Ferndesk domain provided when you configured your custom subfolder. Replace PROXY_PREFIX if you're using a different subfolder path (e.g., /docs instead of /help).

   Already set up your subfolder a while ago? Just replace your worker code with the version above. Everything keeps working exactly as before, and your help center pages will start serving from our edge network, typically loading in under 100 ms.

3. Click Deploy to publish your changes.

   

Step 5: Verify the setup

Test that your help center is now accessible at your custom subfolder path.

1. Open a new browser tab and navigate to https://yourdomain.com/help.

2. You should see your Ferndesk help center loaded with your branding.

3. Test a few pages by clicking links to ensure navigation works correctly.

Troubleshooting

Next steps

• Learn more about help center URL structure and section-aware paths

• Connect a custom domain (subdomain) instead