Last updated

Developer portal changelog

Deprecated docs

The developer portal beta is approaching end of life.

Use Realm and Reunite instead. Read the migration guide.

This changelog is divided into two tracks:

1 - for 1.1.x releases

2 - for 1.0.x releases

Developer portal 1.1.x

Next

1.1.0-beta.137 (2024-07-16)

Features

  • Add support for an environment variable LOWERCASE_URL to change tags in the OpenAPI description to lower case when they appear in URLs.
  • Upgraded the Reference docs package to 2.43.8. Check the Reference docs changelog for details about this version.

Fixes

  • Fixed an issue with duplicated URLs in sitemap.xml.

1.1.0-beta.136 (2024-06-17)

Fixes

  • Fixed an issue where users were unable to scroll through Search Results on mobile devices.
  • Upgraded the Reference docs package to 2.43.7. Check the Reference docs changelog for details about this version.

1.1.0-beta.135 (2024-05-15)

Features

1.1.0-beta.134 (2024-04-18)

Features

1.1.0-beta.133 (2024-03-18)

Features

  • Add expiration date timeout for the authentication token, so logging users out event will be triggered on the UI as expected.

1.1.0-beta.132 (2024-02-19)

Fixes

  • Authentication tokens expire after the set expiration time, logging users out of the UI as expected.

1.1.0-beta.131 (2024-01-16)

Features

1.1.0-beta.130 (2023-12-15)

Fixes

  • Fixed a problem with web-manifest missing Authorization header when Basic authorization applied.

1.1.0-beta.129 (2023-11-30)

Fixes

  • Fixed a problem with slow build times for OpenAPI files in the static folder.
  • Prevent OpenAPI files in the static folder from being search-indexed twice.

1.1.0-beta.128 (2023-10-17)

Fixes

  • Fixed an issue that causes a failing build because of an unresolved stream.

1.1.0-beta.127 (2023-08-16)

Features

  • Upgraded the Reference docs package to 2.42.1. Check the Reference docs changelog for details about this version.
  • Upgraded the @redocly/openapi-core package to 1.0.2.

Fixes

  • Added support for the deepLinkPrefix option with pagination set to item.
  • Fixed an issue with copying code snippets text which contains environment variables.

1.1.0-beta.126 (2023-07-13)

Features

  • Added support for the sideNavStyle configuration option that defines the style of the navigation sidebar items (in the left-hand side of the page). The default style is summary-only. The path-first style shows the path first with the summary underneath. The id-only style shows the operation ID if provided; otherwise, it shows only the path.
  • Upgraded the Reference docs package to 2.41.1. Check the Reference docs changelog for details about this version.
  • Upgraded the @redocly/openapi-core package to 1.0.0-beta.131.
  • Added support for disabling the version log for security reasons.

1.1.0-beta.125 (2023-06-15)

Features

  • Added "404 - Not Found" title to the 404 page.

1.1.0-beta.124 (2023-05-30)

Features

  • Upgraded the @redocly/openapi-core package to 1.0.0-beta.124.

Fixes

  • Fixed an issue where a broken page would briefly display prior to redirecting to a different page.
  • Fixed an issue with sitemap.xml generation for large portals.

1.1.0-beta.123 (2023-03-10)

Fixes

  • Fixed an issue with builds crashing when plugins read data.

1.1.0-beta.122 (2023-01-19)

Fixes

1.1.0-beta.121 (2022-12-19)

Features

1.1.0-beta.120 (2022-11-11)

Fixes

  • Fixed an issue where the sidebar disappears periodically.

Features

1.1.0-beta.119 (2022-10-05)

Features

1.1.0-beta.118 (2022-09-28)

Features

Fixes

  • Fixed an issue with scrolling to an anchor on initial page loads.

1.1.0-beta.117 (2022-09-22)

