{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"set-a-custom-domain","__idx":0},"children":["Set a custom domain"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can configure a custom domain for your project and optionally serve your documentation from a subdirectory path."," ","This allows you to host your docs at URLs like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs.example.com"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs.example.com/api/"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-up-a-custom-domain","__idx":1},"children":["Set up a custom domain"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure your custom domain on the project's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom domain"]}," page:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log in to your Redocly instance."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select your project."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom domain"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add domain"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom Domain"]}," without the protocol."," ","For example, \"docs.example.com\"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["(Optional) Disable the default domain by unchecking the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use proxy to URL"]}," checkbox."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Log in to your DNS management provider and complete the following steps:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add a new TXT record with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["name/host"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["value"]}," listed in the Domain verification admonition."," ","The admonition is on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom domain"]}," section of the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," page in your project."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Point the domain CNAME record to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ssl.redocly.app"]},"."," ","If you have EU data residency, point the CNAME record to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ssl.eu.redocly.app"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify"]},"."," ","A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pending"]}," badge displays next to the domain, until it is verified."," ","Once the domain is verified, a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verified"]}," badge displays next to the domain."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"ssltls-certificates","__idx":2},"children":["SSL/TLS certificates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly automatically manages SSL/TLS certificates for your custom domains."," ","Once you have successfully verified your DNS records (CNAME and TXT), Redocly provisions and renews certificates using Let's Encrypt."," ","You do not need to provide or manually manage your own certificates for domains pointed at Redocly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"serve-from-a-subdirectory","__idx":3},"children":["Serve from a subdirectory"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set a project's path prefix to serve pages from somewhere other than the root of a domain."," ","This can help organize URLs or make the separation of content more clear."," ","For example, a SaaS company serving their developer documentation from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/developers"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To serve from a subdirectory, you also need to proxy requests to the website."," ","Any proxy should be capable of doing that; we are not responsible for supporting third-party products."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The path prefix is set using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDOCLY_PREFIX_PATHS"]}," ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/reunite/project/env-variables"},"children":["environment variable"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["URL ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["without"]}," prefix: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.example.com/page"]}," ","URL ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["with"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-v2"]}," prefix: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.example.com/api-v2/page"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-prefix-in-reunite","__idx":4},"children":["Set prefix in Reunite"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For projects deployed through Reunite, set the page prefix using environment variables in Reunite:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to the project ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Environment variables"]}," page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add environment variable"]}," and add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDOCLY_PREFIX_PATHS"]}," with your desired prefix value (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-v2"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deployments"]}," hyperlink in the banner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Trigger deployment"]}," button."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Deployment considerations"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDOCLY_PREFIX_PATHS"]}," only in your project's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file can cause health checks and publish steps to fail during deployment."," ","Use Reunite's environment variables feature for reliable deployments."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-prefix-for-local-development","__idx":5},"children":["Set prefix for local development"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For local development, you can add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REDOCLY_PREFIX_PATHS"]}," to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file in the root of your project:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","data-title":".env","header":{"title":".env","controls":{"copy":{}}},"source":"REDOCLY_PREFIX_PATHS=api-v2\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach is suitable for local testing but should not be used as the primary method for deployed projects."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Separate environment files"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use named environment files for more control, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.development"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.preview"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env.production"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prefixed-links-in-markdown","__idx":6},"children":["Prefixed links in Markdown"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After setting a page prefix, links to Markdown pages and related assets are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["automatically transformed"]}," to support the path prefix."," ","That transformation includes the sidebar, navbar, footer, and links used in content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You do not need to update any links to Markdown content after setting a page prefix."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prefixed-links-in-react","__idx":7},"children":["Prefixed links in React"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In React, you can automatically apply the path prefix to the URL by using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Link"]}," component, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"ExampleComponent.tsx","header":{"title":"ExampleComponent.tsx","controls":{"copy":{}}},"source":"import { Link } from '@redocly/theme/components/Link/Link';\n\nexport default function ExampleComponent() {\n    return (\n        <Link to=\"/guide/another-page\">Another page</Link>\n    )\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["withPathPrefix"]}," helper function provides an alternative way of adding the prefix to links, as in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"ExampleComponent.tsx","header":{"title":"ExampleComponent.tsx","controls":{"copy":{}}},"source":"import { withPathPrefix } from '@redocly/theme/core/utils';\n\nexport default function ExampleComponent() {\n    return (\n        <a href={withPathPrefix(\"/guide/another-page\")}>Another page</a>\n    )\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":8},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/reunite/project/env-variables"},"children":["Use environment variables"]}]}," - Configure additional project settings using environment variables for dynamic content and customization"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/links"},"children":["Manage links"]}]}," - Understand how link prefixes are automatically handled when adding links to Markdown content"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/api-docs/add-openapi-docs"},"children":["Add OpenAPI descriptions"]}]}," - Add API documentation that automatically uses your custom domain's page prefix for generated reference pages"]}]}]},"frontmatter":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"tagList":["admonition","configOptionRequirements"],"title":"Set a custom domain","lastModified":"2026-10-01T23:00:57.000Z"}