Skip to content

Fix Grammar and Spelling in Documentation #491

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Fix Grammar and Spelling in Documentation #491

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 33 additions & 11 deletions mint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,11 +63,17 @@
{
"group": "Editing",
"icon": "pen-paintbrush",
"pages": ["development", "web-editor"]
"pages": [
"development",
"web-editor"
]
},
"settings/global",
"settings/navigation",
"migration"
"migration",
"web-editor",
"settings/github",
"settings/versioning"
]
},
{
Expand Down Expand Up @@ -124,7 +130,10 @@
{
"icon": "code",
"group": "Custom Scripts",
"pages": ["advanced/custom/css", "advanced/custom/js"]
"pages": [
"advanced/custom/css",
"advanced/custom/js"
]
},
{
"icon": "folder",
Expand All @@ -150,7 +159,8 @@
"settings/authentication-personalization/authentication-setup/password",
"settings/authentication-personalization/authentication-setup/jwt",
"settings/authentication-personalization/authentication-setup/oauth",
"settings/authentication-personalization/authentication-setup/mintlify"
"settings/authentication-personalization/authentication-setup/mintlify",
"settings/authentication-personalization/authentication-setup/jwt"
]
},
{
Expand All @@ -159,16 +169,20 @@
"settings/authentication-personalization/personalization-setup/choosing-a-handshake",
"settings/authentication-personalization/personalization-setup/shared-session",
"settings/authentication-personalization/personalization-setup/jwt",
"settings/authentication-personalization/personalization-setup/oauth"
"settings/authentication-personalization/personalization-setup/oauth",
"settings/authentication-personalization/personalization-setup/jwt"
]
},
"settings/authentication-personalization/sending-data"
"settings/authentication-personalization/sending-data",
"settings/authentication-personalization/personalization"
]
},
{
"icon": "plug",
"group": "Extensions",
"pages": ["advanced/widget/chat"]
"pages": [
"advanced/widget/chat"
]
},
{
"icon": "brackets-curly",
Expand Down Expand Up @@ -214,7 +228,10 @@
},
{
"group": "SDKs",
"pages": ["integrations/sdks/speakeasy", "integrations/sdks/stainless"]
"pages": [
"integrations/sdks/speakeasy",
"integrations/sdks/stainless"
]
},
{
"group": "Support",
Expand All @@ -226,7 +243,10 @@
},
{
"group": "Privacy",
"pages": ["integrations/privacy/overview", "integrations/privacy/osano"]
"pages": [
"integrations/privacy/overview",
"integrations/privacy/osano"
]
},
{
"group": "Components",
Expand Down Expand Up @@ -258,7 +278,9 @@
},
{
"group": "Changelog",
"pages": ["changelog/overview"]
"pages": [
"changelog/overview"
]
}
],
"footer": {
Expand Down Expand Up @@ -342,4 +364,4 @@
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
}
}
}
}
44 changes: 22 additions & 22 deletions settings/authentication-personalization/authentication-setup/jwt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,45 +4,45 @@ description: 'Use a customized login flow to authenticate users'
---

<Info>
This is the documentation for the JWT **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
This is the documentation for the JSON Web Token (JWT) **Authentication** Handshake. The steps for setting up the [JWT **Personalization** Handshake](/settings/authentication-personalization/personalization-setup/jwt) are slightly different.
</Info>

If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.
If you don't have a dashboard or want to keep your dashboard and docs completely separate, you can use your own login flow to authenticate users via a JWT in the URL.

## Implementation

<Steps>
<Step title="Generate a private key">
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
Navigate to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key in a secure location where your backend can access it.
</Step>
<Step title="Create a login flow">
Create a login flow that does the following:
- Authenticate the user
- Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- Sign the JWT with the secret key, using the EdDSA algorithm
- Create a redirect URL back to the `/login/jwt-callback` path of your docs, including the JWT as the hash
Create a login flow that performs the following steps:
- Authenticates the user
- Creates a JWT containing the authenticated user's info in the [User](../sending-data) format
- Signs the JWT with the secret key using the EdDSA algorithm
- Creates a redirect URL to the `/login/jwt-callback` path of your docs, including the JWT as the hash
</Step>
<Step title="Configure your Authentication settings">
Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Authentication settings.
Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and provide the login URL in your Authentication settings.
</Step>
</Steps>