Fixes

  • Fixed an issue with seo siteUrl configuration not working for images.
  • Fixed an issue with sidebar not hidden on mobile when navigating to different hash link.
  • Fixed an issue with hidden search results when closing keyboard area on mobile devices.

1.1.0-beta.116 (2022-09-21)

Features

  • Upgraded the Reference docs package to 2.37.1 - check the Reference docs changelog for details about this version.
  • Upgraded the @redocly/openapi-core package to 1.0.0-beta.110.

Fixes

  • Fixed an issue with incorrect search behavior on mobile devices.
  • Fixed an issue with showing sidebar scrollbar when there are only a few links in it.
  • Fixed an issue with incorrect "Last updated time" for markdown pages in some cases.

1.1.0-beta.115 (2022-09-14)

Features

  • Downloads Redocly configuration files (such as redocly.yaml) for each API in the API catalog.
  • Added ability to set search input loading spinner color. Now the theme's components.search.iconColor property applies to the search input loading spinner too.
  • Upgraded the Reference docs package to 2.36.1 - check the Reference docs changelog for details about this version.
  • Upgraded the @redocly/openapi-core package to 1.0.0-beta.109.

1.1.0-beta.114 (2022-09-07)

Fixes

  • Fixed an issue with search performance where search data loaded multiple times.

Features

  • Added possibility to ignore entire folder during the build by placing underscore in front of folder's name. For more details refer to the docs.
  • Upgraded the Reference docs package to 2.36.0 - check the Reference docs changelog for details about this version.
  • Upgraded the @redocly/openapi-core package to 1.0.0-beta.108.

1.1.0-beta.113 (2022-08-31)

Fixes

  • Fixed an issue with invalid render order for MDX causing wrong images displayed after page refresh.
  • Fixed an issue with invalid error formatting in console output.
  • Fixed icon for info admonition.

Features

1.1.0-beta.112 (2022-08-25)

Fixes

  • Fixed an issue with incorrect id for definition, which path is specified under oasDefinitions section in siteConfig.yaml but does not have a corresponding .page.yaml.

Features

  • Upgraded the Reference docs package to 2.33.0 - check the Reference docs changelog for details about this version.

  • Added new theme setting externalIconUrl to specify URL to external icon. Supports data-urls too. Example usage:

    const customIconUrl = require('../images/external.svg');

export const theme = {
  // ...
  externalIconUrl: customIconUrl,
  // ...
}

1.1.0-beta.111 (2022-08-17)

Fixes

  • Fixed an issue with not including table content into search results.
  • Fixed an issue with rendering mermaid diagrams when portal runs in local environment.

Features

  • Added support for wildcard (*) redirects. You can get more familiar with redirects feature here.
  • Added export of Footer component, so it can be wrapped in some container.
  • Added disableAutoApiDocs config option to disable automatic API docs pages creation from OpenAPI files (without .page.yaml).
  • Added possibility to customize external link icon.
  • Upgraded the Reference docs package to 2.31.1 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.107.

1.1.0-beta.110 (2022-08-10)

Fixes

  • Fixed an issue with rebuilding API definition in development mode.

Features

  • Added disableLinkPrefetching config option. If it is set to true, developer portal will do data prefetching only for hovered links.
  • Upgraded the Reference docs package to 2.31.0 - check the Reference docs changelog for details about this version.

1.1.0-beta.109 (2022-08-04)

Fixes

  • Fixed an issue with portal build failures when image attributes are used on pages.

1.1.0-beta.108 (2022-08-03)

Fixes

  • Fixed an issue where the customizable images feature was breaking MDX pages if the development server started without the images optimization option.
  • Fixed an issue where the search indexer failed for valid OpenAPI definitions.
  • Fixed an issue with including jsx tags into search results.

Features

  • Added support for --no-uglify CLI option to disable JavaScript minification.
  • Upgraded the Reference docs package to 2.29.0 - check the Reference docs changelog for details about this version.

1.1.0-beta.107 (2022-07-27)

