From 0f3b1ce61d242130f099c67ca5cee08fb503c1fe Mon Sep 17 00:00:00 2001 From: Danny Sheridan <83524670+dannysheridan@users.noreply.github.com> Date: Mon, 27 May 2024 12:37:22 -0500 Subject: [PATCH] (docs) Add Building Your Docs section (#3698) * Write Building Your Docs sections * add custom CSS * define multiple sdk group names * multiple group names --- fern/docs.yml | 92 ++--- fern/fern.config.json | 2 +- .../api-definition/openapi/extensions.mdx | 14 + .../building-your-docs}/custom-domain.mdx | 0 .../local-development.mdx} | 7 +- .../building-your-docs}/navigation.mdx | 0 .../docs/building-your-docs/pr-preview.mdx | 68 ++++ .../pages/docs/building-your-docs/styling.mdx | 331 ++++++++++++++++++ fern/pages/docs/components/overview.mdx | 39 +++ .../colors-fonts-background-image.mdx | 148 -------- .../config/branding/logo-and-favicon.mdx | 37 -- .../fern-docs/config/config-overview.mdx | 9 - fern/pages/fern-docs/config/previews.mdx | 70 ---- fern/pages/sdks/features/auto-pagination.mdx | 33 +- 14 files changed, 502 insertions(+), 348 deletions(-) rename fern/pages/{fern-docs/config/branding => docs/building-your-docs}/custom-domain.mdx (100%) rename fern/pages/docs/{introduction/development.mdx => building-your-docs/local-development.mdx} (89%) rename fern/pages/{fern-docs/config => docs/building-your-docs}/navigation.mdx (100%) create mode 100644 fern/pages/docs/building-your-docs/pr-preview.mdx create mode 100644 fern/pages/docs/building-your-docs/styling.mdx create mode 100644 fern/pages/docs/components/overview.mdx delete mode 100644 fern/pages/fern-docs/config/branding/colors-fonts-background-image.mdx delete mode 100644 fern/pages/fern-docs/config/branding/logo-and-favicon.mdx delete mode 100644 fern/pages/fern-docs/config/config-overview.mdx delete mode 100644 fern/pages/fern-docs/config/previews.mdx diff --git a/fern/docs.yml b/fern/docs.yml index ebce378c5e1..6420674b1d1 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -6,8 +6,6 @@ instances: owner: fern-api repo: fern branch: main - # - url: fern-beta.docs.buildwithfern.com/learn - # custom-domain: staging.buildwithfern.com/learn title: Fern tabs: @@ -118,7 +116,7 @@ navigation: - page: Auto-Pagination path: ./pages/sdks/features/auto-pagination.mdx icon: pro - - page: OAuth + - page: OAuth token refresh path: ./pages/sdks/features/oauth.mdx icon: pro - page: Retries with backoff @@ -148,8 +146,6 @@ navigation: - page: WebSockets path: ./pages/sdks/features/websockets.mdx icon: pro - # - page: OAuth token refresh - # path: ./pages/sdks/features/dummy.mdx # icon: pro # - page: Object oriented SDKs # path: ./pages/sdks/features/dummy.mdx @@ -160,37 +156,6 @@ navigation: # - page: GitHub integration # path: ./pages/sdks/features/dummy.mdx # icon: pro - - # - section: Other generators - # contents: - # - section: Server-side - # contents: - # - page: Express.js - # path: ./pages/fern-sdks/other-generators/server-side/express.mdx - # slug: express - # - page: FastAPI - # path: ./pages/fern-sdks/other-generators/server-side/fastapi.mdx - # slug: fastapi - # - page: Spring - # path: ./pages/fern-sdks/other-generators/server-side/spring.mdx - # - section: Specification - # slug: spec - # contents: - # - page: OpenAPI generator - # slug: openapi - # path: ./pages/fern-sdks/other-generators/spec/openapi-generator.mdx - # - page: Postman Collection generator - # slug: postman - # path: ./pages/fern-sdks/other-generators/spec/postman-collection.mdx - # - section: Guides - # contents: - # - page: Publish to Maven Central - # path: ./pages/fern-sdks/guides/publish-to-maven-central.mdx - # slug: publish-maven - # - page: Update SDKs with Fern's GitHub Bot - # path: ./pages/fern-sdks/guides/github-bot.mdx - # slug: github-bot - # icon: - tab: docs layout: - section: Getting Started @@ -201,33 +166,24 @@ navigation: - page: Showcase slug: showcase path: ./pages/docs/introduction/showcase.mdx - - page: Local Development - slug: development - path: ./pages/docs/introduction/development.mdx - page: Project Structure slug: project-structure path: ./pages/docs/introduction/project-structure.mdx - - section: Configuration - slug: config - contents: - - page: Overview - path: ./pages/fern-docs/config/config-overview.mdx + + - section: Building Your Docs + contents: - page: Navigation - path: ./pages/fern-docs/config/navigation.mdx - - page: PR previews - slug: previews - path: ./pages/fern-docs/config/previews.mdx - - section: Customize branding - slug: branding - contents: - - page: Colors, fonts, and background image - path: ./pages/fern-docs/config/branding/colors-fonts-background-image.mdx - slug: colors-fonts-background-image - - page: Logo and favicon - path: ./pages/fern-docs/config/branding/logo-and-favicon.mdx - - page: Custom domain - path: ./pages/fern-docs/config/branding/custom-domain.mdx - - section: Write content + path: ./pages/docs/building-your-docs/navigation.mdx + - page: Customize Styling + path: ./pages/docs/building-your-docs/styling.mdx + - page: Pull Request Preview + path: ./pages/docs/building-your-docs/pr-preview.mdx + - page: Local Development + path: ./pages/docs/building-your-docs/local-development.mdx + - page: Custom Domain + path: ./pages/docs/building-your-docs/custom-domain.mdx + + - section: Writing Content slug: content contents: - page: Write Markdown content @@ -237,7 +193,8 @@ navigation: path: ./pages/fern-docs/content/front-matter.mdx - page: Reusable snippets path: ./pages/fern-docs/content/reusable-snippets.mdx - - section: API references + + - section: API References contents: - page: Generate API reference path: ./pages/fern-docs/content/generate-api-ref.mdx @@ -256,24 +213,32 @@ navigation: - section: Components slug: components contents: - - page: Accordion + - page: Overview + path: ./pages/docs/components/overview.mdx + - page: Accordions path: ./pages/docs/components/accordions.mdx + slug: accordions icon: "square-caret-down" - page: Accordion Groups path: ./pages/docs/components/accordion-groups.mdx icon: table-rows + slug: accordion-groups - page: Aside path: ./pages/docs/components/asides.mdx icon: align-right + slug: aside - page: Callouts path: ./pages/docs/components/callouts.mdx icon: "circle-exclamation" + slug: callouts - page: Cards path: ./pages/docs/components/cards.mdx icon: "rectangle" + slug: cards - page: Card Groups path: ./pages/docs/components/card-groups.mdx icon: "rectangles-mixed" + slug: card-groups - page: Code Blocks path: ./pages/docs/components/code-blocks.mdx slug: code-blocks @@ -281,18 +246,23 @@ navigation: - page: Steps path: ./pages/docs/components/steps.mdx icon: "arrow-progress" + slug: steps - page: Frames path: ./pages/docs/components/frames.mdx icon: "frame" + slug: frames - page: Tabs path: ./pages/docs/components/tabs.mdx icon: "window-restore" + slug: tabs - page: Endpoint Request Snippet path: ./pages/docs/components/endpoint-request-snippet.mdx icon: "turn-up" + slug: request-snippet - page: Endpoint Response Snippet path: ./pages/docs/components/endpoint-response-snippet.mdx icon: "turn-down" + slug: response-snippet - tab: cli-api layout: - section: CLI Reference diff --git a/fern/fern.config.json b/fern/fern.config.json index ef27dd09a4b..04b90b8a847 100644 --- a/fern/fern.config.json +++ b/fern/fern.config.json @@ -1,4 +1,4 @@ { "organization": "fern", - "version": "0.26.10" + "version": "0.29.0" } \ No newline at end of file diff --git a/fern/pages/api-definition/openapi/extensions.mdx b/fern/pages/api-definition/openapi/extensions.mdx index 61f5ee9e9ca..abf3d721fea 100644 --- a/fern/pages/api-definition/openapi/extensions.mdx +++ b/fern/pages/api-definition/openapi/extensions.mdx @@ -35,6 +35,20 @@ paths: x-fern-sdk-method-name: create_user ``` +If you add more than one `x-fern-sdk-group-name` extension, then the generated SDK will nested group names. The order of the group names is preserved in the generated SDK method. + +For example, the following OpenAPI will generate `client.admin.users.create()`: + +```yaml title="openapi.yaml" +paths: + /users: + post: + x-fern-sdk-group-name: + - admin + - users + x-fern-sdk-method-name: create +``` + ## Authentication overrides For authentication within your SDK, you may want to customize the: diff --git a/fern/pages/fern-docs/config/branding/custom-domain.mdx b/fern/pages/docs/building-your-docs/custom-domain.mdx similarity index 100% rename from fern/pages/fern-docs/config/branding/custom-domain.mdx rename to fern/pages/docs/building-your-docs/custom-domain.mdx diff --git a/fern/pages/docs/introduction/development.mdx b/fern/pages/docs/building-your-docs/local-development.mdx similarity index 89% rename from fern/pages/docs/introduction/development.mdx rename to fern/pages/docs/building-your-docs/local-development.mdx index 49671c7fe3b..7ecad9135aa 100644 --- a/fern/pages/docs/introduction/development.mdx +++ b/fern/pages/docs/building-your-docs/local-development.mdx @@ -1,6 +1,6 @@ --- -title: 'Development' -description: 'Preview changes before deploying to production' +title: Local Development +description: Preview your documentation locally with Fern. Access your docs on your local server at port 3000, hot-reloading as you edit your markdown and OpenAPI files. --- @@ -101,7 +101,6 @@ jobs: - Note that search functionality is not enabled on documentation previews. It is only - enabled on production deployments. + Note that search functionality is not enabled on documentation previews. It is only enabled on production deployments. diff --git a/fern/pages/fern-docs/config/navigation.mdx b/fern/pages/docs/building-your-docs/navigation.mdx similarity index 100% rename from fern/pages/fern-docs/config/navigation.mdx rename to fern/pages/docs/building-your-docs/navigation.mdx diff --git a/fern/pages/docs/building-your-docs/pr-preview.mdx b/fern/pages/docs/building-your-docs/pr-preview.mdx new file mode 100644 index 00000000000..3f19a7838f3 --- /dev/null +++ b/fern/pages/docs/building-your-docs/pr-preview.mdx @@ -0,0 +1,68 @@ +--- +title: Pull request previews +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. Use manually or in GitHub Actions. + +## Usage + +```bash +fern generate --docs --preview +``` + +## Example + +```bash +fern generate --docs --preview + +[docs]: Found 0 errors and 1 warnings. Run fern check --warnings to print out the warnings. +[docs]: Published docs to https://fern-preview-ce3459d6-8a76-4747-963a-33c71ee13959.docs.buildwithfern.com +┌─ +│ ✓ docs.example.com +└─ +``` + +## Usage in GitHub Actions + +The following is a GitHub Action workflow that generates a preview URL for every pull request.x + + +```yaml +name: preview-docs + +on: + pull_request + +jobs: + run: + runs-on: ubuntu-latest + permissions: write-all + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install Fern + run: npm install -g fern-api + + - name: Generate preview URL + id: generate-docs + env: + FERN_TOKEN: ${{ secrets.FERN_TOKEN }} + run: | + OUTPUT=$(fern generate --docs --preview 2>&1) || true + echo "$OUTPUT" + URL=$(echo "$OUTPUT" | grep -oP 'Published docs to \K.*(?= \()') + echo "Preview URL: $URL" + echo "🌿 Preview your docs: $URL" > preview_url.txt + + - name: Comment URL in PR + uses: thollander/actions-comment-pull-request@v2.4.3 + with: + filePath: preview_url.txt +``` + + +## Link expiration + +Preview links do not expire. However, the time to live (TTL) is subject to change in the future. \ No newline at end of file diff --git a/fern/pages/docs/building-your-docs/styling.mdx b/fern/pages/docs/building-your-docs/styling.mdx new file mode 100644 index 00000000000..32881841a74 --- /dev/null +++ b/fern/pages/docs/building-your-docs/styling.mdx @@ -0,0 +1,331 @@ +--- +title: Style your docs to match your brand +description: Configure your site's primary accent color, background image, logo, favicon, light and dark mode, and fonts. +--- + +Every Fern Docs website has a configuration file called `docs.yml`. Use this file to set the theme for your docs, including the primary accent color, background image, logo, favicon, light & dark mode, and fonts. + +## Colors + +### Primary accent + +You can specify a primary accent color using the [hexadecimal color](https://www.w3schools.com/colors/colors_hexadecimal.asp). The primary accent color is used for several purposes, including: + +- to indicate the page a user is on within the navigation +- as the background of a primary link button +- to underline hyperlinks +- the next and previous page navigation buttons + +In `docs.yml`, you can set a single primary accent color or specify different colors for light and dark modes: + + + + ```yaml + colors: + accentPrimary: "#ADFF8C" + ``` + + + ```yaml + colors: + accentPrimary: + light: "#418326" + dark: "#ADFF8C" + ``` + + + +### Background color + +Just like `accentPrimary`, you can specify the background color in `docs.yml` using the [hexadecimal color](https://www.w3schools.com/colors/colors_hexadecimal.asp). + + + + ```yaml + colors: + accentPrimary: "#a6d388" + background: "#0d0e11" + ``` + + + ```yaml + colors: + accentPrimary: + light: "#418326" + dark: "#ADFF8C" + background: + light: "#ffffff" + dark: "#0d0e11" + ``` + + + +## Images + +### Background image + +Customize the background image by including the image(s) in your `fern/` project and specifying the path in `docs.yml`. The PNG, SVG, and JPG image formats are supported. + + +```diff + fern/ + ├─ openapi/ + ├─ pages/ ++ ├─ images/ ++ ├─ background-light.svg ++ └─ background-dark.svg + ├─ docs.yml + └─ fern.config.json +``` + + +In `docs.yml`, you can set a single background image or specify different images for light and dark modes: + + + + ```yaml + background-image: ./images/background.svg + ``` + + + ```yaml + background-image: + light: ./images/background-light.svg + dark: ./images/background-dark.svg + ``` + + + +### Logo + +Specify a logo in `docs.yml` which gets displayed in the top left of your docs. + + + + ```yaml + logo: ./images/logo.png + ``` + + + ```yaml + logo: + light: ./images/logo-light.png + dark: ./images/logo-dark.png + ``` + + + +#### Logo properties +`light` or `dark` specifies the image file location. The supported file types are `.png` or `.svg`. + +`height` is optional and sets the logo's height in pixels. + +`href` is optional and provides a link for the logo, often used to point to the website's homepage. When the logo is clicked, the user is directed to this link. + + +```yaml +logo: + light: ./images/logo-light.png + dark: ./images/logo-dark.png + height: 60 + href: https://example.com +``` + + +### Favicon image + +Add a `favicon` image that displays in the browser tab. Supported file types are `.png` and `.ico`. + +## Fonts + +You can specify custom fonts for your documentation website. The supported file types are `.woff` and `.woff2`. + +Include the custom fonts in your `fern/` project: + + +```diff + fern/ + ├─ fern.config.json + ├─ generators.yml + ├─ openapi/ + ├─ openapi.yml ++ ├─ fonts/ ++ ├─ your-font-regular.woff2 ++ ├─ your-font-bold.woff2 ++ └─ another-font-regular.woff2 +``` + + +Fern has three font types: +- `headingsFont`: affects page and section titles; if not supplied, defaults to the body font +- `bodyFont`: affects paragraph text and other body text +- `codeFont`: affects code blocks and inline code snippets + +To customize the font used for each font type, add a top-level `typography` list to `docs.yml`. Then in it, specify the path of your font file for one or more of the font types. + +A font has two properties: +- `name`: the name of the font; defaults to a generated name that will be used to reference your custom font in the eventually injected CSS +- `path`: the path to the font file + + +```yaml +typography: + bodyFont: + name: Inter-Regular + path: ./fonts/Inter-Regular.woff2 + headingsFont: + name: Inter-Bold + path: ./fonts/Inter-Bold.woff2 + codeFont: + name: Roboto-Mono-Regular + path: ./fonts/Roboto-Mono-Regular.woff2 +``` + + +If the font file is not variable, you can specify font weights. + +A font path has three properties: +- `path`: indicate that there are multiple font files +- `weight`: a string of weights that are supported by this font file +- `style`: the style of the font file, either `normal` or `italic` + + +```yaml +typography: + bodyFont: + name: Inter-Regular + paths: + - path: ./fonts/Inter-Regular.woff2 + weight: "400" + style: normal + - path: ./fonts/Inter-Bold.woff2 + weight: 500 900 # <-- indicates a range of weights + style: normal +``` + + +## Layout + +There are several layout options you can configure in `docs.yml`. All of the layout properties are optional and give you more control over the presentation of your docs. + +- `header-height`: the height of the header in pixels; the default is `4rem (64px)` + +- `page-width`: the maximum width of the page content, including the sidebar and content; the default is `88rem (1408px)` + +- `content-width`: the maximum width of the markdown content; the default is `44rem (704px)` + +- `sidebar-width`: the width of the sidebar in desktop mode; the default is `18rem (288px)` + +- `searchbar-placement`: the placement of the search bar; the options are `sidebar` (default) or `header` + +- `tabs-placement`: the placement of the tabs; the options are `sidebar` (default) or `header` + +- `content-alignment`: the alignment of the markdown content; the options are `center` (default) and `left` + + +```yaml +layout: + header-height: 70px + page-width: 1344px + content-width: 672px + sidebar-width: 336px + searchbar-placement: header + tabs-placement: header + content-alignment: left +``` + + +## Custom CSS + +Custom CSS is available on the Business plan. + +You can add custom CSS to your docs to further customize the look and feel. Add a `styles.css` file and include it in your `fern/` project: + + +```diff + fern/ + ├─ openapi/ + ├─ pages/ + ├─ images/ ++ ├─ styles.css + ├─ docs.yml + └─ fern.config.json +``` + + +In `docs.yml`, specify the path to the `styles.css` file: + + +```yaml +css: ./docs/styles.css +``` + + +Here's an example of what you can do with custom CSS: + + +```css + +.petstore-table { + background-color: white; + border: 1px solid #DEDEE1; + border-radius: 4px; +} + +.dark .petstore-table { + background-color: #1e1e1e; + border: 1px solid #2e2e2e; +} + +.petstore-table thead { + position: sticky; + top: 0; +} + +.petstore-table thead tr { + background-color: #edecee; + border: 1px solid #DEDEE1; + border-radius: 4px 4px 0px 0px; +} + +.dark .petstore-table thead tr { + background-color: #2e2e2e; + border: 1px solid #2e2e2e; +} + +.petstore-table th { + padding: 6px; +} + +.petstore-table tbody td { + padding: 6px; +} + +.petstore-table tbody tr:nth-child(odd) { + border: 1px solid #DEDEE1; +} +.petstore-table tbody tr:nth-child(even) { + border: 1px solid #DEDEE1; + background-color: #f7f6f8; +} + +.dark .petstore-table tbody tr:nth-child(odd) { + border: 1px solid #2e2e2e; +} + +.dark .petstore-table tbody tr:nth-child(even) { + border: 1px solid #2e2e2e; + background-color: #2e2e2e; +} +``` + + +## Custom JavaScript + +Custom JS is available on the Business plan. + +## Header and footer + +Custom Components is available on the Enterprise plan. + +You can bring your own UI components and replace the default components. The `header` and `footer` are the most common components to replace. You can replace any component in the docs, including the sidebar, tabs, search bar, and more. \ No newline at end of file diff --git a/fern/pages/docs/components/overview.mdx b/fern/pages/docs/components/overview.mdx new file mode 100644 index 00000000000..6052ea57110 --- /dev/null +++ b/fern/pages/docs/components/overview.mdx @@ -0,0 +1,39 @@ +--- +title: Components Overview +description: Enhance your docs with Fern's built-in component library. Use components to create interactive and engaging documentation. +--- + +Fern provides a library of 15+ built-in-components to make your documentation more interactive and engaging. Components are building blocks that you can add to any MDX page. + +## Usage + +Specify a component in your MDX file while writing content. For example, to add a `Card` component, use the following syntax: + + +````mdx + + Give us a star! Fern's CLI & docs source code is available on GitHub. + +```` + +This will automatically render a card with the title, icon, and content you specified. + + + Give us a star! The source code to Fern's CLI is available on GitHub. + + +## Bring your own components + +Want to bring your own UI components, such as a custom header and footer? You can on the Enterprise plan. [Contact us](https://buildwithfern.com/contact) to learn more. + +## Requests for new components + +Have a component in mind that you'd like to see in Fern? Let us know by filing a [GitHub Issue](https://github.com/fern-api/fern/issues/new?assignees=&labels=&projects=&template=feature-request.md&title=%5BFeature%5D). \ No newline at end of file diff --git a/fern/pages/fern-docs/config/branding/colors-fonts-background-image.mdx b/fern/pages/fern-docs/config/branding/colors-fonts-background-image.mdx deleted file mode 100644 index c172efd01b5..00000000000 --- a/fern/pages/fern-docs/config/branding/colors-fonts-background-image.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Custom colors, fonts, background image -description: Configure your site's primary accent color and dark & light mode background colors; dark & light mode background image; and fonts for headings, body, and code. ---- - -Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to update the colors, background image, and fonts for your documentation site. - -## Colors - -### Primary accent - -You can specify a primary accent color using the [hexadecimal color](https://www.w3schools.com/colors/colors_hexadecimal.asp). The primary accent color is used for several purposes, including: - -- to indicate the page a user is on within the navigation -- as the background of a primary link button -- to underline hyperlinks -- the next and previous page navigation buttons - - -```yaml -colors: - accentPrimary: "#a6d388" -``` - - -### Background - -Just like `accentPrimary`, you can specify the background color using the [hexadecimal color](https://www.w3schools.com/colors/colors_hexadecimal.asp). - - -```yaml -colors: - accentPrimary: "#a6d388" - background: - dark: "#0d0e11" - light: "#ffffff" -``` - - -## Background image - -Include the background image or images in your `fern/` project, then specify the path in `docs.yml`: - - -```diff - fern/ - ├─ openapi/ - ├─ pages/ -+ ├─ images/ -+ ├─ bg-light.svg -+ └─ bg-dark.svg - ├─ docs.yml - └─ fern.config.json -``` - - -The PNG, SVG, and JPG image formats are supported. - -### Single background image - -You can set a single background image for both light and dark modes: - - -```yaml -background-image: ./images/bg.svg -``` - - -### Light and dark mode background image - -You can set a different background image for each mode: - - -```yaml -background-image: - light: ./images/bg-light.svg - dark: ./images/bg-dark.svg -``` - - -## Fonts - -You can specify custom fonts for your documentation website. The supported file types are `.woff` and `.woff2`. - -Include the custom fonts in your `fern/` project: - - -```diff - fern/ - ├─ fern.config.json - ├─ generators.yml - ├─ openapi/ - ├─ openapi.yml -+ ├─ fonts/ -+ ├─ your-font-regular.woff2 -+ ├─ your-font-bold.woff2 -+ └─ another-font-regular.woff2 -``` - - -Fern has three font types: -- `headingsFont`: affects page and section titles; if not supplied, defaults to the body font -- `bodyFont`: affects paragraph text and other body text -- `codeFont`: affects code blocks and inline code snippets - -To customize the font used for each font type, add a top-level `typography` list to `docs.yml`. Then in it, specify the path of your font file for one or more of the font types. - -A font has two properties: -- `name`: the name of the font; defaults to a generated name that will be used to reference your custom font in the eventually injected CSS -- `path`: the path to the font file - - -```yaml -typography: - bodyFont: - name: Inter-Regular - path: ./fonts/Inter-Regular.woff2 - headingsFont: - name: Inter-Bold - path: ./fonts/Inter-Bold.woff2 - codeFont: - name: Roboto-Mono-Regular - path: ./fonts/Roboto-Mono-Regular.woff2 - name: Roboto-Mono-Regular -``` - - -If the font file is not variable, you can specify font weights. - -A font path has three properties: -- `path`: indicate that there are multiple font files -- `weight`: a string of weights that are supported by this font file -- `style`: the style of the font file, either `normal` or `italic` - - -```yaml -typography: - bodyFont: - name: Inter-Regular - paths: - - path: ./fonts/Inter-Regular.woff2 - weight: "400" - style: normal - - path: ./fonts/Inter-Bold.woff2 - weight: 500 900 # <-- indicates a range of weights - style: normal -``` - \ No newline at end of file diff --git a/fern/pages/fern-docs/config/branding/logo-and-favicon.mdx b/fern/pages/fern-docs/config/branding/logo-and-favicon.mdx deleted file mode 100644 index bd73ae3286c..00000000000 --- a/fern/pages/fern-docs/config/branding/logo-and-favicon.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Add a custom logo and favicon -description: Customize your docs site's logo and favicon, including the logo height and its link target. ---- - -Every Fern Docs website has a special configuration file called `docs.yml`. Use this file to update the logo and favicon for your documentation site. - -## Logo - -Add a logo that displays in the top left of your documentation website. - - -```yaml -logo: - path: ./images/logo.png - height: 60 - href: https://example.com -``` - - -### Logo path - -`path` specifies the image file location. The supported file types are `.png` or `.svg`. - -### Logo height - -`height` sets the logo's height in pixels. - -### Logo href - -`href` provides a link for the logo, often used -to point to the website's homepage. When the logo is clicked, the user is directed to this link. - -## Favicon - -Specifies the path to a `favicon` image, which is typically displayed in a -browser tab or bookmark. Supported file types are `.png` and `.ico`. \ No newline at end of file diff --git a/fern/pages/fern-docs/config/config-overview.mdx b/fern/pages/fern-docs/config/config-overview.mdx deleted file mode 100644 index dab98dba4bd..00000000000 --- a/fern/pages/fern-docs/config/config-overview.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Overview of Fern Docs configurations -description: Links to configurations for your Fern Docs, including navigation, custom domain, colors, fonts, logo, favicon, and background image. ---- - -- [Navigation.](/learn/docs/config/navigation) Update the site navigation with tabs, sections, pages, and navbar links. -- [Custom domain.](/learn/docs/config/branding/custom-domain) Bring your own custom domain to Fern Docs. -- Brand your site with your organization's [logo and favicon](/learn/docs/config/branding/logo-and-favicon) -- Configure custom [colors, fonts, and background image](/learn/docs/config/branding/colors-fonts-background-image). diff --git a/fern/pages/fern-docs/config/previews.mdx b/fern/pages/fern-docs/config/previews.mdx deleted file mode 100644 index 4c0d8e279d2..00000000000 --- a/fern/pages/fern-docs/config/previews.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Pull request previews -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 - -## Usage - -```bash -fern generate --docs --preview -``` - -## Example - -```bash -fern generate --docs fern.docs.buildwithfern.com --preview - -Download @fern/registry Downloading manifest... -Download @fern/registry Downloading... -Download @fern/registry Parsing... -[docs]: Published docs to https://fern-preview-3e0e506f-d277-4f13-be63-e609b7320db1.docs.buildwithfern.com -┌─ -│ ✓ Download @fern/registry -│ ✓ fern.docs.buildwithfern.com -└─ -``` - -## Usage in GitHub Actions - -The following is a GitHub Action workflow that generates a preview URL for every pull request. - - -```yaml -name: preview-docs - -on: - pull_request: - branches: - - main - -jobs: - generate-preview-docs: - name: Generate Documentation Preview - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '18' - - - name: Install Fern - run: npm install -g fern-api - - - name: Generate Documentation Preview with Fern - env: - FERN_TOKEN: ${{ secrets.FERN_TOKEN }} - run: fern generate --docs --preview -``` - - -## Link expiration - -Preview links do not expire. However, the time to live (TTL) may be subject to change in the future. diff --git a/fern/pages/sdks/features/auto-pagination.mdx b/fern/pages/sdks/features/auto-pagination.mdx index 8e38b6ced76..fd9df944709 100644 --- a/fern/pages/sdks/features/auto-pagination.mdx +++ b/fern/pages/sdks/features/auto-pagination.mdx @@ -1,16 +1,13 @@ --- title: Auto Pagination -description: Paginate through API responses easily +description: Paginate through API responses easily with offset, cursor, and link-based pagination. --- - This feature is only available on paid plans. Please schedule a [demo](https://buildwithfern.com/contact) - or [email us](mailto:support@buildwithfern.com) to get started. + This feature is only available on paid plans. [Contact us](https://buildwithfern.com/contact) to get started. -Instead of forcing SDK users to learn the intricacies of your -pagination system, Fern SDKs will return an iterator so that user's can -simply loop through all the results. +Instead of forcing SDK users to learn the intricacies of your pagination system, Fern SDKs will return an iterator so that user's can simply loop through all the results. @@ -114,8 +111,8 @@ MyResponseObject: - - + + ```yaml Offset ... paths: @@ -125,8 +122,8 @@ paths: results: $response.results ... ``` - - + + ```yaml Cursor ... paths: @@ -137,13 +134,13 @@ paths: results: $response.results ... ``` - - + + - - + + ```yaml Offset service: endpoints: @@ -152,8 +149,8 @@ service: offset: $request.page results: $response.data ``` - - + + ```yaml Cursor service: endpoints: @@ -163,7 +160,7 @@ service: next_cursor: $response.page.next.starting_after results: $response.data ``` - - + + \ No newline at end of file