-
Notifications
You must be signed in to change notification settings - Fork 157
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation edits made through Mintlify web editor
- Loading branch information
1 parent
d70b909
commit 2f06725
Showing
20 changed files
with
340 additions
and
1,358 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,46 +7,20 @@ import SubpathGatingSnippet from "/snippets/custom-subpath-gating.mdx"; | |
|
|
||
| <SubpathGatingSnippet platform="Cloudflare" /> | ||
|
|
||
| ## Create Cloudflare Worker | ||
| ## Setup Instructions | ||
|
|
||
| Navigate to the `Workers & Pages > Create application > Create worker`. You | ||
| should be able to presented with the following screen where you can create a new | ||
| Cloudlfare worker. | ||
| 1. Create a Cloudflare Worker at `Workers & Pages > Create application > Create worker` | ||
|
|
||
| <Frame> | ||
| <img alt="Create a Cloudflare worker" src="/images/cloudflare/worker.png" /> | ||
| </Frame> | ||
| 2. Add your custom domain: | ||
| - Go to `Configure worker > Settings > Triggers` | ||
| - Click `Add Custom Domain` | ||
| - Add your domain (with and without `www.`) | ||
|
|
||
| ### Add custom domain | ||
|
|
||
| Once the worker is created, click `Configure worker`. Navigate to the worker | ||
| `Settings > Triggers`. Click on `Add Custom Domain` to add your desired domain | ||
| into the list - we recommend you add both the version with and without `www.` | ||
| prepended to the domain. | ||
|
|
||
| <Frame> | ||
| <img | ||
| alt="Cloudflare worker custom domain" | ||
| src="/images/cloudflare/custom-domain.png" | ||
| /> | ||
| </Frame> | ||
|
|
||
| If you have trouble setting up a custom subdirectory, | ||
| [contact our support team](mailto:[email protected]) and we'll walk you through | ||
| upgrading your hosting with us. | ||
|
|
||
| ### Edit Worker Script | ||
|
|
||
| Click on `Edit Code` and add the following script into the worker's code. | ||
|
|
||
| <Frame> | ||
| <img alt="Cloudflare edit code" src="/images/cloudflare/edit-code.png" /> | ||
| </Frame> | ||
|
|
||
| <Tip> | ||
| Edit `DOCS_URL` by replacing `[SUBDOMAIN]` with your unique subdomain and | ||
| `CUSTOM_URL` with your website's base URL. | ||
| </Tip> | ||
| 3. Add the worker script: | ||
| - Click `Edit Code` | ||
| - Copy the script below | ||
| - Replace `[SUBDOMAIN]` and `[YOUR_DOMAIN]` with your values | ||
| - Deploy the changes | ||
|
|
||
| ```javascript | ||
| addEventListener("fetch", (event) => { | ||
|
|
@@ -56,9 +30,7 @@ addEventListener("fetch", (event) => { | |
| async function handleRequest(request) { | ||
| try { | ||
| const urlObject = new URL(request.url); | ||
| // If the request is to the docs subdirectory | ||
| if (/^\/docs/.test(urlObject.pathname)) { | ||
| // Then Proxy to Mintlify | ||
| const DOCS_URL = "[SUBDOMAIN].mintlify.dev"; | ||
| const CUSTOM_URL = "[YOUR_DOMAIN]"; | ||
|
|
||
|
|
@@ -74,11 +46,9 @@ async function handleRequest(request) { | |
| return await fetch(proxyRequest); | ||
| } | ||
| } catch (error) { | ||
| // if no action found, play the regular request | ||
| return await fetch(request); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Click on `Deploy` and wait for the changes to propagate (it can take up to a few | ||
| hours). | ||
| Need help? [Contact our support team](mailto:[email protected]) for assistance with custom subdirectory setup. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,88 +1,53 @@ | ||
| --- | ||
| title: 'Introduction' | ||
| description: 'Give your users a personalized docs experience' | ||
| description: 'Personalize your docs with User Auth' | ||
| --- | ||
|
|
||
| User Auth allows you to identify and authenticate your users so that you can personalize docs content for them. Your users. | ||
| User Auth lets you identify and authenticate users to create personalized documentation experiences. | ||
|
|
||
| Example use cases: | ||
| ## Key Features | ||
|
|
||
| 1. **Customize MDX content** with a user's information, such as their name, plan, or title. | ||
| 1. **Custom Content** - Display user-specific information like names and plan details | ||
| 2. **API Integration** - Auto-fill API keys in the API Playground | ||
| 3. **Access Control** - Show/hide pages based on user groups | ||
|
|
||
| 2. **Prefill API keys** in the API Playground for streamlined use. | ||
| ## What User Auth Is Not | ||
|
|
||
| 3. **Selectively show pages** in the navigation based on a user's groups. | ||
| 1. **Not for Private Docs** - Pages remain accessible via direct URLs | ||
| 2. **Not a User Database** - Mintlify doesn't store user data | ||
|
|
||
| ## What *isn't* User Auth | ||
| <Note>Need private docs? [Contact our team](mailto:[email protected]) for solutions.</Note> | ||
|
|
||
| At this time, User Auth is not meant for the following use cases: | ||
| ## Using User Auth | ||
|
|
||
| 1. **Private docs content.** While you can hide pages from unauthenticated users, those pages are still accessible by anyone who can guess the URL. If your documentation contains sensitive information, User Auth is not enough to hide it. | ||
| ### Personalizing Content | ||
|
|
||
| 2. **A Mintlify-backed user database.** Mintlify does not store *any* information about your users. Rather, it relies on your existing infrastructure to serve as the source-of-truth for user data. | ||
|
|
||
| <Note>If you are interested in private docs content, [contact our team](mailto:[email protected]) to explore solutions.</Note> | ||
|
|
||
| ## How to Use | ||
|
|
||
| ### Customizing MDX Content | ||
|
|
||
| When writing content, you can use the `userContext` variable to access the information you have sent to your docs. Here's a simple example: | ||
|
|
||
| Hello, {userContext.name ?? 'reader'}! | ||
| Access user information through the `userContext` variable: | ||
|
|
||
| ```jsx | ||
| Hello, {userContext.name ?? 'reader'}! | ||
| ``` | ||
| This feature becomes even more powerful when paired with custom data about the user. Here's a real world example that allows us to give specific instructions on how to access the User Auth feature based on the customer's existing plan: | ||
| User Auth is an enterprise feature. { | ||
| userContext.org === undefined | ||
| ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</> | ||
| : userContext.org.plan !== 'enterprise' | ||
| ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</> | ||
| : <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</> | ||
| } | ||
| ```jsx | ||
| User Auth is an enterprise feature. { | ||
| userContext.org === undefined | ||
| ? <>To access this feature, first create an account at the <a href="https://dashboard.mintlify.com/login">Mintlify dashboard</a>.</> | ||
| : userContext.org.plan !== 'enterprise' | ||
| ? <>You are currently on the ${userContext.org.plan ?? 'free'} plan. To speak to our team about upgrading, <a href="mailto:[email protected]">contact our sales team</a>.</> | ||
| : <>To request this feature for your enterprise org, <a href="mailto:[email protected]">contact our team</a>.</> | ||
| } | ||
| ``` | ||
| <Note> | ||
| The information in `userContext` is only available after a user has logged in. For logged out users, the value of `userContext` will be `{}`. To prevent the page from crashing for logged-out users, always use optional chaining on your `userContext` fields, e.g. `{userContext.org?.plan}` | ||
| Always use optional chaining (e.g., `userContext.org?.plan`) since `userContext` is empty (`{}`) for logged-out users. | ||
| </Note> | ||
| ### Prefilling API Keys | ||
| ### API Key Integration | ||
| If you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Make sure the name of the field in the user info is an exact match of the name in the API Playground. | ||
| API Playground inputs are automatically prefilled when matching field names are provided in the user info. | ||
| ### Showing/Hiding Pages | ||
| ### Page Visibility Control | ||
| By default, every page is visible to every user. If you want to restrict which pages are visible to your users, you can add a `groups` field in your page metadata. | ||
| When determining which pages to show to the user, Mintlify will check which groups the user belongs to. | ||
| If the user is not in any of the groups listed in the page metadata, the page will not be shown. | ||
| Control page visibility using the `groups` field in page metadata: | ||
| ```md | ||
| --- | ||
| title: 'Managing Your Users' | ||
| description: 'Adding and removing users from your organization' | ||
| title: 'Example Page' | ||
| groups: ['admin'] | ||
| --- | ||
| ``` | ||
| Here's a table that displays whether a page is shown for different combinations of `groups` in UserInfo and page metadata: | ||
| | | `groups` not in UserInfo | `groups: []` in UserInfo | `groups: ['admin']` in UserInfo | | ||
| | :------------------------------ | :----------------------: | :----------------------: | :-----------------------------: | | ||
| | `groups` not in metadata | ✅ | ✅ | ✅ | | ||
| | `groups: []` in metadata | ❌ | ❌ | ❌ | | ||
| | `groups: ['admin']` in metadata | ❌ | ❌ | ✅ | | ||
| <Note>Note that an empty array in the page metadata is interpreted as "No groups should see this page."</Note> | ||
| Page visibility rules: | ||
| - No `groups` in metadata: Visible to all | ||
| - Empty `groups` array: Hidden from all | ||
| - Specific groups: Only visible to users in those groups |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.