Fixes

  • Fixed an issue where the copy button is not displayed for a code snippet if its language is not specified.
  • Fixed a missing alt attribute for icon in Tile components.
  • Fixed an issue with deprecated title warnings.
  • Fixed an issue with drilldown menu type overlapping.
  • Fixed an issue with detecting lint ignore file during the portal build.

Features

  • Added support for Rudderstack.
  • Added new theming options for customizing FAB (floating action button) component.
  • Upgraded the Reference docs package to 2.27.3 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.105.

1.1.0-beta.106 (2022-07-20)

Fixes

  • Fixed an issue with the API catalog not working for big API definitions in some cases.
  • Fixed an issue with inconsistent behavior for the deprecated option in sidebar menu.
  • Fixed an issue with div width has value [object Object].

Features

1.1.0-beta.105 (2022-07-13)

Fixes

  • Fixed an issue when search-index.json got filled with CSS text when using some UI libraries.

Feature

  • Upgraded the Reference docs package to 2.27.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.104.

1.1.0-beta.104 (2022-07-06)

Fixes

  • Fixed an issue with the deprecated showConsole parameter.
  • Fixed a portal crash on an empty .page.yaml file.
  • Fixed title's anchors under the API authentication section.
  • Fixed indexing paragraphs on the page for search.

Feature

1.1.0-beta.103 (2022-07-01)

Fixes

  • Fixed an issue with page crashing when using custom Navbar and not passing location to SearchBox.

Feature

1.1.0-beta.102 (2022-06-30)

Fixes

  • Fixed an issue with top-level sidebar groups not hidden with RBAC if they have nested separator.

Feature

  • Upgraded the Reference docs package to 2.26.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.103.

1.1.0-beta.101 (2022-06-24)

Fixes

  • Fixed an issue with search results not being clickable in some cases.

1.1.0-beta.100 (2022-06-22)

Feature

1.1.0-beta.99 (2022-06-15)

Feature

  • Upgraded the Reference docs package to 2.23.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.102.

1.1.0-beta.98 (2022-06-08)

Fixes

  • Fixed an issue with GraphQL error when set API catalog disableAutoSidebar option to true.
  • Fixed an issue with search result box show/hide behaviour after the item was selected.

1.1.0-beta.97 (2022-06-01)

Feature

  • Upgraded the Reference docs package to 2.22.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.100.

Fixes

  • Fixed an issue with escaping backslashes when copying code samples.
  • Fixed an issue when a page without a footer causes an error.
  • Fixed an issue with schemas menu items not working properly.
  • Fixed an issue with API catalog not working for API definitions in json format.
  • Fixed an issue with cutted off request body in the Try it console.

1.1.0-beta.96 (2022-05-25)

Feature

Fixes

  • Fixed an issue with RBAC sidebar items not filtered by default.
  • Fixed an issue with the portal not loading API docs for multiple versions of an API when using the index.page.yaml file.

1.1.0-beta.95 (2022-05-19)

Feature

  • Upgraded the Reference docs package to 2.19.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.98.

Fixes

  • Resolved an issue with Code snippet button text gets inside the searchIndex.
  • Resolved an issue with the WideTile UI component layout.

1.1.0-beta.94 (2022-05-12)

Feature

  • Upgraded the Reference docs package to 2.15.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.97.

1.1.0-beta.93 (2022-05-05)

Feature

  • Upgraded the Reference docs package to 2.14.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.95.

Fixes

  • Resolved an issue with highlighting the last element in the MD(X) page TOC.
  • OpenAPI definition files that have _ at the start of the filename will not be included in the portal build.

1.1.0-beta.92 (2022-04-28)

Feature

Fixes

  • Resolved an issue with linking to API reference pages from MD pages.

1.1.0-beta.91 (2022-04-21)

Feature

  • Upgraded the Reference docs package to 2.13.6 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.94.

