You can configure domains for your hosted site to make it easier to access your documentation.

Free subdomain

Every Basedoc project is automatically assigned a free subdomain using the "slug" chosen when creating the project on the basedoc.io domain.

For example, if your slug is "my-project", your subdomain will be my-project.basedoc.io.

Your subdomain is immediately live and available for use, and free forever.

Custom domain

You can configure a custom domain for your hosted site to make it easier to access your documentation. This requires adding a DNS record for your domain to point to Basedoc.

To add a custom domain, go to your project in Basedoc and select Settings in the top right.

Here you can add a custom domain to your project, for example docs.example.com or mydocssite.com.

In the form, enter the domain you want to use and click Save domain.

After this you will need to add a CNAME record to your domain's DNS settings.

For example, if you are using the domain docs.example.com, you will need to add a CNAME record for docs with the value sites.basedoc.io.

To use your root/apex domain, you will need to add a CNAME record for @ with the value sites.basedoc.io.

Once you have added the DNS records, you can refresh your project settings in Basedoc. When the system can see your DNS record you will see a success message.

Then your site will be available at your custom domain.

Subdirectory

You can also configure your hosted site to be available at a subdirectory of your domain, for example https://example.com/docs.

To do this you will need to redirect traffic to Basedoc.

First, go to your project in Basedoc and select Settings in the top right.

Here you can add a subdirectory value for your project, for example /docs.

Then you will need to configure the traffic redirection. There are a few different ways to do this, depending on your hosting provider.

Reverse proxy

You can use a reverse proxy to redirect traffic to Basedoc.

For example, if you are using Nginx, you can use the following configuration:

location /docs {
  proxy_pass https://myproject.basedoc.io;
  proxy_set_header Host myproject.basedoc.io;
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
}

Cloudflare Worker

If your domain is hosted with Cloudflare, you can use a Cloudflare Worker to redirect traffic to Basedoc.

Create a new worker with the following code, and edit the BASEDOC_SLUG variable to the slug of your project.

const BASEDOC_SLUG = "myproject";
const BASE_PATH = "/docs";

export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (!url.pathname.startsWith(BASE_PATH)) {
      return fetch(request);
    }

    // Strip /docs, always leave a leading slash
    const upstreamPath =
      url.pathname.slice(BASE_PATH.length) || "/";

    const upstreamUrl =
      `https://${BASEDOC_SLUG}.basedoc.io` + upstreamPath + url.search;

    const headers = new Headers(request.headers);
    headers.set("X-Forwarded-Host", url.host);
    headers.set("X-Forwarded-Proto", url.protocol.slice(0, -1));

    const resp = await fetch(upstreamUrl, {
      method: request.method,
      headers,
      body: request.body,
      redirect: "manual",
    });

    const outHeaders = new Headers(resp.headers);
    outHeaders.set("X-Basedoc-Proxied", "true");

    return new Response(resp.body, {
      status: resp.status,
      statusText: resp.statusText,
      headers: outHeaders,
    });
  },
};

Then add a Worker route in Cloudflare to redirect traffic to your worker. This route should be yourdomain.com/docs*.

Vercel

If your domain is hosted with Vercel, you can use a Vercel Edge Function to redirect traffic to Basedoc.

Create a new middleware.ts file in the root of your project with the following code, and edit the BASEDOC_SLUG variable to the slug of your project.

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

const BASEDOC_SLUG = "myproject";
const BASE_PATH = "/docs";

export function middleware(request: NextRequest) {
  const { pathname, search } = request.nextUrl;

  if (!pathname.startsWith(BASE_PATH)) {
    return NextResponse.next();
  }

  const upstreamPath =
    pathname.slice(BASE_PATH.length) || "/";

  const upstreamUrl =
    `https://${BASEDOC_SLUG}.basedoc.io` + upstreamPath + search;

  const res = NextResponse.rewrite(upstreamUrl);

  res.headers.set("X-Basedoc-Proxied", "true");
  res.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");
  res.headers.set("X-Forwarded-Proto", "https");

  return res;
}