Skip to content

Commit

Permalink
(docs): multiple updates incl. add info on: max_retries config, how t…
Browse files Browse the repository at this point in the history 
…itles work, how to add images, where to find release changelogs (#3135)

* docs: update fern-init.mdx to add more info about created files/folders, remove IMDb mention, remove --docs flag info

* docs: update front-matter.mdx with how page titles are constructed from front matter and docs.yml

* docs: update write-markdown.mdx with info about adding images

* docs: add retry logic section to sdks-overview.mdx, remove link to deleted browser sdk page, update where to find version numbers, update headers
  • Loading branch information
@minaelee
minaelee authored Mar 10, 2024
1 parent df1cac2 commit ecd00da
Show file tree
Hide file tree
Showing 4 changed files with 98 additions and 51 deletions.
38 changes: 35 additions & 3 deletions fern/docs/pages/fern-docs/content/front-matter.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Front matter must be added to the top of a `.md` or `.mdx` file, before the rest
<CodeBlock title="Example front matter in .md or .mdx file">
```mdx
---
title: Fern | Introduction to the Fern toolkit for REST APIs
title: 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.
editThisPageUrl: https://github.com/fern-api/fern/blob/main/fern/docs/pages/overview/introduction.mdx
image: https://github.com/fern-api/fern/blob/main/fern/docs/images/logo-green.png
Expand All @@ -24,9 +24,41 @@ image: https://github.com/fern-api/fern/blob/main/fern/docs/images/logo-green.pn
**Type**: string<br />
**Default**: The name of the page as specified in `docs.yml`

Set the content for the [`<title>` element](https://web.dev/learn/html/document-structure#document_title) for a page. This title is displayed in browser tabs, history, and bookmarks, as well as in search engine results. Having a unique and informative title for each page benefits your site's SEO (Search Engine Optimization). For more information, see [Google's guidelines for useful titles](https://developers.google.com/search/docs/appearance/title-link#page-titles).
Set the content for the [`<title>` element](https://web.dev/learn/html/document-structure#document_title) for a page. This title is displayed in browser tabs, history, and bookmarks, as well as in search engine results. Having a unique and informative title for each page benefits your site's SEO (Search Engine Optimization).

If no title is provided in the front matter of a page, the name of the page in `docs.yml` is used.
<Tip>
TIP: For more information, see [Google's guidelines for useful titles](https://developers.google.com/search/docs/appearance/title-link#page-titles).
</Tip>

If no `title` is provided in the front matter of a page, Fern uses the value for that page in `docs.yml`.

For example, if a page is defined like this in `docs.yml`:

<CodeBlock title='docs.yml'>
```yaml
- page: Overview
path: ./docs/pages/fern-docs/docs-overview.mdx
```
</CodeBlock>
Then, if Fern does not find a `title` in that page's front matter, `Overview` is used for the default title.

##### Site-wide title text appended from docs.yml

You can set a field named `title` in `docs.yml` like this:

<CodeBlock title='docs.yml'>
```yaml
instances:
- url: fern.docs.buildwithfern.com
title: Fern | Documentation # <-- set site-wide
```
</CodeBlock>

The value you enter for this field is appended to every page's title across your docs site, as ` - TITLE_VALUE`.

For example, with the above setting in `docs.yml`, the `Overview` page's title becomes `Overview - Fern | Documentation`.

#### description
**Type**: string<br />
Expand Down
30 changes: 21 additions & 9 deletions fern/docs/pages/fern-docs/content/write-markdown.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,17 @@ description: Use Markdown and MDX to add content to your Fern documentation site

## Add Markdown or MDX pages

Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/).
Add pages manually to your documentation by creating Markdown (`.md`) or MDX (`.mdx`) files. New to Markdown? See [Markdown Guide: Getting started](https://www.markdownguide.org/getting-started/).

<Note>
NOTE: Throughout our documentation, we refer to both Markdown and MDX as Markdown. [MDX](https://mdxjs.com/) is a version of Markdown, extended to allow the use of JSX components.
</Note>

Place your pages inside your `fern/` folder and link to them from your [navigation settings](/fern-docs/config/navigation) in the `docs.yml` file.

In the example below, the MDX files are inside a folder named `pages/`.

<CodeBlock title="Example folder structure">
<CodeBlock title='Example folder structure'>
```bash
fern/
├─ fern.config.json
Expand All @@ -22,7 +26,7 @@ fern/
```
</CodeBlock>

<CodeBlock title="docs.yml">
<CodeBlock title='docs.yml'>
```yml
navigation:
- section: Overview
Expand All @@ -35,26 +39,34 @@ navigation:
</CodeBlock>
## Page header
Fern automatically generates the `<h1>` page header for each page from `docs.yml`. For example, here's the `docs.yml` entry that maps the page you are reading now:
```yml
- page: Write Markdown content
path: ./docs/pages/fern-docs/content/write-markdown.mdx
```
The value for `page` is used as the content of the top `<h1>` element of this page. Thus, when adding content to your Markdown or MDX pages, begin with `<h2>` instead of `<h1>`.
The value for `page` is used as the content of the top `<h1>` element of this page. Thus, when adding content to your Markdown pages, begin with `<h2>` instead of `<h1>`.

## Fern components
Fern has a built-in component library you can use in Markdown and MDX files. [Explore the components.](/fern-docs/content/component-library/)

## Links in Markdown and MDX
Fern has a built-in component library you can use in Markdown. [Explore the components.](/fern-docs/content/component-library/)

## Links in Markdown

### Link target
When clicked, links to relative URLs open in the same tab, whereas links to absolute URLs open in a new browser tab.

### Link format
Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown/MDX as follows:
Use a `/` character to begin a relative URL to another page on your docs site. This routes to the `url` defined in your `docs.yml` file, such as `example-docs.buildwithfern.com`. For example, if you want to link to `https://example-docs.buildwithfern.com/overview/introduction`, you can write the link in Markdown as follows:

<CodeBlock title="Relative link example">
<CodeBlock title='Relative link example'>
```mdx
Read the [Introduction](/overview/introduction).
```
</CodeBlock>
</CodeBlock>

## Images

To use images in your Markdown pages, upload them to a service such as [Amazon S3](https://aws.amazon.com/media-sharing/) or [Google Cloud Storage](https://cloud.google.com/storage).

Once you have the URL to your image, use [Markdown syntax to insert the image](https://www.markdownguide.org/basic-syntax/#images-1).
46 changes: 33 additions & 13 deletions fern/docs/pages/fern-sdks/sdks-overview.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
---
title: An overview of Fern's SDK generators
desc: Fern's SDK generators create code that makes it easier for developers to integrate with your APIs.
title: An overview of Fern's generators
desc: An overview of Fern's SDK generators, server-side generators, specification (Postman and OpenAPI) generators, retry logic, and using specific versions.
---

Fern's SDK generators are written in the language they generate. They're open source and actively maintained, so you can raise a PR or open an issue if you'd like to suggest an improvement.
Fern's generators are open source and actively maintained, so you can raise a PR or open an issue if you'd like to suggest an improvement.

## SDK language support
## SDK generators overview

Whether you call them SDKs, client libraries, or wrappers, Fern's generators create code that makes it easier for developers to integrate with your APIs.
Whether you call them SDKs, client libraries, or wrappers, Fern's SDK generators create code that makes it easier for developers to integrate with your APIs.

| Language | Availability | Package Manager | `fern add <generator>` command |
| -------------------------------------------------------------- | --------------------- | --------------- | ------------------------------------- |
| [TypeScript Node.js](/fern-sd-ks/sdk-generators/typescript) | Generally available | NPM | `fernapi/fern-typescript-node-sdk` |
| [TypeScript Browser](/fern-sd-ks/sdk-generators/browser) | Generally available | NPM | `fernapi/fern-typescript-browser-sdk` |
| [Python](/fern-sd-ks/sdk-generators/python) | Generally available | PyPI | `fernapi/fern-python-sdk` |
| [Java](/fern-sd-ks/sdk-generators/java) | Generally available | Maven | `fernapi/fern-java-sdk` |
| [Go](/fern-sd-ks/sdk-generators/go) | Generally available | Proxy Module | `fernapi/fern-go-sdk` |
Expand All @@ -22,7 +21,28 @@ Whether you call them SDKs, client libraries, or wrappers, Fern's generators cre

_Looking for a language that's not listed? [Let us know.](https://github.com/fern-api/fern/issues/new?title=%5BLanguage%20Request%5D%20)_

## Server-side
### Retry logic

Fern's SDK generators employ an exponential backoff strategy with a default of two retries for each client.

To configure the number of retries for a generator, update `generators.yml`. Example:

<CodeBlock title='generators.yml'>
```yaml
groups:
local:
generators:
- name: fernapi/fern-typescript-node-sdk
version: 0.x.x
output:
location: local-file-system
path: ../sdks/typescript
config:
maxRetries: 6 # <----
```
</CodeBlock>
## Server-side generators overview
Whether you call them server interfaces, server stubs, or API implementation stubs, Fern's generators create boilerplate for your backend that makes it easier for you to implement your API. Plus, your API will be consistent across your server, clients, and docs.
Expand All @@ -33,13 +53,13 @@ Whether you call them server interfaces, server stubs, or API implementation stu
| [Spring](/fern-sd-ks/other-generators/server-side/spring) | Java | Generally available | `fernapi/fern-java-spring` |
| [Go standard library](/fern-sd-ks/other-generators/server-side/go) | Go | Coming next year | `fernapi/fern-go-server` |
| [.NET](/fern-sd-ks/other-generators/server-side/dotnet) | C# | Coming next year | `fernapi/fern-csharp-dotnet` |
| [Ruby on Rails](/fern-sd-ks/other-generators/server-side/ruby) | Ruby | Coming next year | `fernapi/fern-ruby-rails` |
| [Ruby on Rails](/fern-sd-ks/other-generators/server-side/ruby) | Ruby | Coming next year | `fernapi/fern-ruby-rails` |
| [Flask](/fern-sd-ks/other-generators/server-side/flask) | Python | Coming next year | `fernapi/fern-python-flask` |
| [Django](/fern-sd-ks/other-generators/server-side/django) | Python | Coming next year | `fernapi/fern-python-django` |

_Looking for a framework that's not listed? [Let us know.](https://github.com/fern-api/fern/issues/new?title=%5BFramework%20Request%5D%20)_

## Specification
## Specification generators overview

Use our [OpenAPI generator](/fern-sd-ks/other-generators/spec/openapi) to export your Fern Definition to the OpenAPI specification, and our [Postman Collection generator](/fern-sd-ks/other-generators/spec/postman) to export your API definition to a Postman Collection.

Expand All @@ -48,11 +68,9 @@ Use our [OpenAPI generator](/fern-sd-ks/other-generators/spec/openapi) to export
| Generally available | `fernapi/fern-openapi` |
| Generally available | `fernapi/fern-postman` |

## Releases
## Use a specific generator release's version

All generator releases are published in the `Releases` section of the GitHub repository. You can directly use these version numbers in your generator configuration files.

![Releases on GitHub](https://fern-image-hosting.s3.amazonaws.com/releases-github.png)
You can directly use previous releases' version numbers in your generator configuration files.

For example, if you want to pin to a specific version of the TypeScript/Node.js SDK generator, `0.7.1`, you can use the following configuration:

Expand All @@ -63,3 +81,5 @@ groups:
- name: fernapi/fern-typescript-node-sdk
version: 0.7.1
```

To find previous release/version numbers, view the changelog for the generator. View a [table of changelogs here](https://github.com/fern-api/fern?tab=readme-ov-file#sdk-generators).
35 changes: 9 additions & 26 deletions fern/docs/pages/overview/cli/cli-commands/fern-init.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,46 +3,29 @@ title: Use fern init to start a Fern project
description: The command "fern init" initializes a new Fern workspace with a sample API definition and Fern configuration files.
---

`fern init` initializes a new Fern workspace in the current folder. By default, you'll see the `IMDb API` (International Movie Database) example.
`fern init` initializes a new Fern workspace in the current folder.

## Usage

<CodeBlock title='Fern CLI command'>
```bash
fern init [--docs]
fern init
```
</CodeBlock>

This will create the following folder structure in your project:
This command creates a `fern/` folder with the following folder structure:

```yaml
fern/
├─ fern.config.json # root-level configuration
├─ generators.yml # generators you're using
└─ definition/
└─ definition/ # Fern Definition files
├─ api.yml # API-level configuration
└─ imdb.yml # endpoints, types, and errors
```

## Options

By adding `--docs`, you'll also get a sample documentation website for your API with an API Reference section.
The `fern.config.json` file contains root-level configuration for your project. Make sure to update the organization name in this file with your own. The version in this file is the Fern version number and should match the output from `fern version`.

```bash
$ fern init --docs
```

The file added will look like:

<CodeBlock title = "docs.yml">
```yml
instances:
- url: https://your-organization.docs.buildwithfern.com
title: Your Organization | Documentation
navigation:
- api: API Reference
colors:
accentPrimary: '#ffffff'
background: '#000000'
```
</CodeBlock>
The `generators.yml` file contains settings for the generators you want to use. By default, it uses the TypeScript SDK generator. Use [fern add](/overview/cli/commands) to add generators, and edit the file to remove generators.

To publish the API docs, run `fern generate --docs`. See more details on this command at [fern-generate](/overview/cli/commands/fern-generate).
The `definition/` folder contains default Fern Definition files defining a sample API. To use OpenAPI in your project instead of Fern Definition, delete this folder and replace it with a folder named `openapi/` that contains your OpenAPI specification file (such as `openapi.yaml`).

0 comments on commit ecd00da

Please sign in to comment.