Serving a Project from Your Own Address
updated
With a canonical URL, a project’s documentation opens at an address on your own site, for example https://example.com/docs. Links within the project, images and search on those pages stay under that address, and search engines treat it as the original. The pages on public.meldoc.io keep working as before.
Meldoc does not host your domain. Your site stays where it is, and a reverse proxy you control forwards the documentation paths to Meldoc.
What you need
- A workspace on the Enterprise plan. Without it, Canonical URL in the project settings shows Available on Enterprise. and a Contact sales button.
- Permission to manage the project’s settings.
- A project with the access level Unlisted or Public. A private project gives your proxy no answer; the settings dialog says so.
- A reverse proxy in front of your site that you can configure.
Set it up
- Open Project settings and choose Canonical URL.
- Enter your address, for example
https://example.com/docs, and select Save. Usehttps, a domain name and, if you want one, a path. A port, a query string or a#part is refused, and so is an IP address. Capital letters in the domain and a trailing slash are tidied up for you; the path keeps its case. - Copy the address under Point your proxy at. It looks like
https://public.meldoc.io/_proxy/<workspace>/<project>. - Configure your proxy as described below.
- Select Check.
The check runs only when you select Check; until it passes the status reads Not verified. The pages already open through your proxy during that time, but the address is not yet declared canonical on public.meldoc.io. Once the status reads Verified, the pages on public.meldoc.io tell search engines that your address is the original.
What your proxy has to do
Two rules, not one. Both must forward to the address you copied:
| Request to your site | Forward to |
|---|---|
/docs |
the copied address |
/docs/* |
the copied address plus the rest of the path |
The first rule serves the project’s start page, the second everything else. Setting up only /docs/* is the usual mistake: the documents open and the start page does not.
The proxy must also pass status codes and redirects through untouched, and add no redirect of its own: no trailing-slash or www redirect on the docs path. And it should set the visitor’s address in X-Forwarded-For. Without it, everyone who searches from your site counts as one visitor against the search rate limit.
nginx
Replace /docs with the path of your address, and <workspace>/<project> with the end of the address you copied.
location = /docs {
proxy_pass https://public.meldoc.io/_proxy/<workspace>/<project>;
proxy_ssl_server_name on;
proxy_redirect off;
proxy_set_header Cookie "";
proxy_set_header Authorization "";
proxy_set_header X-Forwarded-For $remote_addr;
}
location /docs/ {
proxy_pass https://public.meldoc.io/_proxy/<workspace>/<project>/;
proxy_ssl_server_name on;
proxy_redirect off;
proxy_set_header Cookie "";
proxy_set_header Authorization "";
proxy_set_header X-Forwarded-For $remote_addr;
}
If nginx itself sits behind a CDN, use the CDN’s variable for the real client address instead of $remote_addr. nginx looks up public.meldoc.io once, when it loads its configuration, so reload it on a schedule, for example daily, to follow address changes.
Cloudflare Worker
Add the routes example.com/docs and example.com/docs/* to the Worker, and replace /docs and <workspace>/<project> as above.
export default {
async fetch(request) {
const url = new URL(request.url);
const rest = url.pathname.slice('/docs'.length);
const target = 'https://public.meldoc.io/_proxy/<workspace>/<project>' + rest + url.search;
const headers = new Headers(request.headers);
for (const h of ['cookie', 'authorization', 'host']) headers.delete(h);
headers.set('X-Forwarded-For', request.headers.get('CF-Connecting-IP') ?? '');
return fetch(target, { method: request.method, headers, redirect: 'manual' });
},
};
Both recipes drop the visitor’s cookies and Authorization header: they belong to your site, and Meldoc reads neither, so forwarding them would only hand your sessions to a third party.
Any other host that can rewrite a path to an external URL works the same way: the same two rules, no redirects.
What Check verifies
Check requests two addresses on your site: <address>/_verify, which exercises the second rule, and the address itself, which exercises the first. Both have to answer 200 and be recognisably this project. If one fails, the notice says which address it looked at and, for an error or a redirect, what status it got.
| The notice says | What to fix |
|---|---|
| This address is not reachable from the internet. | The domain points at a private or internal address. The check only reaches public servers. |
| We could not connect to this address. | The domain does not resolve, the certificate is invalid or the server did not answer in time. |
| The address answers with a redirect. It has to answer directly. | The proxy, or something in front of it, redirects. For these paths, turn off trailing-slash redirects, redirects between www and the bare domain, and redirects to a login page. |
| The address answered with an error. | A status other than 200 came back. A 404 usually means a missing rule or a wrong copied address. |
| The address answers, but not with this project. | Something else answers at that address: another page on your site, or a different project. If the address itself fails this, HTML minification or rewriting on your proxy or CDN may have removed the marker the check looks for. |
| Try again in a minute. | Checks are limited in number per minute. |
A failed check clears an earlier Verified, so run it again after any change to your proxy.
What does not come along
- Documents protected by a password open on
public.meldoc.ioafter a redirect, not on your site. A project whose first document is protected cannot pass Check, because its start page redirects. - Links copied with Share still point at
public.meldoc.io. - Meldoc’s analytics and cookie banner are not shown on your site.
- Links to another project of the workspace open on
public.meldoc.io. - Search on the proxied pages finds documents of this project only, and in a very large workspace a matching document can be missing from it.
- Changing the project’s alias changes the address your proxy points at, and Verified is cleared. Update the proxy and run Check again.
- Removing the canonical URL with Remove stops the proxy from being answered and takes the declaration off
public.meldoc.io. If your workspace loses the Enterprise plan, the saved address stays in force, can be removed, and cannot be changed or checked again.
Sitemap
The proxied pages come with a sitemap at <address>/sitemap.xml, for example https://example.com/docs/sitemap.xml. It lists the project’s documents except protected ones. Add it to your site’s robots.txt:
Sitemap: https://example.com/docs/sitemap.xml
What’s next?
Creating and Configuring Projects — The rest of the project settings.
Document Visibility & Access Level — Who can open a project and its documents.