Fixes

  • Resolved an issue with the portal crashing when non-existing page is referenced from sidebars.
  • Resolved a default value for catalog.yaml version summary.

1.1.0-beta.90 (2022-04-14)

Feature

  • Upgraded the Reference docs package to 2.13.5 - check the Reference docs changelog for details about this version.
  • Search results on API reference pages will display operation descriptions when available.

Fixes

  • Resolved an issue with .json-based reference docs pages not working correctly in sidebars.yaml.

1.1.0-beta.89 (2022-04-07)

Feature

  • Upgraded the Reference docs package to 2.13.4 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.93.

Fixes

  • Resolved an issue with missing setParameterValue export and fixed a broken Reference docs hooks code example in the documentation.
  • Resolved an issue with search result disappear on scrollbar click.

1.1.0-beta.88 (2022-03-31)

Feature

  • Changed default value for search indexing depth for integrated Reference docs from 8 to 2. Set it to a number from 1 to 10 to control the maximum level of nested properties that should be included in the search index.
  • Upgraded the Reference docs package to 2.13.0 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.91.

1.1.0-beta.87 (2022-03-28)

Fixes

  • Resolved an issue with portal crashing builds on invalid .yaml files.

1.1.0-beta.86 (2022-03-28)

Features

  • Implemented the API catalog - a new approach for integrating the developer portal and the API registry. Use the catalog.yaml file to import assets and integrate multi-version APIs into your portal.

  • You can add an "Edit page" button to all or some MD(X) pages in your portal. When enabled, the button is displayed at the top of each page, and can link to a GitHub or a GitLab repository. You can enable it globally for all pages in the siteConfig.yaml file, or control it per-page in the front matter.

  • Starting with this release, portal version number is visible in the developer console to make troubleshooting easier.

  • Reference docs pages can be integrated directly into the portal without creating .page.yaml files. To achieve this, add your OpenAPI definition file to the portal project and include it into a sidebars.yaml file. Note that this approach doesn't support multi-version APIs, integrating APIs from the Redocly API registry, restricting permissions with RBAC, or excluding specific API reference documentation from portal search results. To use those features, you have to integrate Reference docs with .page.yaml files as before.

