diff --git a/fern/products/docs/pages/getting-started/quickstart.mdx b/fern/products/docs/pages/getting-started/quickstart.mdx index b9c74c1c3..9013fc236 100644 --- a/fern/products/docs/pages/getting-started/quickstart.mdx +++ b/fern/products/docs/pages/getting-started/quickstart.mdx @@ -23,200 +23,217 @@ Or, follow this guide to get started with Fern using the CLI. + Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line: - Install the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) so you can manage your project from the command line: + ```bash + npm install -g fern-api + ``` - ```bash - npm install -g fern-api - ``` + ### Just testing! - - All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch + + All the configuration for your docs lives in the `fern` folder. Create a fern folder by either using the [starter template](https://github.com/fern-api/docs-starter) or starting from scratch + Use the `fern-api/docs-starter` repository as a template for your site: - Use the `fern-api/docs-starter` repository as a template for your site: - 1. Navigate to [fern-api/docs-starter](https://github.com/fern-api/docs-starter) and click on the **Use this template** button (found at the top right of this page). You must be logged into GitHub. - 2. Choose the option to **create a new repository**. Name it `fern-docs`. - 3. Clone your newly created repository and open it in your favorite code editor (e.g., Cursor, VS Code). + 1. Navigate to [fern-api/docs-starter](https://github.com/fern-api/docs-starter) and click on the **Use this template** button (found at the top right of this page). You must be logged into GitHub. + 2. Choose the option to **create a new repository**. Name it `fern-docs`. + 3. Clone your newly created repository and open it in your favorite code editor (e.g., Cursor, VS Code). + + ```bash title="SSH" + git clone git@github.com:fern-api/docs-starter.git + ``` - - ```bash title="SSH" - git clone git@github.com:fern-api/docs-starter.git - ``` - ```bash title="HTTPS" - git clone https://github.com/fern-api/docs-starter.git - ``` - - - You'll see a basic site with a `fern` folder that contains an API definition, Markdown pages, and configuration files. [View the live example](https://plantstore.dev/welcome) to see what the starter template looks like when published. You can use these files to test out Fern's features, or replace them with your own files. - - - - - - - - - - - - - - - - - + ```bash title="HTTPS" + git clone https://github.com/fern-api/docs-starter.git + ``` + + + You'll see a basic site with a `fern` folder that contains an API definition, Markdown pages, and configuration files. [View the live example](https://plantstore.dev/welcome) to see what the starter template looks like when published. You can use these files to test out Fern's features, or replace them with your own files. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - + + + + + ```bash + fern init --docs + ``` - ```bash - fern init --docs - ``` + You'll see a new `fern` folder in your project with the following configuration files (but no additional Markdown or API definition files): - You'll see a new `fern` folder in your project with the following configuration files (but no additional Markdown or API definition files): + + + - - - - - - + + + - - - Configure two settings (these values don't have to match): + - - **Organization name** in `fern.config.json`: Identifies your organization in the Fern system (including the [Fern Dashboard](https://dashboard.buildwithfern.com/)) - - **Docs URL** in `docs.yml`: Determines where your docs are published + + Configure two settings (these values don't have to match): + * **Organization name** in `fern.config.json`: Identifies your organization in the Fern system (including the [Fern Dashboard](https://dashboard.buildwithfern.com/)) + * **Docs URL** in `docs.yml`: Determines where your docs are published - ```json {2} - { - "organization": "{{YOUR_ORGANIZATION}}", - "version": "" - } - ``` + ```json {2} + { + "organization": "{{YOUR_ORGANIZATION}}", + "version": "" + } + ``` + - ```yml {2} - instances: - - url: {{YOUR_DOMAIN}}.docs.buildwithfern.com - ``` + ```yml {2} + instances: + - url: {{YOUR_DOMAIN}}.docs.buildwithfern.com + ``` - Use only alphanumeric characters, hyphens, and underscores for both values. + Use only alphanumeric characters, hyphens, and underscores for both values. + - - Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).) + + Now that you have a basic docs site, you can customize it by adding tutorials, generating an API Reference, or finetuning the branding. (Or skip ahead to [preview](#preview-your-docs) and [publish](#publish-to-production).) - - - Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more. + + Create Markdown (`.mdx`) files and fill them in. Read the [Markdown basics](/learn/docs/writing-content/markdown-basics) documentation to learn more. - - Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. You can also create [reusable snippets](/learn/docs/writing-content/reusable-snippets) to share content across multiple pages. - + + Fern supports [GitHub flavored Markdown (GFM)](https://github.github.com/gfm/) within MDX files, no plugin required. You can also create [reusable snippets](/learn/docs/writing-content/reusable-snippets) to share content across multiple pages. + - ```markdown docs/pages/hello-world.mdx - --- - title: "Page Title" - description: "Subtitle (optional)" - --- + ```markdown docs/pages/hello-world.mdx + --- + title: "Page Title" + description: "Subtitle (optional)" + --- - Hello world! - ``` + Hello world! + ``` - Reference your new pages from your `docs.yml` file. You can reference the - Markdown page within a section or as a standalone page. - - ```yml docs.yml - navigation: - - page: Hello World - path: docs/pages/hello-world.mdx - - section: Overview - contents: - - page: Getting Started - path: docs/pages/getting-started.mdx - ``` + Reference your new pages from your `docs.yml` file. You can reference the + Markdown page within a section or as a standalone page. + + ```yml docs.yml + navigation: + - page: Hello World + path: docs/pages/hello-world.mdx + - section: Overview + contents: + - page: Getting Started + path: docs/pages/getting-started.mdx + ``` - - If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec: + + If you cloned the starter template, you already have an `openapi.yaml` file with sample API definitions. If you started from scratch, add your OpenAPI spec: - ```bash - fern init --openapi /path/to/openapi.yml - ``` + ```bash + fern init --openapi /path/to/openapi.yml + ``` - Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref): + Reference your API definition in the `docs.yml` file to [generate API Reference documentation](/learn/docs/api-references/generate-api-ref): - ```yml docs.yml - navigation: - - api: "API Reference" - ``` + ```yml docs.yml + navigation: + - api: "API Reference" + ``` - - - [Configure all of your site's branding](/learn/docs/configuration/site-level-settings), such as the logo, colors, and font, in the `docs.yml` file. - - - ```yml maxLines=7 - colors: - accent-primary: - dark: "#f0c193" - light: "#af5f1b" - logo: - dark: docs/assets/logo-dark.svg - light: docs/assets/logo-light.svg - height: 40 - href: https://buildwithfern.com/ - - favicon: docs/assets/favicon.svg - ``` - + + [Configure all of your site's branding](/learn/docs/configuration/site-level-settings), such as the logo, colors, and font, in the `docs.yml` file. + + + ```yml maxLines=7 + colors: + accent-primary: + dark: "#f0c193" + light: "#af5f1b" + + logo: + dark: docs/assets/logo-dark.svg + light: docs/assets/logo-light.svg + height: 40 + href: https://buildwithfern.com/ + + favicon: docs/assets/favicon.svg + ``` + + - - Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links. + + Before publishing, [preview your changes](/docs/preview-publish/preview-changes) in your local development environment or generate shareable preview links. + Run the local development server with hot-reloading. Your docs will automatically update as you edit Markdown and OpenAPI files: - Run the local development server with hot-reloading. Your docs will automatically update as you edit Markdown and OpenAPI files: - - ```bash - fern docs dev - ``` + ```bash + fern docs dev + ``` - - Generate a preview URL you can share with your team: + + Generate a preview URL you can share with your team: - ```bash - fern generate --docs --preview - ``` + ```bash + fern generate --docs --preview + ``` @@ -225,9 +242,9 @@ Or, follow this guide to get started with Fern using the CLI. - - When you're ready for your docs to be publicly accessible, [publish them](/learn/docs/preview-publish/publishing-your-docs): + + When you're ready for your docs to be publicly accessible, [publish them](/learn/docs/preview-publish/publishing-your-docs): ```bash fern generate --docs @@ -236,11 +253,13 @@ Or, follow this guide to get started with Fern using the CLI. You'll be prompted to log in and connect your GitHub account. This command builds your documentation at the URL you configured in `docs.yml` (e.g., `https://yourdomain.docs.buildwithfern.com`). - Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members, and CLI version. Track analytics to understand how developers use your docs. + Use the [Fern Dashboard](http://dashboard.buildwithfern.com) to manage your GitHub repository connection, organization members, and CLI version. Track analytics to understand how developers use your docs. + + ## Explore Fern's features Now that your docs are live, explore these features to enhance them further.