diff --git a/.vale.ini b/.vale.ini index 8b66c6930..c6cca176e 100644 --- a/.vale.ini +++ b/.vale.ini @@ -22,8 +22,10 @@ Microsoft.Vocab = NO Microsoft.Spacing = NO Microsoft.Semicolon = NO # Mostly just picks up code Microsoft.SentenceLength = NO # Mostly just picks up code +Microsoft.Ellipses = NO # Mostly just picks up code Microsoft.Dashes = NO Microsoft.Foreign = NO +Microsoft.Plurals = NO # Not relevant for Fern audience Microsoft.GeneralURL = NO diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 8fab0bc23..4884cbf90 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -75,3 +75,12 @@ exceptions: - OpenRPC - gRPC - RPC + - MCP + - JWT + - PUT + - GET + - POST + - IDE + - RBAC + - SAML + - OIDC diff --git a/.vale/styles/FernStyles/Current.yml b/.vale/styles/FernStyles/Current.yml index 0a5313b82..017088720 100644 --- a/.vale/styles/FernStyles/Current.yml +++ b/.vale/styles/FernStyles/Current.yml @@ -13,6 +13,5 @@ tokens: - today - soon - latest - - new - upcoming - old \ No newline at end of file diff --git a/.vale/styles/FernStyles/Ellipses.yml b/.vale/styles/FernStyles/Ellipses.yml deleted file mode 100644 index 6a00a613b..000000000 --- a/.vale/styles/FernStyles/Ellipses.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: existence -message: "In general, don't use an ellipsis." -link: https://docs.microsoft.com/en-us/style-guide/punctuation/ellipses -nonword: true -level: suggestion -action: - name: remove -tokens: - - '\.\.\.' diff --git a/.vale/styles/FernStyles/FirstPerson.yml b/.vale/styles/FernStyles/FirstPerson.yml index 2b10b23ec..bc6e27a2f 100644 --- a/.vale/styles/FernStyles/FirstPerson.yml +++ b/.vale/styles/FernStyles/FirstPerson.yml @@ -12,5 +12,4 @@ tokens: - \bI'm\b - \bI've\b - \bme\b - - \bmy\b - \bmine\b diff --git a/.vale/styles/FernStyles/We.yml b/.vale/styles/FernStyles/We.yml index b5ebdaef9..ef5f068bf 100644 --- a/.vale/styles/FernStyles/We.yml +++ b/.vale/styles/FernStyles/We.yml @@ -7,5 +7,4 @@ tokens: - we - we'(?:ve|re) - ours? - - us - let's diff --git a/fern/products/docs/pages/api-references/api-ref-content.mdx b/fern/products/docs/pages/api-references/api-ref-content.mdx index 63ee37f5b..4bee37263 100644 --- a/fern/products/docs/pages/api-references/api-ref-content.mdx +++ b/fern/products/docs/pages/api-references/api-ref-content.mdx @@ -55,7 +55,7 @@ By including the `summary` field, the `API Reference` section title will link to ## Adding Markdown content between endpoints -In addition to adding Markdown content to individual endpoints, you can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints. +You can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints. This feature requires you to use the `layout` field in your `docs.yml` file, which is described in the [Customize your API Reference](/learn/docs/api-references/customize-api-reference-layout) guide. diff --git a/fern/products/docs/pages/api-references/autopopulate-api-key.mdx b/fern/products/docs/pages/api-references/autopopulate-api-key.mdx index 7faaa76aa..0bea7e9dd 100644 --- a/fern/products/docs/pages/api-references/autopopulate-api-key.mdx +++ b/fern/products/docs/pages/api-references/autopopulate-api-key.mdx @@ -1,5 +1,5 @@ --- -title: Auto-populate API keys +title: Autopopulate API keys subtitle: Make integrating with your API frictionless by adding your login flow to the API Explorer. --- @@ -25,9 +25,9 @@ API key injection can work in two different ways depending on your company's aut To enable this feature, you need to configure authentication so that Fern can securely retrieve API keys for your users. The process works as follows: -1. When a user clicks the "Login" button in the API Explorer, they are redirected to your authentication page. +1. When a user clicks the "Login" button in the API Explorer, they're redirected to your authentication page. 2. After successful authentication, your system must set a cookie called `fern_token` in the user's browser. -3. This token should be a [JWT](https://jwt.io) encrypted with a secret key that we provide. The JWT should contain the user's API key. +3. This token should be a [JWT](https://jwt.io) encrypted with a secret key from Fern. The JWT should contain the user's API key. The JWT should have a structure similar to: @@ -89,13 +89,13 @@ The JWT should have a structure similar to: -#### Setting up auto-populated API keys +#### Setting up autopopulated API keys - [ ] Reach out to Fern to get your secret key - [ ] Send Fern the URL of your authentication page. This is where users will be redirected to after clicking the "Login" button in the API Explorer. - [ ] Add logic to your service to set the `fern_token` cookie when a user logs in -For an example of how to set up the `fern_token` cookie, see our demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts). +For an example of how to set up the `fern_token` cookie, see this demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts). @@ -113,7 +113,7 @@ To enable this feature, you need to configure OAuth authentication so that Fern -#### Setting up auto-populated API keys +#### Setting up autopopulated API keys To enable API key injection, you'll need to: - [ ] Set up an authenticated account for Fern so Fern can authorize users on your behalf. diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx index efdb7b3f9..55c60f559 100644 --- a/fern/products/docs/pages/api-references/customize-api-ref.mdx +++ b/fern/products/docs/pages/api-references/customize-api-ref.mdx @@ -168,7 +168,7 @@ To customize the display of an endpoint, you can add a `title`. You can also use ### Hiding endpoints -You can hide an endpoint from the API reference by setting `hidden` to `true`. The endpoint will still be accessible at its URL. +You can hide an endpoint from the API Reference by setting `hidden` to `true`. The endpoint will still be accessible at its URL. @@ -267,7 +267,7 @@ navigation: ### Adding availability -You can set the availability for the entire API reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. +You can set the availability for the entire API Reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. ```yaml title="docs.yml" {3, 6} navigation: diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx index 5b6d3fd1f..9abc7d7bb 100644 --- a/fern/products/docs/pages/api-references/generate-api-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-api-ref.mdx @@ -19,7 +19,7 @@ navigation: | Property | Value | | ---------------- | ------------------------------------------------------------------------------------------------------- | | `api` (required) | Title of the API Reference Section | -| `api-name` | Name of the API we are referencing, if there are [multiple APIs](#include-more-than-one-api-reference) | +| `api-name` | Name of the API you're referencing, if there are [multiple APIs](#include-more-than-one-api-reference) | | `audiences` | List of [audiences](/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed in your API Reference | | `availability` | Set the [availability status](/learn/docs/api-references/customize-api-reference-layout#adding-availability) for the entire API Reference or specific sections | | `display-errors` | Displays error schemas in the API References | @@ -50,7 +50,7 @@ fern/ └─ api.yml # API definition ``` -For a simple setup without tabs, you can include multiple API references directly in your navigation: +For a simple setup without tabs, you can include multiple API References directly in your navigation: ```yaml title="docs.yml" navigation: @@ -60,7 +60,7 @@ navigation: api-name: garden-api # Matches folder name containing your API definition ``` -When using tabs, each API reference must be placed within a tab's `layout`: +When using tabs, each API Reference must be placed within a tab's `layout`: ```yaml title="docs.yml" {12, 17} tabs: diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx index bbb359805..e6f73ff31 100644 --- a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx @@ -1,9 +1,9 @@ --- title: Generate OpenRPC Reference -description: Learn how to generate and customize OpenRPC API reference documentation +description: Learn how to generate and customize OpenRPC API Reference documentation --- -Fern enables you to generate professional, interactive API reference documentation for your JSON-RPC APIs using the [OpenRPC](https://open-rpc.org/) specification. OpenRPC provides a standardized, machine-readable format for describing JSON-RPC 2.0 APIs, unlocking powerful documentation and code generation workflows. +Fern enables you to generate professional, interactive API Reference documentation for your JSON-RPC APIs using the [OpenRPC](https://open-rpc.org/) specification. OpenRPC provides a standardized, machine-readable format for describing JSON-RPC 2.0 APIs, unlocking powerful documentation and code generation workflows. Example of Alchemy's docs site}> Alchemy's OpenRPC API Reference Example diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx index ee6d80d82..cda9abaf9 100644 --- a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx +++ b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx @@ -1,11 +1,11 @@ --- title: Generate WebSocket Reference -description: Learn how to generate and customize WebSocket API reference documentation +description: Learn how to generate and customize WebSocket API Reference documentation --- -Fern generates WebSocket API reference documentation from your AsyncAPI specification or Fern Definition. The AsyncAPI specification describes message-driven APIs in a machine-readable format. Fern supports the [v2](https://www.asyncapi.com/docs/reference/specification/v2.x) and [v3](https://www.asyncapi.com/docs/reference/specification/v3.0.0) specifications. +Fern generates WebSocket API Reference documentation from your AsyncAPI specification or Fern Definition. The AsyncAPI specification describes message-driven APIs in a machine-readable format. Fern supports the [v2](https://www.asyncapi.com/docs/reference/specification/v2.x) and [v3](https://www.asyncapi.com/docs/reference/specification/v3.0.0) specifications. Example of how a WebSocket API Reference renders in Fern}> WebSocket API Reference Example diff --git a/fern/products/docs/pages/api-references/http-snippets.mdx b/fern/products/docs/pages/api-references/http-snippets.mdx index b9ed30319..375168129 100644 --- a/fern/products/docs/pages/api-references/http-snippets.mdx +++ b/fern/products/docs/pages/api-references/http-snippets.mdx @@ -41,7 +41,7 @@ To generate HTTP snippets, add request examples to your API definition: ### Set default snippet language -HTTP snippets support several languages. Our development work is driven by customer requests, so please request support for languages not listed here by [opening an issue](https://github.com/fern-api/fern/issues/new/choose). +HTTP snippets support several languages. Fern development work is driven by customer requests – request support for languages not listed here by [opening an issue](https://github.com/fern-api/fern/issues/new/choose). * csharp * curl diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx index 245708f06..f960ee41f 100644 --- a/fern/products/docs/pages/api-references/sdk-snippets.mdx +++ b/fern/products/docs/pages/api-references/sdk-snippets.mdx @@ -23,7 +23,7 @@ To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and ### Add examples to your API definition -In order to generate code snippets, Fern needs to read request examples from your API definition. If you're using a Fern Definition, you can follow [these instructions](/learn/api-definition/fern/examples). If you're using an OpenAPI Specification, you can follow [these instructions](https://swagger.io/docs/specification/adding-examples/). +Fern needs to read request examples from your API definition to generate code snippets. If you're using a Fern Definition, you can follow [these instructions](/learn/api-definition/fern/examples). If you're using an OpenAPI Specification, you can follow [these instructions](https://swagger.io/docs/specification/adding-examples/). ### Define a package name for your SDK(s) @@ -112,7 +112,7 @@ navigation: ### Trigger generation -As the final step, trigger your docs generation by running `fern generate --docs` locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will now appear via a dropdown! +As the final step, trigger your docs generation by running `fern generate --docs` locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will appear via a dropdown! ### Set default snippet language diff --git a/fern/products/docs/pages/authentication/overview.mdx b/fern/products/docs/pages/authentication/overview.mdx index 7230530a2..77d38572b 100644 --- a/fern/products/docs/pages/authentication/overview.mdx +++ b/fern/products/docs/pages/authentication/overview.mdx @@ -5,14 +5,12 @@ description: Understand the different authentication options Fern offers Fern offers two methods of authentication, Single Sign-On (SSO) and Role-Based Access Control (RBAC). -**For most situations, we recommend using RBAC** for granular access control over your documentation. RBAC works well for sites with multiple audiences (internal teams, partners, customers) and supports API key injection to auto-populate code examples. +**For most situations, use RBAC** for granular access control over your documentation. RBAC works well for sites with multiple audiences (internal teams, partners, customers) and supports API key injection to autopopulate code examples. API key injection can be set up using either JWT or OAuth, depending on your existing authentication system. **SSO is simpler** but only provides basic login functionality - it doesn't support RBAC or API key injection. SSO works well for internal-only documentation where everyone should see the same content. - - Learn more about Fern's authentication options: diff --git a/fern/products/docs/pages/authentication/rbac.mdx b/fern/products/docs/pages/authentication/rbac.mdx index 338a7967a..beedd8570 100644 --- a/fern/products/docs/pages/authentication/rbac.mdx +++ b/fern/products/docs/pages/authentication/rbac.mdx @@ -46,7 +46,7 @@ roles: ### Configure authentication via a `fern_token` -Fern uses a browser cookie called `fern_token` to identify authenticated users and their roles. If this cookie is not present when a user tries to access restricted content, Fern redirects them to your login page. +Fern uses a browser cookie called `fern_token` to identify authenticated users and their roles. If this cookie isn't present when a user tries to access restricted content, Fern redirects them to your login page. You can set up this authentication using either JWT or OAuth: diff --git a/fern/products/docs/pages/authentication/set-up-oauth.mdx b/fern/products/docs/pages/authentication/set-up-oauth.mdx index 14d82e7d4..284197568 100644 --- a/fern/products/docs/pages/authentication/set-up-oauth.mdx +++ b/fern/products/docs/pages/authentication/set-up-oauth.mdx @@ -61,7 +61,7 @@ Add a custom claim to your OAuth provider's token response. This claim will be u ``` -Some OAuth providers have strict requirements for custom claims. If you need to use a claim other than `roles`, please reach out to Fern and specify which claim should be parsed for the user's roles. +Some OAuth providers have strict requirements for custom claims. If you need to use a claim other than `roles`, reach out to Fern and specify which claim should be parsed for the user's roles. @@ -86,7 +86,7 @@ To add a custom claim to Auth0, you need to create a **custom action**. This act 6. Add the action to your **Post Login Flow**. -If you are using a different OAuth provider, please reach out to Fern with any questions on setting up a custom claim. +If you are using a different OAuth provider, reach out to Fern with any questions on setting up a custom claim.