## Example

I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
to be completely separate from my dashboard (or I don’t have a dashboard at all).
Let's say you want to set up authentication for your docs hosted at `docs.foo.com`. You want your docs to be completely separate from your dashboard (or you don't have a dashboard).

To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
for my users. At the end of this login flow, once I have verified the identity of the user,
I create a JWT containing the user’s custom data according to Mintlify’s specification.
I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
form `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`, and redirect the user.
To set up authentication with Mintlify:

I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
Login URL field.
1. Generate a JWT secret from your Mintlify dashboard
2. Create a web URL at `https://foo.com/docs-login` that initiates a login flow for your users
3. At the end of this login flow, after verifying the user's identity:
- Create a JWT containing the user's custom data according to Mintlify's specification
- Use a JWT library to sign the JWT with your Mintlify secret
- Create a redirect URL in the format `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`
- Redirect the user to this URL
4. Configure the Mintlify dashboard settings by entering `https://foo.com/docs-login` as the Login URL

Here's what the code might look like:
Here's example code showing how to implement this:

<CodeGroup>
```ts TypeScript
Expand Down Expand Up @@ -86,7 +86,7 @@ async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # 10 second JWT expiration
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 1 week session expiration
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # 2 week session expiration
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
Expand All @@ -99,4 +99,4 @@ async def return_mintlify_auth_status(current_user):

return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
```
</CodeGroup>
</CodeGroup>
45 changes: 20 additions & 25 deletions settings/authentication-personalization/personalization-setup/jwt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,20 @@ description: 'Use a customized login flow to authenticate users'
This is the documentation for the JWT **Personalization** Handshake. The steps for setting up the [JWT **Authentication** Handshake](/settings/authentication-personalization/authentication-setup/jwt) are slightly different.
</Info>


If you don’t have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user info to your docs via a JWT in the URL.
If you don't have a dashboard, or if you want to keep your dashboard and docs completely separate, you can use your own login flow to send user information to your docs via a JWT (JSON Web Token) in the URL.

## Implementation

<Steps>
<Step title="Generate a private key">
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key somewhere secure where it can be accessed by your backend.
Go to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and generate a private key. Store this key in a secure location where it can be accessed by your backend.
</Step>
<Step title="Create a login flow">
Create a login flow that does the following:
- Authenticate the user
- Create a JWT containing the authenticated user's info in the [User](../sending-data) format
- Sign the JWT with the secret key, using the EdDSA algorithm
- Create a redirect URL back to your docs, including the JWT as the hash
Create a login flow that performs the following actions:
- Authenticates the user
- Creates a JWT containing the authenticated user's information in the [User](../sending-data) format
- Signs the JWT with the secret key using the EdDSA algorithm
- Creates a redirect URL back to your docs that includes the JWT as the hash parameter
</Step>
<Step title="Configure your Personalization settings">
Return to your [Mintlify dashboard settings](https://dashboard.mintlify.com/products/authentication) and add the login URL to your Personalization settings.
Expand All @@ -30,20 +29,18 @@ If you don’t have a dashboard, or if you want to keep your dashboard and docs

## Example

I want to set up authentication for my docs hosted at `docs.foo.com`. I want my docs
to be completely separate from my dashboard (or I don’t have a dashboard at all).
In this example, we'll set up authentication for docs hosted at `docs.foo.com`. We want the docs to be completely separate from the dashboard (or we don't have a dashboard at all).

To set up authentication with Mintlify, I go to my Mintlify dashboard and generate a
JWT secret. I create a web URL `https://foo.com/docs-login` that initiates a login flow
for my users. At the end of this login flow, once I have verified the identity of the user,
I create a JWT containing the user’s custom data according to Mintlify’s specification.
I use a JWT library to sign this JWT with my Mintlify secret, create a redirect URL of the
form `https://docs.foo.com#{SIGNED_JWT}`, and redirect the user.
To set up authentication with Mintlify:

