From 3d91632031af25c9bbfd04cadc3877f3c549e1b6 Mon Sep 17 00:00:00 2001 From: Minae Lee Date: Wed, 21 Feb 2024 19:30:49 -0700 Subject: [PATCH] docs: add titles and descs to frontmatter in Fern's documentation pages (#3006) * docs: add title and desc to introduction.mdx * docs: add title and desc to import.mdx * docs: add title and desc to examples.mdx * docs: add title and desc to why-fern.mdx * docs: add title and desc to extensions.mdx * docs: add title and desc to export.mdx * docs: add title and desc to go-sdk.mdx * docs: add title and desc to python-sdk.mdx * docs: add title and desc to java-sdk.mdx * docs: add title and desc to node-sdk.mdx * docs: add title and desc to postman-collection.mdx * docs: add title and desc to php-sdk.mdx * docs: add title and desc to csharp-sdk.mdx * docs: add comma * docs: add comma * docs: update desc wording in node-sdk.mdx * docs: reword desc in java-sdk.mdx * docs: add title and desc to ruby-sdk.mdx * docs: add title and desc to browser-sdk.mdx * docs: add title and desc to publish-to-maven-central.mdx * docs: add title and desc to writing-content.mdx * docs: add title and desc to snippets.mdx * docs: add title and desc to previews.mdx * docs: add title and desc to endpoint-errors.mdx * docs: add title and desc to custom-domain.mdx * docs: add title and desc to configurations-overview.mdx * docs: add title and desc to audiences.mdx * docs: add title and desc to availability.mdx * docs: update frontmatter and content of availability.mdx - realized that some of the content is an unintentional copy from Callout.mdx, fixed * docs: add title and desc to callout.mdx * docs: add title and desc to card.mdx * docs: add title and desc to codeblock.mdx * docs: add title and desc to icons.mdx --- fern/docs/pages/docs/audiences.mdx | 5 +++++ fern/docs/pages/docs/components/availability.mdx | 7 ++++++- fern/docs/pages/docs/components/callout.mdx | 10 ++++++++-- fern/docs/pages/docs/components/card.mdx | 8 +++++++- fern/docs/pages/docs/components/codeblock.mdx | 8 +++++++- fern/docs/pages/docs/components/icons.mdx | 6 ++++++ fern/docs/pages/docs/configurations-overview.mdx | 8 +++++++- fern/docs/pages/docs/custom-domain.mdx | 6 ++++++ fern/docs/pages/docs/endpoint-errors.mdx | 5 +++++ fern/docs/pages/docs/previews.mdx | 9 ++++++++- fern/docs/pages/docs/snippets.mdx | 7 ++++++- fern/docs/pages/docs/writing-content.mdx | 7 +++++++ fern/docs/pages/guides/publish-to-maven-central.mdx | 6 +++++- fern/docs/pages/openapi/export.mdx | 7 ++++++- fern/docs/pages/openapi/extensions.mdx | 4 ++++ fern/docs/pages/sdks/browser-sdk.mdx | 5 +++++ fern/docs/pages/sdks/csharp-sdk.mdx | 5 +++++ fern/docs/pages/sdks/go-sdk.mdx | 5 +++++ fern/docs/pages/sdks/java-sdk.mdx | 5 +++++ fern/docs/pages/sdks/node-sdk.mdx | 5 +++++ fern/docs/pages/sdks/php-sdk.mdx | 5 +++++ fern/docs/pages/sdks/postman-collection.mdx | 5 +++++ fern/docs/pages/sdks/python-sdk.mdx | 5 +++++ fern/docs/pages/sdks/ruby-sdk.mdx | 5 +++++ fern/docs/pages/welcome/introduction.mdx | 8 ++++++-- 25 files changed, 144 insertions(+), 12 deletions(-) diff --git a/fern/docs/pages/docs/audiences.mdx b/fern/docs/pages/docs/audiences.mdx index abd7b7f0b77..0a064e8d2c3 100644 --- a/fern/docs/pages/docs/audiences.mdx +++ b/fern/docs/pages/docs/audiences.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | Configuring audiences for different consumer groups +description: Segment your API documentation for different consumers, called 'Audiences'. For example, you can publish a subset of your docs to the 'public' Audience. +--- + [Audiences](/api-definition/fern-definition/audiences) are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. The following example shows how to configure your `docs.yml` to publish documentation for the `public` audience. diff --git a/fern/docs/pages/docs/components/availability.mdx b/fern/docs/pages/docs/components/availability.mdx index bc128393fb8..947536e4aeb 100644 --- a/fern/docs/pages/docs/components/availability.mdx +++ b/fern/docs/pages/docs/components/availability.mdx @@ -1,4 +1,9 @@ -The `Availability Component` is used when you want to visually highlight important content for the user. +--- +title: Fern | Indicate the Availability of an endpoint +description: Indicate the status of an endpoint using the Availability component. Display whether the endpoint is in beta, generally available, or deprecated. +--- + +The `Availability` component is used to indicate the availability status of an endpoint. Availability Prop: diff --git a/fern/docs/pages/docs/components/callout.mdx b/fern/docs/pages/docs/components/callout.mdx index ca2fdc9cb02..ca295d37290 100644 --- a/fern/docs/pages/docs/components/callout.mdx +++ b/fern/docs/pages/docs/components/callout.mdx @@ -1,4 +1,10 @@ -The `Callout Component` is used when you want to visually highlight important content for the user. There are different props available to design callout component properly. +--- +title: Fern | Highlight content with the Callout component +description: Use the Callout component to visually highlight important content within your documentation. Configure the 'intent' as 'info', 'success', or 'warn'. +--- + + +The `Callout` component is used when you want to visually highlight important content for the user. There are different props available to design callout component properly. Note: it is helpful to add a `
` after the callout component to ensure that the next component is not too close to the callout. @@ -54,4 +60,4 @@ This is a warn callout. This is a warn callout. ``` - \ No newline at end of file + diff --git a/fern/docs/pages/docs/components/card.mdx b/fern/docs/pages/docs/components/card.mdx index 02a1346580b..b3ffb420d11 100644 --- a/fern/docs/pages/docs/components/card.mdx +++ b/fern/docs/pages/docs/components/card.mdx @@ -1,4 +1,10 @@ -The `Card` is used when you want to display content in a rectangular box. +--- +title: Fern | Use the Card component to display content in a box +description: The Card component displays content in a rectangular box, with an optional title, icon, and href (link). Create a grid of boxes using the Cards component. +--- + + +The `Card` component is used when you want to display content in a rectangular box. Card Prop: diff --git a/fern/docs/pages/docs/components/codeblock.mdx b/fern/docs/pages/docs/components/codeblock.mdx index dfbf1849a52..90376ed56a6 100644 --- a/fern/docs/pages/docs/components/codeblock.mdx +++ b/fern/docs/pages/docs/components/codeblock.mdx @@ -1,4 +1,10 @@ -The `CodeBlock` is used when you want to display a code snippet. +--- +title: Fern | Display code snippets using the CodeBlock component +description: The CodeBlock component displays a code snippet, with an optional title and language. Use the CodeBlocks component to show multiple snippets in a tabbed view. +--- + + +The `CodeBlock` component is used when you want to display a code snippet. CodeBlock Props: diff --git a/fern/docs/pages/docs/components/icons.mdx b/fern/docs/pages/docs/components/icons.mdx index a4283610257..92ac686e86a 100644 --- a/fern/docs/pages/docs/components/icons.mdx +++ b/fern/docs/pages/docs/components/icons.mdx @@ -1,3 +1,9 @@ +--- +title: Fern | Using Font Awesome icons or custom icons in Fern Docs +description: Use and style the 26,000+ icons available in the Font Awesome icon library in your Fern Docs. Fern also supports custom icons on its Business plan. +--- + + [Font Awesome](https://fontawesome.com/) is the Internet's icon library and toolkit, used by millions of designers, developers, and content creators. We use Font Awesome to power the icons within Fern Docs. You can pick from the 26,000+ icons available and then apply a style, color, size, or animation to them. diff --git a/fern/docs/pages/docs/configurations-overview.mdx b/fern/docs/pages/docs/configurations-overview.mdx index d5c057c53a8..e6c99b4b8db 100644 --- a/fern/docs/pages/docs/configurations-overview.mdx +++ b/fern/docs/pages/docs/configurations-overview.mdx @@ -1,5 +1,11 @@ +--- +title: Fern | Overview of available documentation configurations +description: Links to configurations for your Fern Docs site, including a custom domain, pull request previews, SDK snippets, audiences, and display of endpoint errors. +--- + + - [Custom domain.](/generate-docs/configurations/custom-domain) Bring your own custom domain to Fern Docs. - [Pull request previews.](/generate-docs/configurations/pull-request-previews) Preview changes from pull requests before merging code to a production branch. - [SDK Snippets.](/generate-docs/configurations/sdk-snippets) Add SDK code snippets in different languages to your documentation. - [Audiences.](/generate-docs/configurations/audiences) Configure your Fern Docs to publish documentation specific to different `Audiences`. -- [Endpoints errors.](/generate-docs/configurations/endpoint-errors) Enables errors to show up in your documentation. +- [Endpoint errors.](/generate-docs/configurations/endpoint-errors) Enables errors to show up in your documentation. diff --git a/fern/docs/pages/docs/custom-domain.mdx b/fern/docs/pages/docs/custom-domain.mdx index b86dd44090a..106b2972ace 100644 --- a/fern/docs/pages/docs/custom-domain.mdx +++ b/fern/docs/pages/docs/custom-domain.mdx @@ -1,3 +1,9 @@ +--- +title: Fern | Bring your custom domain to your Fern Docs +description: Learn how you can set up your Fern-generated documentation site to use a custom domain or subdomain. +--- + + Learn how to bring your own custom domain to Fern Docs. diff --git a/fern/docs/pages/docs/endpoint-errors.mdx b/fern/docs/pages/docs/endpoint-errors.mdx index 016452fba5e..70b54d5f48c 100644 --- a/fern/docs/pages/docs/endpoint-errors.mdx +++ b/fern/docs/pages/docs/endpoint-errors.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | Endpoint errors configuration and example +description: Enable errors to show up on the endpoint pages of your documentation, from the error names, codes, and objects returned configured in your API definition. +--- + This configuration enables errors to show up on the endpoint pages of your documentation. The error names, codes, and objects returned are configured in your API definition. ## Configuration diff --git a/fern/docs/pages/docs/previews.mdx b/fern/docs/pages/docs/previews.mdx index f25a9895a65..8794522d801 100644 --- a/fern/docs/pages/docs/previews.mdx +++ b/fern/docs/pages/docs/previews.mdx @@ -1,3 +1,10 @@ +--- +title: Fern | Pull request previews of docs changes before merge +description: Fern's PR previews feature lets you preview changes to your docs from pull requests before merging to the live docs site. Use manually or in GitHub Actions. +--- + + + `PR previews` offer a way to preview changes from pull requests (PRs) before merging code to a production branch. This is useful for reviewing documentation changes before publishing them to your live documentation site. Here's an example of a `PR preview`: https://fern-preview-fa86d0dd-7763-4d5f-84d8-6d630dc1742a.docs.buildwithfern.com @@ -62,4 +69,4 @@ jobs: ## Link expiration -Preview links do not expire. However, the time to live (TTL) may be subject to change in the future. \ No newline at end of file +Preview links do not expire. However, the time to live (TTL) may be subject to change in the future. diff --git a/fern/docs/pages/docs/snippets.mdx b/fern/docs/pages/docs/snippets.mdx index 5151535f0ec..cf7e7818a14 100644 --- a/fern/docs/pages/docs/snippets.mdx +++ b/fern/docs/pages/docs/snippets.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | Add SDK code snippets to your documentation +description: From examples in your API definition, Fern generates SDK code sample snippets in cURL and other languages that are automatically populated in your Fern Docs. +--- + Fern allows you to add SDK code snippets to your documentation. This is useful for showing how to use your SDK in different languages. By default, Fern will generate cURL snippets. By following the steps below, you can add code snippets for other languages. ![SDK code snippet selector](https://fern-image-hosting.s3.amazonaws.com/sdk-code-snippets.png) @@ -58,4 +63,4 @@ navigation: If you'd like to bring SDK snippets into your own documentation, you can use the [Snippets API](/api-reference/reference/snippets). API acces requires a a [SDK Business plan](https://buildwithfern.com/pricing). -Merge.dev is an example of a Fern customer that uses the Snippets API to bring Python code samples [into their API Reference](https://docs.merge.dev/hris/employees/#employees_list). \ No newline at end of file +Merge.dev is an example of a Fern customer that uses the Snippets API to bring Python code samples [into their API Reference](https://docs.merge.dev/hris/employees/#employees_list). diff --git a/fern/docs/pages/docs/writing-content.mdx b/fern/docs/pages/docs/writing-content.mdx index 346e6bbcf57..6e4052b1d62 100644 --- a/fern/docs/pages/docs/writing-content.mdx +++ b/fern/docs/pages/docs/writing-content.mdx @@ -1,3 +1,10 @@ +--- +title: Fern | Write and customize content in docs built with Fern +description: Add content with Markdown and MDX. Use Fern's custom components and frontmatter. Customize navigation and styles. Add an automatically generated API Reference. +--- + + + ## Add content with Markdown or MDX files Add pages manually to your documentation by creating [Markdown](https://www.markdownguide.org/) (`.md`) or [MDX](https://mdxjs.com/) (`.mdx`) files and linking to them in [docs.yml](#configure-your-site-with-docs-yml). diff --git a/fern/docs/pages/guides/publish-to-maven-central.mdx b/fern/docs/pages/guides/publish-to-maven-central.mdx index 97204d6ca13..91730842a53 100644 --- a/fern/docs/pages/guides/publish-to-maven-central.mdx +++ b/fern/docs/pages/guides/publish-to-maven-central.mdx @@ -1,3 +1,7 @@ +--- +title: Fern | How to publish your Java SDK as an artifact to Maven Central +description: A guide to publishing your SDK generated by Fern as an artifact to the public Maven Central repository. +--- The following is a guide on how to publish your SDK (referred to as an `artifact`) to Maven Central. ## Step 1: Decide what your Maven `groupId` will be . @@ -81,4 +85,4 @@ Going forward, when referencing the artifact you'll use the `groupId` and `artif - `com.stripe:stripe-java` - `com.slack.api/slack-api-client` - `dev.merge:merge-java-client` -- `com.amazonaws:aws-java-sdk-s3` \ No newline at end of file +- `com.amazonaws:aws-java-sdk-s3` diff --git a/fern/docs/pages/openapi/export.mdx b/fern/docs/pages/openapi/export.mdx index be440698f14..c3554215e0c 100644 --- a/fern/docs/pages/openapi/export.mdx +++ b/fern/docs/pages/openapi/export.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | Export your API from Fern's format to OpenAPI +description: Use Fern's OpenAPI generator to convert your API defined using the Fern Definition format to an OpenAPI 3.1 specification file. +--- + To export your API to OpenAPI from Fern, you can use the `fern-openapi` generator. The OpenAPI generator outputs an OpenAPI 3.1 document for your API, which can be used with any OpenAPI-compatible tools. Here is an example of how you can configure the fern-openapi generator in your generators.yml file: @@ -33,4 +38,4 @@ When configured, the generator outputs OAS files in the specified format. **Default:** {} -When configured, the object is merged into the generated OAS file. This allows you to add custom fields to the specification. \ No newline at end of file +When configured, the object is merged into the generated OAS file. This allows you to add custom fields to the specification. diff --git a/fern/docs/pages/openapi/extensions.mdx b/fern/docs/pages/openapi/extensions.mdx index ae0b05bc0fb..b1348260ee4 100644 --- a/fern/docs/pages/openapi/extensions.mdx +++ b/fern/docs/pages/openapi/extensions.mdx @@ -1,3 +1,7 @@ +--- +title: Fern | Fern's custom OpenAPI extensions for higher-quality SDKs +description: Learn about Fern's OpenAPI extensions for SDK method names, authentication overrides, global headers, enum descriptions and names, audiences, and more. +--- Fern supports different OpenAPI extensions so that you can generate higher-quality SDKs. diff --git a/fern/docs/pages/sdks/browser-sdk.mdx b/fern/docs/pages/sdks/browser-sdk.mdx index b0f7adde08d..cf70e589f26 100644 --- a/fern/docs/pages/sdks/browser-sdk.mdx +++ b/fern/docs/pages/sdks/browser-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's TypeScript Browser SDK Generator +description: Use Fern's TypeScript Browser SDK generator and your API definition to output a fully functional Browser SDK locally, or publish it privately or to NPM. +--- + [Source code](https://github.com/fern-api/fern-typescript) **Latest version**: `0.9.5` diff --git a/fern/docs/pages/sdks/csharp-sdk.mdx b/fern/docs/pages/sdks/csharp-sdk.mdx index c682526da5f..3521c61e6c2 100644 --- a/fern/docs/pages/sdks/csharp-sdk.mdx +++ b/fern/docs/pages/sdks/csharp-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's C# SDK Generator +description: Use Fern's C# SDK generator and your API definition to output a fully functional C# SDK (client libraries) to your local filesystem, or publish it to NuGet. +--- + Latest version: `0.0.0` diff --git a/fern/docs/pages/sdks/go-sdk.mdx b/fern/docs/pages/sdks/go-sdk.mdx index 87cdf2d00cc..c2ded8e78bc 100644 --- a/fern/docs/pages/sdks/go-sdk.mdx +++ b/fern/docs/pages/sdks/go-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's Go SDK Generator +description: Use Fern's Go SDK generator and your API definition to output a fully functional Go SDK (client libraries) to your local filesystem, or publish it to GitHub. +--- + [Source code](https://github.com/fern-api/fern/tree/main/generators/go)
**Latest version**: `0.12.0` diff --git a/fern/docs/pages/sdks/java-sdk.mdx b/fern/docs/pages/sdks/java-sdk.mdx index af8539c3c3c..b26a967ebf4 100644 --- a/fern/docs/pages/sdks/java-sdk.mdx +++ b/fern/docs/pages/sdks/java-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's Java SDK Generator +description: Use Fern's Java SDK generator and your API definition to output a fully functional Java SDK locally, or publish it to a private or public Maven repository. +--- + [Source code](https://github.com/fern-api/fern/tree/main/generators/java)
**Latest version**: `0.6.1` diff --git a/fern/docs/pages/sdks/node-sdk.mdx b/fern/docs/pages/sdks/node-sdk.mdx index 26ce2a69611..902c6eee121 100644 --- a/fern/docs/pages/sdks/node-sdk.mdx +++ b/fern/docs/pages/sdks/node-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's TypeScript Node.js SDK Generator +description: Use Fern's TypeScript Node.js SDK generator and your API definition to output a fully functional SDK locally, and publish the package internally or to NPM. +--- + [Source code](https://github.com/fern-api/fern-typescript)
**Latest version**: `0.9.5` diff --git a/fern/docs/pages/sdks/php-sdk.mdx b/fern/docs/pages/sdks/php-sdk.mdx index ff37f7de46a..18e541ee70e 100644 --- a/fern/docs/pages/sdks/php-sdk.mdx +++ b/fern/docs/pages/sdks/php-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's PHP SDK Generator +description: Use Fern's PHP SDK generator and your API definition to output a fully functional PHP SDK (client libraries) to your local filesystem, or publicly to Packagist. +--- + Latest version: `0.0.0` diff --git a/fern/docs/pages/sdks/postman-collection.mdx b/fern/docs/pages/sdks/postman-collection.mdx index 43f1500966e..3b113368f80 100644 --- a/fern/docs/pages/sdks/postman-collection.mdx +++ b/fern/docs/pages/sdks/postman-collection.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's Postman Collection Generator +description: Use Fern's Postman Collection generator and your API definition to output a Postman Collection to your local filesystem, or publish it to Postman. +--- + [Source code](https://github.com/fern-api/fern/tree/main/generators/postman)
**Latest version**: `0.1.0` diff --git a/fern/docs/pages/sdks/python-sdk.mdx b/fern/docs/pages/sdks/python-sdk.mdx index ef44e6a9b20..3441550f09a 100644 --- a/fern/docs/pages/sdks/python-sdk.mdx +++ b/fern/docs/pages/sdks/python-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's Python SDK Generator +description: Use Fern's Python SDK generator and your API definition to output a fully functional Python SDK (client libraries) to your local filesystem, or publish it to GitHub. +--- + [Source code](https://github.com/fern-api/fern/tree/main/generators/python)
**Latest version**: `0.8.0` diff --git a/fern/docs/pages/sdks/ruby-sdk.mdx b/fern/docs/pages/sdks/ruby-sdk.mdx index 15d9d07ea73..ca4869c5b41 100644 --- a/fern/docs/pages/sdks/ruby-sdk.mdx +++ b/fern/docs/pages/sdks/ruby-sdk.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | How to use Fern's Ruby SDK Generator +description: Use Fern's Ruby SDK generator and your API definition to output a fully functional Ruby SDK (client libraries) locally, or publish it to RubyGems. +--- + [Source code](https://github.com/fern-api/fern/tree/main/generators/ruby) Latest version: `0.0.0` diff --git a/fern/docs/pages/welcome/introduction.mdx b/fern/docs/pages/welcome/introduction.mdx index 11ebad38ee0..48ecb72f32b 100644 --- a/fern/docs/pages/welcome/introduction.mdx +++ b/fern/docs/pages/welcome/introduction.mdx @@ -1,3 +1,8 @@ +--- +title: Fern | Introduction to the Fern toolkit for REST APIs +description: Define your API with OpenAPI or Fern's simpler format, then generate SDKs, server boilerplate, and a documentation website with an API Reference. +--- + Fern is a toolkit for building REST APIs. With Fern, you can generate SDKs, API documentation, and boilerplate for your backend server. Fern is **fully compatible with OpenAPI**. Leverage your existing OpenAPI @@ -14,6 +19,5 @@ OpenAPI, you can also use Fern's simpler format to define your API. The magic of Fern is our compiler, which transforms your API definition into: - **SDKs.** Client libraries that **feel handwritten** and are published to package managers like npm and PyPI. -- **Documentation.** A beautiful docs website with a best-in-class API Reference. Automatically sync your Postman Collection +- **Documentation.** A beautiful docs website with a best-in-class API Reference. Automatically sync your Postman Collection. - **Backend boilerplate.** Server side code, such as Pydantic models for FastAPI and Jersey interfaces for Spring Boot. Get compile-time validation that your endpoints are being served correctly. -