From 1b4e8f8a8536053979bb18b0891cde5382ef550d Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 13 Oct 2026 10:37:35 -0500 Subject: [PATCH 1/6] Add page layout section Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/pages-and-content.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/app/dev-portal/pages-and-content.md b/app/dev-portal/pages-and-content.md index 2e4f34819f6..2dd27b50a83 100644 --- a/app/dev-portal/pages-and-content.md +++ b/app/dev-portal/pages-and-content.md @@ -122,6 +122,20 @@ about ← URL: "/about" ``` {:.no-copy-code} +### Page layouts + +Instead of starting from a blank page, you can build a page from a pre-built layout. Set the layout in the page's front matter with the `layout` property. A page that omits `layout`, or names one that doesn't exist, uses `custom`. + +The following layouts are available: + +* `custom` (default): No built-in chrome. You build the whole page yourself, including sidebars and header. Use this for a landing page or anything the other layouts don't fit. Because `custom` doesn't render a title or description from front matter, give the page its own heading in the body. +* `guide`: Contains navigation, content, and a table of contents. Use this for long-form documentation where readers browse sibling pages and jump to a section. +* `reference`: Contains navigation and content. Use this for shorter conceptual pages. +* `wide`: Contains navigation and content, but the contents space has a wider column. Use this for content that needs more horizontal room, like a wide table or a generated API reference. +* `center`: A single centered column, without sidebars. Use this for release notes or articles. + +For information about how to customize a layout's sidebars and header, or configure page navigation, see the [Markdown Components reference](https://portaldocs.konghq.com/). + ### Page visibility and publishing You can choose to make a page public or private and publish or unpublish it. To control page visibility and publishing, click a page in the Portal Editor and click the menu at the top right. From 47f99186c2f63551ed2d384606a932397fe74ae8 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Fri, 16 Oct 2026 10:22:32 -0500 Subject: [PATCH 2/6] add sidebar nav stuff Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- .../customizations/dev-portal-customizations.yaml | 6 ++++++ app/dev-portal/pages-and-content.md | 13 ++++++++++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml index 7a7b8ebad48..4c1bd088df6 100644 --- a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml +++ b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml @@ -164,6 +164,12 @@ rows: * **Main menu**: Main menus are a flat list of links that will be added to the header of every page in your {{site.dev_portal}}. These titles and links will be spaced evenly horizontally. You can also add external links to all {{site.dev_portal}} menu items either using the {{site.konnect_short_name}} UI or the [`/portals/{portalId}/customization` endpoint](/api/konnect/portal-management/v3/#/operations/update-portal-customization). * **Footer menu sections**: Footer menus allow you to create a set of columns with links for global navigation. Select **Footer Sections Menu** from the dropdown list to begin creating your menus. Footer sections create vertical columns across the bottom of every page, with the logo from [Appearance](#appearance) on the left side. We recommend creating your desired footer sections before creating footer menu items. Footer menu items are links to any URL you prefer, with a title to be displayed. Items must specify a footer menu section. * **Footer bottom menu**: Footer bottom menu is a flat list of links that will be added to the bottom of every page. Footer bottom menus are placed below footer menu sections. + * **Sidebar navigation**: The sidebar navigation menu is a vertical list of links that displays on the left side of the page. + You can configure this in the **Sidebar Navigation** section of the Portal Editor or using the [`/portals/{portalId}/customization/navigations` endpoint](/api/konnect/portal-management/). + Whether a sidebar menu is displayed depends on the [page layout](/dev-portal/pages-and-content/#page-layouts). + You can choose to have one sidebar menu for all pages by only adding a single `/` navigation entry with links in the group, or split your sidebar menu into different sections (for example, `/getting-started` and `/guides`). + You can also omit a sidebar menu for a section, which is useful for content like release notes. + Individual links can be restricted to signed-in developers, and you can also add external links. - blocks: - type: image config: diff --git a/app/dev-portal/pages-and-content.md b/app/dev-portal/pages-and-content.md index 2dd27b50a83..765dda26b7f 100644 --- a/app/dev-portal/pages-and-content.md +++ b/app/dev-portal/pages-and-content.md @@ -122,6 +122,9 @@ about ← URL: "/about" ``` {:.no-copy-code} +The sidebar navigation menu that displays next to a page isn't derived from this page structure. +It's configured separately, as described in [{{site.dev_portal}} navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation). + ### Page layouts Instead of starting from a blank page, you can build a page from a pre-built layout. Set the layout in the page's front matter with the `layout` property. A page that omits `layout`, or names one that doesn't exist, uses `custom`. @@ -129,11 +132,15 @@ Instead of starting from a blank page, you can build a page from a pre-built lay The following layouts are available: * `custom` (default): No built-in chrome. You build the whole page yourself, including sidebars and header. Use this for a landing page or anything the other layouts don't fit. Because `custom` doesn't render a title or description from front matter, give the page its own heading in the body. -* `guide`: Contains navigation, content, and a table of contents. Use this for long-form documentation where readers browse sibling pages and jump to a section. -* `reference`: Contains navigation and content. Use this for shorter conceptual pages. -* `wide`: Contains navigation and content, but the contents space has a wider column. Use this for content that needs more horizontal room, like a wide table or a generated API reference. +* `guide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation), content, and a table of contents. Use this for long-form documentation where readers browse sibling pages and jump to a section. +* `reference`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) and content. Use this for shorter conceptual pages. +* `wide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) and content, but the contents space has a wider column. Use this for content that needs more horizontal room, like a wide table or a generated API reference. * `center`: A single centered column, without sidebars. Use this for release notes or articles. +On `guide`, `reference`, `wide`, and `center`, the page header is built from front matter you're already writing: `title` and `description` render in the header, and an optional `tagline` property renders as a short label above the title. + +Any section a layout renders (a sidebar or the header) can be replaced with a snippet using the `layout-options` front matter property. + For information about how to customize a layout's sidebars and header, or configure page navigation, see the [Markdown Components reference](https://portaldocs.konghq.com/). ### Page visibility and publishing From 89c780a48fd9b65ab29d354299319406fc6efad7 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:49:27 -0500 Subject: [PATCH 3/6] Apply batched suggestions from code review Co-authored-by: Adam DeHaven <2229946+adamdehaven@users.noreply.github.com> --- .../customizations/dev-portal-customizations.yaml | 2 +- app/dev-portal/pages-and-content.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml index 4c1bd088df6..d844f919c2c 100644 --- a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml +++ b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml @@ -164,7 +164,7 @@ rows: * **Main menu**: Main menus are a flat list of links that will be added to the header of every page in your {{site.dev_portal}}. These titles and links will be spaced evenly horizontally. You can also add external links to all {{site.dev_portal}} menu items either using the {{site.konnect_short_name}} UI or the [`/portals/{portalId}/customization` endpoint](/api/konnect/portal-management/v3/#/operations/update-portal-customization). * **Footer menu sections**: Footer menus allow you to create a set of columns with links for global navigation. Select **Footer Sections Menu** from the dropdown list to begin creating your menus. Footer sections create vertical columns across the bottom of every page, with the logo from [Appearance](#appearance) on the left side. We recommend creating your desired footer sections before creating footer menu items. Footer menu items are links to any URL you prefer, with a title to be displayed. Items must specify a footer menu section. * **Footer bottom menu**: Footer bottom menu is a flat list of links that will be added to the bottom of every page. Footer bottom menus are placed below footer menu sections. - * **Sidebar navigation**: The sidebar navigation menu is a vertical list of links that displays on the left side of the page. + * **Sidebar navigation**: The sidebar navigation menu is a grouped, vertical list of links that displays on the left side of the page. You can configure this in the **Sidebar Navigation** section of the Portal Editor or using the [`/portals/{portalId}/customization/navigations` endpoint](/api/konnect/portal-management/). Whether a sidebar menu is displayed depends on the [page layout](/dev-portal/pages-and-content/#page-layouts). You can choose to have one sidebar menu for all pages by only adding a single `/` navigation entry with links in the group, or split your sidebar menu into different sections (for example, `/getting-started` and `/guides`). diff --git a/app/dev-portal/pages-and-content.md b/app/dev-portal/pages-and-content.md index 765dda26b7f..462280c8441 100644 --- a/app/dev-portal/pages-and-content.md +++ b/app/dev-portal/pages-and-content.md @@ -127,14 +127,14 @@ It's configured separately, as described in [{{site.dev_portal}} navigation](/de ### Page layouts -Instead of starting from a blank page, you can build a page from a pre-built layout. Set the layout in the page's front matter with the `layout` property. A page that omits `layout`, or names one that doesn't exist, uses `custom`. +Instead of manually constructing the page content container with components, you can use a `layout` that offers a built-in arrangement of a page's regions. Set the layout in the page's front matter with the `layout` property. A page that omits `layout`, or names one that doesn't exist, uses `custom`. The following layouts are available: * `custom` (default): No built-in chrome. You build the whole page yourself, including sidebars and header. Use this for a landing page or anything the other layouts don't fit. Because `custom` doesn't render a title or description from front matter, give the page its own heading in the body. -* `guide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation), content, and a table of contents. Use this for long-form documentation where readers browse sibling pages and jump to a section. -* `reference`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) and content. Use this for shorter conceptual pages. -* `wide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) and content, but the contents space has a wider column. Use this for content that needs more horizontal room, like a wide table or a generated API reference. +* `guide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) on the left, content, and a table of contents on the right. Use this for long-form documentation where readers browse sibling pages and jump to a section. +* `reference`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) on the left, and centered content. Use this for shorter conceptual pages. +* `wide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) on the left and content, but the contents space has a wider column. Use this for content that needs more horizontal room, like a wide table or a generated API reference. * `center`: A single centered column, without sidebars. Use this for release notes or articles. On `guide`, `reference`, `wide`, and `center`, the page header is built from front matter you're already writing: `title` and `description` render in the header, and an optional `tagline` property renders as a short label above the title. From cfcab4a5f6eb929241fead02c0bdbfb7eabd1a46 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:23:32 -0500 Subject: [PATCH 4/6] apply rest of eng feedback Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- .../customizations/dev-portal-customizations.yaml | 4 ++-- app/dev-portal/pages-and-content.md | 7 +++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml index d844f919c2c..df48e3bd40f 100644 --- a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml +++ b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml @@ -157,7 +157,7 @@ rows: blocks: - type: text text: | - You can configure the main menu, footer, and footer bottom navigation menus in your {{site.dev_portal}}. + You can configure the main menu, footer, footer bottom, and sidebar navigation menus in your {{site.dev_portal}}. To configure navigation settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. In the Portal Editor sidebar, click the menu tree icon. @@ -166,7 +166,7 @@ rows: * **Footer bottom menu**: Footer bottom menu is a flat list of links that will be added to the bottom of every page. Footer bottom menus are placed below footer menu sections. * **Sidebar navigation**: The sidebar navigation menu is a grouped, vertical list of links that displays on the left side of the page. You can configure this in the **Sidebar Navigation** section of the Portal Editor or using the [`/portals/{portalId}/customization/navigations` endpoint](/api/konnect/portal-management/). - Whether a sidebar menu is displayed depends on the [page layout](/dev-portal/pages-and-content/#page-layouts). + You **must** select a [page layout](/dev-portal/pages-and-content/#page-layouts) that supports a sidebar menu, otherwise it won't render. You can choose to have one sidebar menu for all pages by only adding a single `/` navigation entry with links in the group, or split your sidebar menu into different sections (for example, `/getting-started` and `/guides`). You can also omit a sidebar menu for a section, which is useful for content like release notes. Individual links can be restricted to signed-in developers, and you can also add external links. diff --git a/app/dev-portal/pages-and-content.md b/app/dev-portal/pages-and-content.md index 462280c8441..439809cfef7 100644 --- a/app/dev-portal/pages-and-content.md +++ b/app/dev-portal/pages-and-content.md @@ -131,17 +131,20 @@ Instead of manually constructing the page content container with components, you The following layouts are available: -* `custom` (default): No built-in chrome. You build the whole page yourself, including sidebars and header. Use this for a landing page or anything the other layouts don't fit. Because `custom` doesn't render a title or description from front matter, give the page its own heading in the body. * `guide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) on the left, content, and a table of contents on the right. Use this for long-form documentation where readers browse sibling pages and jump to a section. * `reference`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) on the left, and centered content. Use this for shorter conceptual pages. * `wide`: Contains [sidebar navigation](/dev-portal/customizations/dev-portal-customizations/#dev-portal-navigation) on the left and content, but the contents space has a wider column. Use this for content that needs more horizontal room, like a wide table or a generated API reference. * `center`: A single centered column, without sidebars. Use this for release notes or articles. +* `custom` (default): You must build the whole page yourself, including sidebars and header. Use this for a landing page or anything the other layouts don't fit. Because `custom` doesn't render a title or description from front matter, give the page its own heading in the body. On `guide`, `reference`, `wide`, and `center`, the page header is built from front matter you're already writing: `title` and `description` render in the header, and an optional `tagline` property renders as a short label above the title. Any section a layout renders (a sidebar or the header) can be replaced with a snippet using the `layout-options` front matter property. -For information about how to customize a layout's sidebars and header, or configure page navigation, see the [Markdown Components reference](https://portaldocs.konghq.com/). +For information about how to customize a layout's sidebars and header, or configure page navigation, see the [Markdown Components reference](https://portaldocs.konghq.com/): +* [Pages (including front matter)](https://portaldocs.konghq.com/pages/overview) +* [Layouts](https://portaldocs.konghq.com/pages/layouts) +* [Layout options](https://portaldocs.konghq.com/pages/layout-options) ### Page visibility and publishing From f9e74fef5e28361aa62e1c7b3dd8a4bcd414be69 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Thu, 22 Oct 2026 15:28:22 -0500 Subject: [PATCH 5/6] convert to reference page Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- .../dev-portal-customizations.yaml | 343 ------------------ app/dev-portal/dev-portal-customizations.md | 220 +++++++++++ 2 files changed, 220 insertions(+), 343 deletions(-) delete mode 100644 app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml create mode 100644 app/dev-portal/dev-portal-customizations.md diff --git a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml b/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml deleted file mode 100644 index df48e3bd40f..00000000000 --- a/app/_landing_pages/dev-portal/customizations/dev-portal-customizations.yaml +++ /dev/null @@ -1,343 +0,0 @@ -metadata: - title: "{{site.dev_portal}} customizations" - content_type: landing_page - description: Customize the look, structure, and access of your {{site.dev_portal}} with flexible page controls and branding options - products: - - dev-portal - works_on: - - konnect -breadcrumbs: - - /dev-portal/ -rows: - - - header: - type: h1 - text: "{{site.dev_portal}} customizations" - sub_text: Customize the look, structure, and access of your {{site.dev_portal}} with flexible page controls and branding options - - - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - You can customize your {{site.dev_portal}}s with the following features: - - Configure layout, navigation, branding, and domain settings. - - Build content-rich pages with Markdown Components, nest information, and reuse snippets. - - Manage page visibility, publishing workflow, and SEO metadata. - - Customize global appearance, apply custom CSS, and set up menus and navigation structures. - - Set up and manage custom domains, SSL certificates, and URL paths. - - The preview will automatically show what your page should look like when developers view your {{site.dev_portal}}. In the event that it fails to refresh after editing the page, there is a refresh button next to the generated URL at the bottom. - - There are three icons above **Preview** that allow you to test adaptive designs in some predefined viewports: - * Desktop - * Tablet - * Mobile - - blocks: - - type: image - config: - url: /assets/images/dev-portal/kongair-example.png - alt_text: "KongAir Dev Portal" - - header: - type: h2 - text: "Pages and content" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - In your {{site.dev_portal}}, you can create pages that contain content such as text, buttons, tabs, and more. - Pages are used to convey information about your API and {{site.dev_portal}} to users. - They are highly customizable using Markdown Components (MDC), allowing you to create nested page structures to organize pages and generate URLs or slugs. - You can also stage new pages or restrict access to logged-in developers by using visibility controls and publishing status. - - To configure pages and content, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. - In the Portal Editor sidebar, click the folder icon. - You can also manage pages and content using the [{{site.konnect_product_name}} MCP Server](/konnect-platform/konnect-mcp/). - - blocks: - - type: image - config: - url: /assets/images/dev-portal/dev-portal-editor.png - alt_text: "KongAir Dev Portal" - - column_count: 3 - columns: - - blocks: - - type: card - config: - title: Pages and content - description: | - Create pages in your {{site.dev_portal}} to share API information with users. Pages support text, buttons, tabs, and more using Markdown Components (MDC). Organize them in nested structures, control visibility, stage drafts, and customize URLs. - icon: /assets/icons/markdown.svg - cta: - url: /dev-portal/pages-and-content/ - - blocks: - - type: card - config: - title: "{{site.dev_portal}} MDC docs" - description: | - Create a {{site.dev_portal}} tailored to your organization with flexible layouts, customizable components, and brand-aligned design elements. - icon: /assets/icons/code.svg - cta: - url: https://portaldocs.konghq.com/ - - blocks: - - type: card - config: - title: "{{site.dev_portal}} global settings" - description: | - Make global changes such as naming your portal, setting the display name used for SEO and page titles. Configure custom domains and review audit logs specific to your {{site.dev_portal}}. - icon: /assets/icons/dev-portal.svg - cta: - url: /dev-portal/portal-settings/ - - blocks: - - type: card - config: - title: VS Code extension - description: | - Edit and view your {{site.dev_portal}} pages in real-time in Visual Studio Code. - Integrates with the {{site.konnect_short_name}} API and kongctl to securely manage {{site.dev_portal}} content. - icon: /assets/icons/vscode.png - cta: - url: https://marketplace.visualstudio.com/items?itemName=konghq.vscode-konnect-dev-portal-toolkit - - blocks: - - type: card - config: - title: "{{site.konnect_product_name}} MCP Server" - description: | - Manage {{site.dev_portal}} pages, snippets, and Markdown Components (MDC) from your AI assistant or IDE using the {{site.konnect_product_name}} MCP Server. - icon: /assets/icons/mcp.svg - cta: - url: /konnect-platform/konnect-mcp/ - - - header: - type: h2 - text: "Appearance" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - Appearance settings are applied globally to all pages in your {{site.dev_portal}}. For advanced needs, you can also create custom CSS that applies custom styles to your {{site.dev_portal}}. Custom CSS provides global customization to all pages in {{site.dev_portal}}. - To configure appearance settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. In the Portal Editor sidebar, click the paint bucket icon. - - Basic appearance settings quickly create basic styles for your default Portal template: - - type: table - config: - columns: - - title: Setting - key: setting - - title: Description - key: description - rows: - - setting: Theme - description: You can choose from default light and dark options. This changes the background and text in your default template. Dark or light theme is not selectable by developers. - - setting: Brand color - description: This color is used to set the primary color in the default template. - - setting: Portal logo - description: Automatically used in the header and footer menu sections to ensure consistent branding across pages. - - setting: Favicon - description: Icon displayed in the browser tab and Favorites for {{site.dev_portal}} visitors. - - blocks: - - type: image - config: - url: /assets/images/dev-portal/dev-portal-appearance.png - alt_text: "KongAir Dev Portal" - - header: - type: h2 - text: "{{site.dev_portal}} navigation" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - You can configure the main menu, footer, footer bottom, and sidebar navigation menus in your {{site.dev_portal}}. - To configure navigation settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. - In the Portal Editor sidebar, click the menu tree icon. - - * **Main menu**: Main menus are a flat list of links that will be added to the header of every page in your {{site.dev_portal}}. These titles and links will be spaced evenly horizontally. You can also add external links to all {{site.dev_portal}} menu items either using the {{site.konnect_short_name}} UI or the [`/portals/{portalId}/customization` endpoint](/api/konnect/portal-management/v3/#/operations/update-portal-customization). - * **Footer menu sections**: Footer menus allow you to create a set of columns with links for global navigation. Select **Footer Sections Menu** from the dropdown list to begin creating your menus. Footer sections create vertical columns across the bottom of every page, with the logo from [Appearance](#appearance) on the left side. We recommend creating your desired footer sections before creating footer menu items. Footer menu items are links to any URL you prefer, with a title to be displayed. Items must specify a footer menu section. - * **Footer bottom menu**: Footer bottom menu is a flat list of links that will be added to the bottom of every page. Footer bottom menus are placed below footer menu sections. - * **Sidebar navigation**: The sidebar navigation menu is a grouped, vertical list of links that displays on the left side of the page. - You can configure this in the **Sidebar Navigation** section of the Portal Editor or using the [`/portals/{portalId}/customization/navigations` endpoint](/api/konnect/portal-management/). - You **must** select a [page layout](/dev-portal/pages-and-content/#page-layouts) that supports a sidebar menu, otherwise it won't render. - You can choose to have one sidebar menu for all pages by only adding a single `/` navigation entry with links in the group, or split your sidebar menu into different sections (for example, `/getting-started` and `/guides`). - You can also omit a sidebar menu for a section, which is useful for content like release notes. - Individual links can be restricted to signed-in developers, and you can also add external links. - - blocks: - - type: image - config: - url: /assets/images/dev-portal/dev-portal-navigation.png - alt_text: "KongAir Dev Portal" - - - header: - type: h2 - text: "API specification settings" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - The API specification settings allow you to control how developers can interact with your API specs in your {{site.dev_portal}}. To configure API spec settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. In the Portal Editor sidebar, click the code brackets icon. - - The following table describes the API spec settings you can configure: - - blocks: - - type: table - config: - columns: - - title: Setting - key: setting - - title: Description - key: description - rows: - - setting: Show Try it - description: Enable in-browser testing for your APIs. All linked gateways must have the CORS plugin configured. For more information, see [Allow developers to try requests from the {{site.dev_portal}} spec renderer](/catalog/apis/#allow-developers-to-try-requests-from-the-dev-portal-spec-renderer). - - setting: Show Try it in Insomnia - description: Enables users to open the API spec in [Insomnia](/insomnia/) to explore and send requests with the native client. - - setting: Continuous scroll - description: Display the full spec on a single, scrollable page. If disabled, documentation, endpoints, and schemas appear on separate pages. - - setting: Show schemas - description: Control whether schemas are visible in your API specs. When enabled, schemas appear in the side navigation below the endpoints. - - setting: Hide deprecated endpoints - description: Manage visibility of deprecated endpoints and models. - - setting: Hide internal endpoints - description: Manage visibility of internal endpoints and models. - - setting: Allow custom server URL - description: Let users define a custom server URL for endpoints. This will be used to generate code snippets and to test the API. The URL is client_side only and is not saved. - - header: - type: h2 - text: "Custom forms" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - {% include_cached sections/custom-form-tutorials.md %} - - Custom forms let you add configurable fields to the developer registration form or to a per-API application registration form, so you can capture the information you need to make approval decisions. - - There are two types of custom forms: - * **Developer registration form**: One per {{site.dev_portal}}. Once published, it replaces the default developer sign-up form. If you create the form via the API, you must include the required `full_name` and `email` fields yourself, along with any other additional fields you want. - * **API registration forms**: You can create multiple forms and assign one to each API publication. APIs without an assigned form use the default registration flow, with no extra fields. - - Use cases for custom forms include: - {% include_cached sections/custom-form-use-cases.md %} - - {% include_cached sections/custom-form-constraints.md %} - - The table shows which field types are available when building a form. - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - {% include_cached sections/custom-form-field-types.md %} - - header: - type: h2 - text: "Developer email customization" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - You can customize both the email domain and content of emails that developers receive for the following events: - * Welcome (developer sign-up approved) - * App registration approved - * App registration rejected - * App registration revoked - * [API key expired](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) - * [API key expiring soon](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) - * Confirm email address - * Reset password - * Account access rejected - * Account access revoked - - To configure email customization settings, go to your {{site.dev_portal}}, click **Portal Editor**, and then click the **Email** icon in the sidebar. - - In the customization settings, you can use variables. For example, `{% raw %}{{application_name}}{% endraw %}` will be replaced with the name of the application in the email. - - The following table contains the variables you can use when customizing emails: - - blocks: - - type: table - config: - columns: - - title: Variable - key: variable - - title: Description - key: description - rows: - - variable: "{{api_documentation_url}}" - description: The documentation URL for the API. - - variable: "{{api_name}}" - description: The name of the API. - - variable: "{{api_version}}" - description: The version of the API. - - variable: "{{application_name}}" - description: The name of the developer's application. - - variable: "{{credential_name}}" - description: The name of the key auth credential. - - variable: "{{credential_expires_at}}" - description: "The date when the [key auth credential expires](/dev-portal/auth-strategies/#configure-the-key-auth-strategy)." - - variable: "{{dev_portal_reply_to}}" - description: The {{site.dev_portal}} reply-to email address. - - variable: "{{developer_email}}" - description: The email address of the developer. - - variable: "{{developer_fullname}}" - description: The full name of the developer. - - variable: "{{developer_status}}" - description: The {{site.dev_portal}} status of a developer. For example, \"approved\", \"pending\", or \"revoked\". - - variable: "{{portal_display_name}}" - description: The display name of the {{site.dev_portal}}. - - variable: "{{portal_domain}}" - description: The URL of the {{site.dev_portal}}. - - header: - type: h3 - text: "Customize the email domain" - columns: - - blocks: - - type: structured_text - config: - blocks: - - type: text - text: | - If you want to change the from and reply-to email domains, you can configure a different domain through {{site.dev_portal}} settings. - Navigate to your {{site.dev_portal}}, click **Settings** in the sidebar and click the **Custom domains** tab. Click **New email domain** and configure the settings. - - Once you've added your new domain, you must add the CNAME records to your DNS server. - - {:.info} - > Certain domain names are restricted. See [Domain name restrictions](/dev-portal/custom-domains/#domain-name-restrictions) for more information. - - blocks: - - type: card - config: - title: Custom domains - description: | - Set up custom URLs for your {{site.dev_portal}}. - Custom URLs require DNS setup and your portal's default URL. - icon: /assets/icons/domain.svg - cta: - url: /dev-portal/custom-domains/ - - - header: - text: "Frequently asked questions" - type: h2 - columns: - - blocks: - - type: faqs - config: - - q: How do I customize the reply-to and from for {{site.dev_portal}} emails? - a: | - {% include faqs/portal-email.md %} diff --git a/app/dev-portal/dev-portal-customizations.md b/app/dev-portal/dev-portal-customizations.md new file mode 100644 index 00000000000..e3d796d53d7 --- /dev/null +++ b/app/dev-portal/dev-portal-customizations.md @@ -0,0 +1,220 @@ +--- +title: "{{site.dev_portal}} customizations" +content_type: reference +layout: reference +permalink: /dev-portal/customizations/dev-portal-customizations/ + +breadcrumbs: + - /dev-portal/ + +products: + - dev-portal + +works_on: + - konnect + +description: "Customize the look, structure, and access of your {{site.dev_portal}} with flexible page controls and branding options" + +related_resources: + - text: Pages and content + url: /dev-portal/pages-and-content/ + - text: "{{site.dev_portal}} MDC docs" + url: https://portaldocs.konghq.com/ + - text: "{{site.dev_portal}} global settings" + url: /dev-portal/portal-settings/ + - text: VS Code extension + url: https://marketplace.visualstudio.com/items?itemName=konghq.vscode-konnect-dev-portal-toolkit + - text: "{{site.konnect_short_name}} MCP Server" + url: /konnect-platform/konnect-mcp/ + - text: Custom domains + url: /dev-portal/custom-domains/ + +faqs: + - q: How do I customize the reply-to and from for {{site.dev_portal}} emails? + a: | + {% include faqs/portal-email.md %} +--- + +You can customize your {{site.dev_portal}}s with the following features: +- Configure layout, navigation, branding, and domain settings. +- Build content-rich pages with Markdown Components, nest information, and reuse snippets. +- Manage page visibility, publishing workflow, and SEO metadata. +- Customize global appearance, apply custom CSS, and set up menus and navigation structures. +- Set up and manage custom domains, SSL certificates, and URL paths. + +The preview will automatically show what your page should look like when developers view your {{site.dev_portal}}. In the event that it fails to refresh after editing the page, there is a refresh button next to the generated URL at the bottom. + +There are three icons above **Preview** that allow you to test adaptive designs in some predefined viewports: +* Desktop +* Tablet +* Mobile + +## Pages and content + +In your {{site.dev_portal}}, you can [create pages](/dev-portal/pages-and-content/) that contain content such as text, buttons, tabs, and more. +Pages are used to convey information about your API and {{site.dev_portal}} to users. +They are highly customizable using [Markdown Components (MDC)](https://portaldocs.konghq.com/), allowing you to create nested page structures to organize pages and generate URLs or slugs. +You can also stage new pages or restrict access to logged-in developers by using visibility controls and publishing status. + +To configure pages and content, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. +In the Portal Editor sidebar, click the folder icon. +You can also manage pages and content using the [{{site.konnect_product_name}} MCP Server](/konnect-platform/konnect-mcp/). + +## Appearance + +Appearance settings are applied globally to all pages in your {{site.dev_portal}}. For advanced needs, you can also create custom CSS that applies custom styles to your {{site.dev_portal}}. Custom CSS provides global customization to all pages in {{site.dev_portal}}. +To configure appearance settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. In the Portal Editor sidebar, click the paint bucket icon. + +Basic appearance settings quickly create basic styles for your default Portal template: + +{% table %} +columns: + - title: Setting + key: setting + - title: Description + key: description +rows: + - setting: Theme + description: You can choose from default light and dark options. This changes the background and text in your default template. Dark or light theme is not selectable by developers. + - setting: Brand color + description: This color is used to set the primary color in the default template. + - setting: Portal logo + description: Automatically used in the header and footer menu sections to ensure consistent branding across pages. + - setting: Favicon + description: Icon displayed in the browser tab and Favorites for {{site.dev_portal}} visitors. +{% endtable %} + +## {{site.dev_portal}} navigation + +You can configure the main menu, footer, footer bottom, and sidebar navigation menus in your {{site.dev_portal}}. +To configure navigation settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. +In the Portal Editor sidebar, click the menu tree icon. + +{% table %} +columns: + - title: Menu + key: menu + - title: Description + key: description +rows: + - menu: Main menu + description: Main menus are a flat list of links that will be added to the header of every page in your {{site.dev_portal}}. These titles and links will be spaced evenly horizontally. You can also add external links to all {{site.dev_portal}} menu items either using the {{site.konnect_short_name}} UI or the [`/portals/{portalId}/customization` endpoint](/api/konnect/portal-management/v3/#/operations/update-portal-customization). + - menu: Footer menu sections + description: Footer menus allow you to create a set of columns with links for global navigation. Select **Footer Sections Menu** from the dropdown list to begin creating your menus. Footer sections create vertical columns across the bottom of every page, with the logo from [Appearance](#appearance) on the left side. We recommend creating your desired footer sections before creating footer menu items. Footer menu items are links to any URL you prefer, with a title to be displayed. Items must specify a footer menu section. + - menu: Footer bottom menu + description: Footer bottom menu is a flat list of links that will be added to the bottom of every page. Footer bottom menus are placed below footer menu sections. + - menu: Sidebar navigation + description: | + The sidebar navigation menu is a grouped, vertical list of links that displays on the left side of the page. You can configure this in the **Sidebar Navigation** section of the Portal Editor or using the [`/portals/{portalId}/customization/navigations` endpoint](/api/konnect/portal-management/). You **must** select a [page layout](/dev-portal/pages-and-content/#page-layouts) that supports a sidebar menu, otherwise it won't render. You can choose to have one sidebar menu for all pages by only adding a single `/` navigation entry with links in the group, or split your sidebar menu into different sections (for example, `/getting-started` and `/guides`). You can also omit a sidebar menu for a section, which is useful for content like release notes. Individual links can be restricted to signed-in developers, and you can also add external links. +{% endtable %} + +## API specification settings + +The API specification settings allow you to control how developers can interact with your API specs in your {{site.dev_portal}}. To configure API spec settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. In the Portal Editor sidebar, click the code brackets icon. + +The following table describes the API spec settings you can configure: + +{% table %} +columns: + - title: Setting + key: setting + - title: Description + key: description +rows: + - setting: Show Try it + description: Enable in-browser testing for your APIs. All linked gateways must have the CORS plugin configured. For more information, see [Allow developers to try requests from the {{site.dev_portal}} spec renderer](/catalog/apis/#allow-developers-to-try-requests-from-the-dev-portal-spec-renderer). + - setting: Show Try it in Insomnia + description: Enables users to open the API spec in [Insomnia](/insomnia/) to explore and send requests with the native client. + - setting: Continuous scroll + description: Display the full spec on a single, scrollable page. If disabled, documentation, endpoints, and schemas appear on separate pages. + - setting: Show schemas + description: Control whether schemas are visible in your API specs. When enabled, schemas appear in the side navigation below the endpoints. + - setting: Hide deprecated endpoints + description: Manage visibility of deprecated endpoints and models. + - setting: Hide internal endpoints + description: Manage visibility of internal endpoints and models. + - setting: Allow custom server URL + description: Let users define a custom server URL for endpoints. This will be used to generate code snippets and to test the API. The URL is client_side only and is not saved. +{% endtable %} + +## Custom forms + +{% include_cached sections/custom-form-tutorials.md %} + +Custom forms let you add configurable fields to the developer registration form or to a per-API application registration form, so you can capture the information you need to make approval decisions. + +There are two types of custom forms: +* **Developer registration form**: One per {{site.dev_portal}}. Once published, it replaces the default developer sign-up form. If you create the form via the API, you must include the required `full_name` and `email` fields yourself, along with any other additional fields you want. +* **API registration forms**: You can create multiple forms and assign one to each API publication. APIs without an assigned form use the default registration flow, with no extra fields. + +Use cases for custom forms include: +{% include_cached sections/custom-form-use-cases.md %} + +{% include_cached sections/custom-form-constraints.md %} + +The table shows which field types are available when building a form. + +{% include_cached sections/custom-form-field-types.md %} + +## Developer email customization + +You can customize both the email domain and content of emails that developers receive for the following events: +* Welcome (developer sign-up approved) +* App registration approved +* App registration rejected +* App registration revoked +* [API key expired](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) +* [API key expiring soon](/dev-portal/auth-strategies/#configure-the-key-auth-strategy) +* Confirm email address +* Reset password +* Account access rejected +* Account access revoked + +To configure email customization settings, go to your {{site.dev_portal}}, click **Portal Editor**, and then click the **Email** icon in the sidebar. + +In the customization settings, you can use variables. For example, `{% raw %}{{application_name}}{% endraw %}` will be replaced with the name of the application in the email. + +The following table contains the variables you can use when customizing emails: + +{% table %} +columns: + - title: Variable + key: variable + - title: Description + key: description +rows: + - variable: "{{api_documentation_url}}" + description: The documentation URL for the API. + - variable: "{{api_name}}" + description: The name of the API. + - variable: "{{api_version}}" + description: The version of the API. + - variable: "{{application_name}}" + description: The name of the developer's application. + - variable: "{{credential_name}}" + description: The name of the key auth credential. + - variable: "{{credential_expires_at}}" + description: "The date when the [key auth credential expires](/dev-portal/auth-strategies/#configure-the-key-auth-strategy)." + - variable: "{{dev_portal_reply_to}}" + description: The {{site.dev_portal}} reply-to email address. + - variable: "{{developer_email}}" + description: The email address of the developer. + - variable: "{{developer_fullname}}" + description: The full name of the developer. + - variable: "{{developer_status}}" + description: The {{site.dev_portal}} status of a developer. For example, \"approved\", \"pending\", or \"revoked\". + - variable: "{{portal_display_name}}" + description: The display name of the {{site.dev_portal}}. + - variable: "{{portal_domain}}" + description: The URL of the {{site.dev_portal}}. +{% endtable %} + +### Customize the email domain + +If you want to change the from and reply-to email domains, you can configure a different domain through {{site.dev_portal}} settings. +Navigate to your {{site.dev_portal}}, click **Settings** in the sidebar and click the **Custom domains** tab. Click **New email domain** and configure the settings. + +Once you've added your new domain, you must add the CNAME records to your DNS server. + +{:.info} +> Certain domain names are restricted. See [Domain name restrictions](/dev-portal/custom-domains/#domain-name-restrictions) for more information. From 26448367aa6a629f8e7fc7007d3875a7aa8c113c Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Mon, 2 Nov 2026 15:01:13 -0600 Subject: [PATCH 6/6] vale and add sentence about themes Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/dev-portal/dev-portal-customizations.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/app/dev-portal/dev-portal-customizations.md b/app/dev-portal/dev-portal-customizations.md index e3d796d53d7..c0502b093dd 100644 --- a/app/dev-portal/dev-portal-customizations.md +++ b/app/dev-portal/dev-portal-customizations.md @@ -75,7 +75,7 @@ columns: key: description rows: - setting: Theme - description: You can choose from default light and dark options. This changes the background and text in your default template. Dark or light theme is not selectable by developers. + description: You can choose from default light and dark options. This changes the background and text in your default template. Dark or light theme is not selectable by developers. You can also select a theme that sets a pre-built layout and style for your {{site.dev_portal}}. - setting: Brand color description: This color is used to set the primary color in the default template. - setting: Portal logo @@ -113,7 +113,7 @@ rows: The API specification settings allow you to control how developers can interact with your API specs in your {{site.dev_portal}}. To configure API spec settings, navigate to your {{site.dev_portal}} in {{site.konnect_short_name}} and click **Portal Editor** in the sidebar. In the Portal Editor sidebar, click the code brackets icon. The following table describes the API spec settings you can configure: - + {% table %} columns: - title: Setting @@ -126,7 +126,7 @@ rows: - setting: Show Try it in Insomnia description: Enables users to open the API spec in [Insomnia](/insomnia/) to explore and send requests with the native client. - setting: Continuous scroll - description: Display the full spec on a single, scrollable page. If disabled, documentation, endpoints, and schemas appear on separate pages. + description: Display the full spec on a single page. If disabled, documentation, endpoints, and schemas appear on separate pages. - setting: Show schemas description: Control whether schemas are visible in your API specs. When enabled, schemas appear in the side navigation below the endpoints. - setting: Hide deprecated endpoints @@ -134,8 +134,9 @@ rows: - setting: Hide internal endpoints description: Manage visibility of internal endpoints and models. - setting: Allow custom server URL - description: Let users define a custom server URL for endpoints. This will be used to generate code snippets and to test the API. The URL is client_side only and is not saved. + description: Let users define a custom server URL for endpoints. This will be used to generate code snippets and to test the API. The URL is client-side only and is not saved. {% endtable %} + ## Custom forms @@ -214,7 +215,7 @@ rows: If you want to change the from and reply-to email domains, you can configure a different domain through {{site.dev_portal}} settings. Navigate to your {{site.dev_portal}}, click **Settings** in the sidebar and click the **Custom domains** tab. Click **New email domain** and configure the settings. -Once you've added your new domain, you must add the CNAME records to your DNS server. +After you've added your new domain, you must add the CNAME records to your DNS server. {:.info} > Certain domain names are restricted. See [Domain name restrictions](/dev-portal/custom-domains/#domain-name-restrictions) for more information.