Deprecated

  • Wildcard /* links (e.g. acme.page.yaml/*) for adding Reference pages to the portal sidebar are deprecated for the direct OpenAPI file integration. Those links only work when using .page.yaml files to integrate Reference docs into the portal.

1.1.0-beta.85 (2022-03-18)

Features

  • Upgraded the Reference docs package to 2.12.5 - check the Reference docs changelog for details about this version.
  • Upgraded the OpenAPI Core package to 1.0.0-beta.88 which allows using the redocly.yaml name for the configuration file.
  • All table of contents sections on MD(X) pages have an "On this page" header.
  • Implemented support for displaying a sidebar on pages not listed in any sidebars.yaml file. To do this, use the new sidebar option in the page front matter. Specify which sidebar to display by providing the path to the sidebars.yaml file or the sidebar name (if you're using the legacy sidebar configuration with sidebarName).

Usage example

---
title: Adding sidebar to the page
sidebar: training
---

---
title: Adding sidebar to the page
sidebar: ../sidebars.yaml
---

If you have defined multiple sidebars in the root sidebars.yaml file, the portal displays the first available sidebar from that file when you add its path to the front matter. In this case, we recommend you use the sidebar name in the front matter to precisely control which sidebar to show. Front matter has priority over other configuration. If a page is listed in a sidebars.yaml file and has a different sidebar set in the front matter, the one from the front matter displays.

Fixes

  • Resolved an issue with disableImagesOptimization not working due to sharp dependency.

1.1.0-beta.84 (2022-03-10)

Features

  • Implemented support for API registry links on the redocly.com domain.
  • Upgraded the Reference docs package to 2.12.3 - check the Reference docs changelog for details about this version.

Fixes

  • Resolved an issue with Markdown references to symlinks.

1.1.0-beta.83 (2022-03-03)

Features

  • Implemented support for linting API definitions from the API registry. To use this feature, either add the --lint-registry-definitions option to the portal build command, or set up the REDOCLY_LINT_REGISTRY_DEFINITIONS environment variable.
  • Upgraded the Reference docs package to 2.12.2 - check the Reference docs changelog for details about this version.

Fixes

  • Resolved an issue with the link checker in preview builds.
  • Resolved an issue with the GithubSlugger import when upgrading to a new portal version.
  • To improve the security of portal dependencies, we migrated from shortid to nanoid package.
  • Resolved an issue with incorrect spacing in nested lists

1.1.0-beta.82 (2022-02-17)

Features

Fixes

  • Resolved an issue with RBAC not applying configured permissions to assets (linked files).
  • Resolved an issue with mutation breaking RBAC in build mode.

1.1.0-beta.81 (2022-02-11)

Features

Fixes

  • Resolved an issue that caused className errors in the browser console on MDX pages.
  • Resolved an issue that caused warnings about resolving dependencies in the build log.
  • Resolved an issue with request body example linting in OpenApiTryIt component.

1.1.0-beta.80 (2022-02-04)

Features

Fixes

  • Resolved an issue with hot-reloading of OAS definition files.
  • Resolved an issue with invalid mobile sidebar icon color in some cases.
  • Resolved an issue with Gatsby version update crashing builds.
  • Resolved an issue with support for multiple sidebars.yaml files on Windows.

1.1.0-beta.79 (2022-01-27)

Fixes

  • Resolved an issue with build failure on Node 17.x.

1.1.0-beta.78 (2022-01-20)

Features

  • This release adds support for multiple sidebars.yaml files and introduces changes to sidebar configuration in the portal. For complete instructions, make sure to read the migration guide.
  • Upgraded the Reference docs package to 2.9.4 - check the Reference docs changelog for details about this version.

1.1.0-beta.77 (2022-01-13)

Features

1.1.0-beta.76 (2022-01-06)

Features

Fixes

  • Resolved an issue with Navbar mobile menu disappears on the medium breakpoint.
  • Resolved an issue with missing area-label in the search input.

1.1.0-beta.75 (2021-12-28)

Features

1.1.0-beta.74 (2021-12-23)

Features

  • Locked the openapi-cli package version to 1.0.0-beta.67.
  • Upgraded the Reference docs package to 2.8.1 - check the Reference docs changelog for details about this version.

Fixes

  • Resolved an issue with broken links to security in preview.

1.1.0-beta.73 (2021-12-09)

Features

  • Added a new experimental feature --prefix-assets (can also be used as an environment variable REDOCLY_PREFIX_ASSETS). This is useful in cases when you need to set a custom prefix for all asset paths in order to load them from an external resource.
  • Upgraded the Reference docs package to 2.7.9 - check the Reference docs changelog for details about this version.

Fixes

  • Resolved an issue with dynamic hashes that were not properly stripped from canonical URLs.
  • Resolved an issue with prefixing search index with env variable REDOCLY_PREFIX_ASSETS.

1.1.0-beta.72 (2021-12-02)

Features

Fixes

  • Resolved an issue with the color of Delete app button in Apigee portal - changed it to primary.
  • Resolved an issue with broken links inside the Reference docs Markdown descriptions.

1.1.0-beta.71 (2021-11-25)

Features

  • Added support for amplitude analytics. For configuration settings check this page.
  • Added possibility to exclude page url from sitemap.xml using excludeFromSearch option in frontmatter.
  • securityDefaults property of OpenApiTryIt component can now accept a function. The number of function arguments depends on the number of dependencies specified in the needs property. Each argument should be provided in the form of a { request, response } object.
  • Added new component ExplainStep. It is designed to enhance Step by Step Guides with tips and instructions for every step.

Usage Example

import {
  OpenApiTryIt,
  Alert,
  scrollToHeading
 } from '@redocly/developer-portal/ui';

## Step 1: Upsert a customer

<OpenApiTryIt
  definitionId="core"
  operationId="CreateUser"
  id="step-1"
/>

<ExplainStep
  needs={['step-1']}
  placeholder={(step1) => {
    if(!step1) {
      return (
        <Alert variant="danger">
          We should take <strong><i>data.user.id</i></strong> from the body of the response
          and use it as a <strong><i>userId</i></strong> query parameter in the next requests.
        </Alert>
      )
    } else {
      return (
        <Alert variant="success">
          <strong>User Id: {step1.response.body.data.user.id}</strong>
        </Alert>
      )
    }
  }}
/>

## Step 2: ...

Fixes

  • Resolved an issue with missing copy button in Markdown snippets.
  • Resolved an issue with hash links to integrated Reference pages not working properly when pagination is set to none.

1.1.0-beta.70 (2021-11-18)

Features

  • Upgraded the Reference docs package to 2.7.0 - check the Reference docs changelog for details about this version.
  • New utility function scrollToHeading exported from @redocly/developer-portal/ui.
  • Added a number of new properties to the OpenApiTryIt component to help you create interactive step-by-step guides. The new properties are:
    • id (optional)
    • needs (optional)
    • placeholder (optional)
    • serverVariables (optional)

id property is required if subsequent OpenApiTryIt instances rely on the response of the current component.

needs property should contain an array of Ids of preceding OpenApiTryIt components if it relies on their response bodies.

placeholder accepts a function that returns a component that is shown instead of OpenApiTryIt if it does not have enough information to perform a "Try It" request.

serverVariables accepts an object or a function that should return an object with server variables overrides. In case it's a function, the number of its arguments depends on the number of dependencies specified in the needs property. For more information about server variables, please, follow this link. You can also check out the example below.

We also improved some of the existing properties in the component:

  • properties can now accept a function. The number of function arguments depends on the number of dependencies specified in the needs property. Each argument should be provided in the form of a { request, response } object. The function should return a new object that is merged with the default body schema.

  • parameters can now accept a function. The number of function arguments depends on the number of dependencies specified in the needs property. Each argument should be provided in the form of a { request, response } object.

  • the defaultExample property now can take the false value. In this case, the Request Body in OpenApiTryIt component is entirely overridden by the user-provided properties object.

Usage Example

import {
  OpenApiTryIt,
  Alert,
  scrollToHeading
 } from '@redocly/developer-portal/ui';

## Step 1: Upsert a customer

<OpenApiTryIt
  definitionId="core"
  operationId="CreateUser"
  id="step-1"
  properties={{
    firstName: "John",
    lastName: "Smith"
  }}
  serverVariables={{
    // Example of server url: https://api.example.com/org/{organizationId}
    organizationId: {
      default: 'Google',
      enum: ['Redocly', 'Rebilly']
    }
  }}
  onResponse={({ response }) => {
    if (response.ok) {
      scrollToHeading('#step-2-create-an-order')
    }
  }}
/>

We need to use the userId in the next request.

## Step 2: Create an order

<OpenApiTryIt
  definitionId="core"
  operationId="PlaceOrder"
  id="step-2"
  needs={['step-1']}
  properties={{
    cartId: '8bb31d4b-0b88-4a29-9f08-a2af65f95dcf'
  }}
  parameters={(step1) => ({
    query: {
      userId: step1.response.body.data.user.id
    }
  })}
  placeholder={(step1) => {
    return <Alert variant="warning">Please complete step 1</Alert>
  }}
/>

Fixes

  • Resolved an issue with missing description in type ContentItemSeo type.
  • Resolved an issue with Node 17 compatibility.
  • Resolved an issue with overriding parameters in OpenApiTryIt component when parameters in definition are defined on the path item level.
  • Resolved an issue with Reference docs anchor links in Developer portal preview builds.

1.1.0-beta.69 (2021-11-11)

  • We have reorganized configuration options for modifying the <head> contents in your portal. Instead of adding these options to the meta section in siteConfig.yaml or to the top level of page front matter, you should now define them in a new section called seo. This means you can now use the same configuration syntax in front matter and in siteConfig.yaml - a big win for consistency!

Specifically, this affects the following configuration options:

  • description
  • image
  • keywords
  • title
  • lang
  • sitemap in front matter
  • siteUrl in the siteConfig.yaml file

and the x-meta specification extension supported in integrated Reference docs pages.

Compare the previous and the new configuration approach.

- meta:
-   title: Example Developer Portal
-   description: The best portal ever
-   image: example.png
-   keywords: documentation,portal,api
-
+ seo:
+   title: Example Developer Portal
+   description: The best portal ever
+   image: example.png
+   keywords: documentation,portal,api
+

- ---
- title: Supported Markdown features
- description: Using Markdown in your developer portal
- keywords: markdown,portal,documentation
- ---
-
+ ---
+ seo:
+   title: Supported Markdown features
+   description: Using Markdown in your developer portal
+   keywords: markdown,portal,documentation
+ ---
+
Important

We recommend migrating to the new configuration approach as soon as possible. Although currently supported, the old approach is considered deprecated and reports warnings in the portal build log.

Features

  • You can now set up JSON-LD parameters for your portal in the siteConfig.yaml file or in the front matter for individual MD(X) pages in the portal.
  • Upgraded the Reference docs package to 2.6.1 - check the Reference docs changelog for details about this version.
  • Upgraded the latest version of the openapi-cli package.

Fixes

  • Resolved an issue with TOC anchor links scrolling to a wrong area on a second click.
  • Resolved an issue with broken absolute links in previews.
  • Resolved an issue with symlinked Markdown files referenced from MDX files causing the build to crash.
  • Resolved an issue with the sitemap.xml file not found.
  • Resolved an issue with absolute links without path prefixes in Markdown snippets and MDX pages.

1.1.0-beta.68 (2021-11-02)

Fixes

  • Resolved an issue with the Reference docs version switcher getting overlapped when used with a drilldown-style sidebar.
  • Resolved an issue with H1 headings from Markdown files not used in sidebar labels.

1.1.0-beta.67 (2021-10-28)

Features

Fixes

  • Resolved an issue with the portal page table of contents not working with headings from reusable Markdown snippets.

1.1.0-beta.66 (2021-10-28)

Broken release.

1.1.0-beta.65 (2021-10-22)

Features

Fixes

  • Resolved an issue with the portal unnecessarily linting definitions from the registry when they should be skipped.

  • Resolved an issue with code block formatting inside the JsonSchema component.

  • Resolved an issue with the selectFirstItemOnExpand: true sidebar setting not working when RBAC is set up for the portal.

1.1.0-beta.64 (2021-10-19)

Fixes

  • Reverted a change to page TOC anchor links that caused issues in the previous two releases.

1.1.0-beta.63 (2021-10-19)

Broken release.

1.1.0-beta.62 (2021-10-18)

Broken release.

1.1.0-beta.61 (2021-10-15)

Fixes

  • Updated the openapi-core library with the latest version of js-yaml that includes fixes for recent issues.

  • Resolved an issue with integrated Reference docs crashing when using custom components that override the ThemeProvider.

1.1.0-beta.60 (2021-10-14)

Fixes

  • Reverted the change that added js-yaml from openapi-core in the previous version.

1.1.0-beta.59 (2021-10-13)

Features

  • The onResponse callback option in the OpenApiTryIt component now supports the request argument that allows it to inspect request data after performing a request.

  • The OpenApiTryIt component now supports the securityDefaults property that allows users to specify default values for security schemes in their example requests.

  • When using the Link component for custom login pages, previousPath now is present in location.state. This can be useful to get the referrer page and redirect back to it after the login.

  • Upgraded the Reference docs package to 2.3.0.

  • Added the js-yaml package from openapi-core and removed js-yaml from portal dependencies.

1.1.0-beta.58 (2021-10-11)

Features

  • The portal now supports a global configuration file for custom redirects. The file must be named redirects.yaml or redirects.json and stored in the root directory of the portal project. The contents of the file should map each source URL to one or more destination URLs, and optionally specify the redirect type. Here's an example redirects.yaml file:
'/some-old-url/':
  to: '/new-url/'
  type: 301
'/some-other-old-url':
  to: '/new-url/'

Fixes

  • Resolved an issue with + symbol encoding in operationId values and in file names.

  • Emacs lock fils are now automatically ignored to prevent crashing the portal on some file systems.

1.1.0-beta.57 (2021-10-06)

Features

  • You can now set the default MIME type for code samples in the OpenApiCodeSample component. Use the defaultMimeType configuration option to set the default MIME type, and the onlyDefaultMimeType option to show only the preset MIME type in code samples. This feature is entirely optional, and code samples retain their previous behavior if these options are omitted.

  • The OpenApiTryIt component now supports an optional onResponse callback that can be used to work with the response data after a successful request. In the following example, the callback is used to forward the response data to the log:

<OpenApiTryIt
  definitionId="petstore"
  operationId="addPet"
  defaultExample="bee"
  onResponse={(data) => console.log('data: ', data)}
/>

  • You can now configure search indexing depth for integrated Reference docs with the searchMaxDepth option. Set it to a number from 1 to 10 to control the maximum level of nested references that should be included in the search index. The default value is 8.

  • Your portal visitors can now interactively resize the columns in any table by dragging the separators between column names in the table header.

  • Upgraded the Reference docs package to 2.1.24 - check the Reference docs changelog for details about this version.

Fixes

  • Resolved a sidebar scrolling issue when using menuStyle: drilldown which resulted in the sidebar content overlapping and displaying duplicated artifacts.

  • Resolved an issue with the page table of contents exceeding the page width.

1.1.0-beta.56 (2021-09-29)

Fixes

  • Removed unnecessary border styling around code blocks.

1.1.0-beta.55 (2021-09-28)

Features

  • Markdown code blocks now have a handy Copy button, so you can copy the entire code block with one click! This feature is global (affects all pages in the portal) and it's enabled by default in the 1.1.0-beta.55 version.

To disable it, add the following to your siteConfig.yaml file:

copyCodeSnippet:
  enable: false

The copyCodeSnippet section supports options for configuring the copy button and the notification that appears after selecting it. Read more about it in the siteConfig documentation.

1.1.0-beta.54 (2021-09-28)

Features

  • You can now use the schemaExpansionLevel property in Portal components to set the default expansion behavior for schemas. To expand the whole schema contents, set it to all. If you set it to a specific number, schemas are expanded only up to that level. For example, schemaExpansionLevel: 3 automatically expands schema contents up to three levels.

The following Portal components support the schemaExpansionLevel property:

  • JsonSchema
  • OpenApiCodeSample
  • OpenApiExample
  • OpenApiRequestBody
  • OpenApiResponse
  • OpenApiTryIt

To configure the schema expansion level, add the property to the options object when inserting the component into a page.

Fixes

  • Resolved an issue with the background color of code blocks in MD(X) pages.

1.1.0-beta.53 (2021-09-28)

Fixes

  • Resolved an issue with search indexing of schema field names in the JsonSchema component.

  • Resolved a padding issue in the search box which caused the search icon to cover the text.

  • Resolved a caching issue with the local development server.

1.1.0-beta.52 (2021-09-26)

Fixes

  • Resolved issues with the page ToC links, and ToC settings for backwards compatibility.
  • Resolved issues with the logo settings. For backwards compatibility, if there is no logo href defined, we default to /.

1.1.0-beta.51 (2021-09-24)