I then go to the Mintlify dashboard settings and enter `https://foo.com/docs-login` for the
Login URL field.
1. First, generate a JWT secret from the Mintlify dashboard
2. Create a web URL at `https://foo.com/docs-login` that initiates a login flow for your users
3. After verifying the user's identity at the end of the login flow, create a JWT containing the user's custom data according to Mintlify's specification
4. Use a JWT library to sign the JWT with your Mintlify secret
5. Create a redirect URL in the format `https://docs.foo.com#{SIGNED_JWT}`
6. Configure the login URL (`https://foo.com/docs-login`) in the Mintlify dashboard settings

Here's what the code might look like:
Here's an example implementation:

```ts
import * as jose from 'jose';
Expand All @@ -70,14 +67,12 @@ export async function handleRequest(req: Request, res: Response) {

return res.redirect(`https://docs.foo.com#${jwt}`);
}

```

## Preserving Anchors

Post-login, if you'd like to redirect to a specific anchor on the page, you can use the following format to create the redirect URL: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.

Example:
After login, you can preserve specific anchor locations on the page by using a special URL format that includes both the JWT and the anchor parameter: `https://docs.foo.com/page#jwt={SIGNED_JWT}&anchor={ANCHOR}`.

- Original: `https://docs.foo.com/quickstart#step-one`
- Redirect: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
Examples:
- Original URL: `https://docs.foo.com/quickstart#step-one`
- Redirect URL with JWT: `https://docs.foo.com/quickstart#jwt={SIGNED_JWT}&anchor=step-one`
33 changes: 16 additions & 17 deletions settings/authentication-personalization/personalization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,28 @@ description: "A list of features unlocked with Personalization"
---

Personalization refers to a suite of features that allow you to customize your
documentation experience based on some information about the user. There are
documentation experience based on information about the user. There are
three major features of Personalization:

- **Customize MDX content** with a user's information, such as their name, plan, or title.
- **Customize MDX Content** with user information such as name, plan, or title.

- **Prefill API keys** in the API Playground for streamlined use.
- **Prefill API Keys** in the API Playground for streamlined usage.

- **Selectively show pages** in the navigation based on a user's groups.
- **Selectively Show Pages** in the navigation based on user groups.

## How to Use

### Customizing MDX Content

When writing content, you can use the `user` variable to access the information you have sent to your docs. Here's a simple example:
When writing content, you can use the `user` variable to access any information you have sent to your docs. Here's a simple example:

Hello, {user.name ?? 'reader'}!

```jsx
Hello, {user.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 Personalization feature based on the customer's existing plan:
This feature becomes even more powerful when paired with custom data about the user. Here's a real-world example that provides specific instructions about accessing the Personalization feature based on the customer's existing plan:

Personalization is an enterprise feature. {
user.org === undefined
Expand All @@ -46,21 +46,21 @@ Personalization is an enterprise feature. {
```

<Note>
The information in `user` is only available after a user has logged in. For
logged out users, the value of `user` will be `{}`. To prevent the page from
The information in the `user` object is only available after a user has logged in. For
logged-out users, the value of `user` will be `{}`. To prevent your page from
crashing for logged-out users, always use optional chaining on your `user`
fields, e.g. `{user.org?.plan}`
fields (e.g., `{user.org?.plan}`).
</Note>

### Prefilling API Keys

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.
When you return API Playground inputs in the user info, they will automatically be prefilled in the API Playground. Ensure that the field name in the user info exactly matches the name in the API Playground.

### Showing/Hiding Pages

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.
By default, every page is visible to every user. To restrict which pages are visible to your users, add a `groups` field in your page metadata.
When determining which pages to show to the user, Mintlify checks which groups the user belongs to.
If the user is not in any of the groups listed in the page metadata, that page will not be shown.

```md
---
Expand All @@ -70,7 +70,7 @@ groups: ["admin"]
---
```

Here's a table that displays whether a page is shown for different combinations of `groups` in User and page metadata:
This table shows whether a page is visible based on different combinations of `groups` in User and page metadata:

| | `groups` not in User | `groups: []` in User | `groups: ['admin']` in User |
| :------------------------------ | :------------------: | :------------------: | :-------------------------: |
Expand All @@ -79,6 +79,5 @@ Here's a table that displays whether a page is shown for different combinations
| `groups: ['admin']` in metadata | ❌ | ❌ | ✅ |

<Note>
Note that an empty array in the page metadata is interpreted as "No groups
should see this page."
</Note>
An empty array in the page metadata is interpreted as "No groups should see this page."
</Note>
Loading
Loading