Put your workspace on your own domain

Serve every document and folder in a workspace from an address you own, like docs.acme.com. A document filed under Guides opens at docs.acme.com/guides/<document>. Existing markdrop.in links keep working.

1. 1

   Add the domain

   #Copy sectionAsk about this

   Open the workspace's settings and go to the Look and domain tab. Under Your own domain, choose Add a domain. Type the hostname, like docs.acme.com, leave What it serves on Documents and files, and choose Add domain.

2. 2

   Prove it's yours

   #Copy sectionAsk about this

   Markdrop shows two records. The first is the Ownership record, a TXT record. Add it where you manage DNS for acme.com.

3. 3

   Point it at Markdrop

   #Copy sectionAsk about this

   The second is the Routing record. A subdomain like docs.acme.com uses a CNAME. An apex domain like acme.com uses an A record instead, because DNS doesn't allow a CNAME there.

4. 4

   Check DNS

   #Copy sectionAsk about this

   Choose Check DNS. When both records are found, the domain is verified and goes live on its own. The status changes to Live, and readers can open it.

For docs.acme.com, the records look like this. Copy the exact values Markdrop shows you; the TXT value is unique to your domain.

For an apex domain, acme.com:

Markdrop works out which panel your DNS lives in from your nameservers. When it knows, it says so ("Your DNS is at Cloudflare"), offers a button to open that provider's DNS page, and writes each name the way that provider expects it.

Prefer the terminal? The same steps work through the API with an API token. Your workspace id is in the address of its settings page, markdrop.in/settings/workspaces/<workspace-id>. kind is app for Documents and files, or cdn for Files only.

curl -X POST "https://api.markdrop.in/api/v1/workspaces/$WORKSPACE_ID/domains" \
  -H "Authorization: Bearer $MARKDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"host": "docs.acme.com", "kind": "app"}'

const res = await fetch(
  `https://api.markdrop.in/api/v1/workspaces/${process.env.WORKSPACE_ID}/domains`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MARKDROP_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ host: "docs.acme.com", kind: "app" }),
  },
);
const domain = await res.json();

import os, requests

res = requests.post(
    f"https://api.markdrop.in/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/domains",
    headers={"Authorization": f"Bearer {os.environ['MARKDROP_TOKEN']}"},
    json={"host": "docs.acme.com", "kind": "app"},
)
domain = res.json()

The response includes the records to add: dns_record_name and dns_record_value for the TXT record, and dns_target_type, dns_target_name and dns_target_value for the routing record. After you add them, check DNS with POST /api/v1/workspaces/<workspace-id>/domains/<domain-id>/verify.

Markdrop doesn't check a new domain on its own: choose Check DNS when you've added the records. A domain that's never verified is dropped after 7 days, and you can add it again.

The first domain you verify becomes the workspace's address on its own. With more than one, open a domain's menu and choose Make default. The default is the address Markdrop uses for shared links and preview cards. Every live domain keeps serving.

When you add a domain, What it serves has a second option, Files only: a plain file host for raw bytes, with no document pages. Use it for something like files.acme.com.

A Files only domain serves files your members upload, and anything it serves can set cookies on its parent domain. Prefer a domain you use for nothing else, not one that also hosts your app or marketing site.

Keep both records in place after the domain is live. Markdrop checks them again every day.

If the records stop resolving to Markdrop for three days, the domain stops serving and shows Lapsed. Put both records back, then choose Check DNS again. Links on markdrop.in keep working throughout.

To see the records again later, open the domain's menu and choose Show DNS records. Download records (CSV) is in the same menu.

Open the domain's menu:

• Detach stops serving at once, and links to the domain fail. The domain stays verified, so you can bring it back later without touching DNS.
• Remove domain stops serving and also discards the verification. Adding it back means adding the DNS records and waiting for them again.

Documents keep working on markdrop.in either way.