dev-portal-customizations.yaml

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.
      - blocks:
          - type: image
            config:
              url: /assets/images/dev-portal/dev-portal-editor.png
              alt_text: "KongAir Dev Portal"
  - column_count: 4
    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
  
  - 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, and footer bottom 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.
      - 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: "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: "<code>&#123;&#123;api_documentation_url&#125;&#125;</code>"
                  description: The documentation URL for the API.
                - variable: "<code>&#123;&#123;api_name&#125;&#125;</code>"
                  description: The name of the API.
                - variable: "<code>&#123;&#123;api_version&#125;&#125;</code>"
                  description: The version of the API.
                - variable: "<code>&#123;&#123;application_name&#125;&#125;</code>"
                  description: The name of the developer's application.
                - variable: "<code>&#123;&#123;credential_name&#125;&#125;</code>"
                  description: The name of the key auth credential.
                - variable: "<code>&#123;&#123;credential_expires_at&#125;&#125;</code>"
                  description: "The date when the [key auth credential expires](/dev-portal/auth-strategies/#configure-the-key-auth-strategy)."
                - variable: "<code>&#123;&#123;dev_portal_reply_to&#125;&#125;</code>"
                  description: The {{site.dev_portal}} reply-to email address.
                - variable: "<code>&#123;&#123;developer_email&#125;&#125;</code>"
                  description: The email address of the developer.
                - variable: "<code>&#123;&#123;developer_fullname&#125;&#125;</code>"
                  description: The full name of the developer.
                - variable: "<code>&#123;&#123;developer_status&#125;&#125;</code>"
                  description: The {{site.dev_portal}} status of a developer. For example, \"approved\", \"pending\", or \"revoked\".
                - variable: "<code>&#123;&#123;portal_display_name&#125;&#125;</code>"
                  description: The display name of the {{site.dev_portal}}.
                - variable: "<code>&#123;&#123;portal_domain&#125;&#125;</code>"
                  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.
  - column_count: 3
    columns:
      - 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 %}