redocly / developer-portal-starter Goto Github PK

View Code? Open in Web Editor NEW

64.0 64.0 102.0 44.63 MB

Starter template for the Redocly developer portal

Home Page: https://redoc.ly

License: Other

TypeScript 50.48% MDX 49.52%

developer-portal-starter's People

Contributors

Stargazers

Watchers

Forkers

freight-trust jeroenvanhautte pauljwil swapnilogale antonkozachuk ourpandas pandahereboy pezi77 nikersch ninjasparda niharnaig katrpilar spacedsweden yonimoses vincentv89 fast-af cryptozifter eegii9006 alexvarchuk craigk0609 adamaltman zalesky budda0ne buddda0ne kayazas123 quipquopro avanpourm danchimento tjh3 yarokon romanhotsiy lchinglen chinhvan2311 alexa17198875 testrest3 ceriph nilminiwso2 gonzab27 scicero100 leetspeaker scheidt-bachmann-nl robertpitt trivedisorabh dvdlub mathieubottausci rocketlawyer isabella232 yliu134 jhnferraris gowtham-nagesh hackrnd bjonesy njaalberre davidmoltin thavamanirajasakthivel thnico abhigupta768 rafalonso paulocesarweb garvit-scio ca1eb-carr adandyguyinspace priley86 mohanraj-u jakubjenis fbrbovic maciejpitucha zenilevh aleccohan haikezegwaard kristoffertorstad pinkdiamond1 wesmena kunal361 varkumaradobe brightcoast adriancollinsshippo eirkje hyperinen druminik todd-elvers sdvassil aditya-docs kingjay66 tusharparekh qpc-github quantum-platinum-cloud sagetimnewton ikhsanuddin sergeiisayeu maya-opensource-software paremarcus hongphuc5497 jgannon-ups yacir dlr-pi taylorkrusen

developer-portal-starter's Issues

Diagram/Code Block Titles

Currently, if you put several mermaid diagrams under each other, each of them gets the "mermaid" as a title. Would it be possible to add an optional parameter to set the title for a block of code? In that case, it would be possible to neatly show multiple diagrams in the same place.

Feature Request: Allow CORS for search API

In order to better support integration with other documentation sites, it would be beneficial to be able to selectively allow CORS requests to the search API such as https://api.docs.cpanel.net/search-index.json?q=mysql&l=100.

We would accept being able to add it to our developer portal via code/configuration if possible, however if I am recalling correctly, this portion of the application is already bundled and not easily edited?

The lack of CORS support is blocking some important integrations for us currently. Any direction that you can provide would be appreciated.

Thanks

Feature Request - Allow ability for sidebar to auto create links to headers in Md file

It would be nice to have the ability to have the sidebar reference an anchor in a MD file or to auto generate links based on headings a in the file.

I tried to make a sidebar config to be:

pages:
- group: Quick start again
expanded: true
pages:
- label: Introduction
page: developer-portal/quickstart/index.md#Introduction

which would render something like:

Quick start
|_ Introduction (would navigate to the Introduction heading in the quickstart/index.md file).

UPDATE:

I did try the href feature and got it to work using a relative path to host:
For example

pages:
- group: Quick start again
expanded: true
pages:
- label: Introduction
href: "/developer-portal/quickstart/#Introduction" (renders the URL correctly and works)

It would still be a nice feature to have an option to auto generate it from the sidebar.

Is there a plan to add models/schemas?

We have several endpoints in our API that use polymorphism (oneOf/anyOf) that link out to a number of schemas that can be used for endpoints that require varying configuration parameters. I noticed that schemas are not displayed in the developer portal, which poses an issue for us because that information is vital for our customers to be able to effectively use the API.

Is there any plan to add this functionality, similar to what Stoplight and Swagger Editor offer? I noticed an open issue in one of your other repos asking for the same functionality, and was hoping it might be implemented here as well.

If not, would you mind walking me through how we can show/render the schemas on the developer portal so that our customers can readily view that information?

Mermaid breaks page

Hi, we recently tried upgrading our redocly version, resulting in errors in any page using mermaid:

error There was an error in your GraphQL query:

Something went wrong during remote rendering. Please, save this Ray ID: bf638205-979f-4ef7-bd90-314bd66d43ab and contact Redoc.ly team.

   1 | query MarkdownQuery($pageId: String!, $id: String!) {
   2 |   markdownRemark(fields: {contentId: {eq: $id}}) {
   3 |     html
>  4 |     headings {
     |     ^
   5 |       value
   6 |       depth
   7 |     }
   8 |   }
   9 |   contentItem(pageId: {eq: $pageId}) {
  10 |     fields {
  11 |       lastModified
  12 |     }
  13 |     data {
  14 |       enableToc

File path: PATH_HERE/@redocly/developer-portal/dist/engine/src/templates/simple-markdown.js
Url path: URL_PATH
Plugin: none

Strangely, I can get the mermaid example from the docs to work (cfr. below), but as soon as I change one thing about it, it breaks again immediately.

gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to mermaid
        section A section
        Completed task            :done,    des1, 2014-01-06,2014-01-08
        Active task               :active,  des2, 2014-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2               :         des4, after des3, 5d
        section Critical tasks
        Completed task in the critical line :crit, done, 2014-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to mermaid                      :1d

Could you help us figure out what's going wrong?

Unable to use UI components (OpenApiCodeSample) when using LandingLayout page template in .mdx file

I was building out a .mdx page and wanted to use the LandingLayout page template. When I use this template the OpenApiCodeSample will error with Incorrect definitionId:. If I remove using the template then it works just fine.

Can I use the LandingLayout or do I need to create another template instead?

.mdx file

---
title: Demo Customization
---

import { LandingLayout, OpenApiCodeSample } from '@redocly/developer-portal/ui';

<OpenApiCodeSample
definitionId="betterCloudApi"
operationId="get_v1_tokens_lookup"
defaultLanguage="Java"
/>
	
export default LandingLayout;

Whether I move the export default LandingLayout; to the top or bottom of the page I get the same error. I noticed in the index.mdx file that the import is at the top https://github.com/Redocly/developer-portal-starter/blame/main/index.mdx#L27

Turn on experimental decoraters for TS

Hi,
I am trying to include a Lit element (lit.dev) into mdx which uses decoraters, I successfully integrated it in a typescript project by turning experimentalDecoraters on in my tsconfig. But in this project, I don't see any tsconfig file. I was wondering if there is a way to turn that on in this project?
Basically in the end I want to tell babel-loader to turn decorators on.

Error: Something went wrong during remote rendering.

I hadn't been able to work with Redocly Dev Portal for a few weeks. When I got back to it and tried to run my local configurations, I saw errors when the site was loading. I finally cloned the developer-portal-starter repository fresh, followed by yarn install, yarn clean, and then yarn start. Bundling and linting are fine, but then I get these errors:

success Checking for changed pages - 0.001s
success source and transform nodes - 12.114s
success building schema - 0.902s

 ERROR #11321  PLUGIN

"gatsby-node.js" threw an error while running the createPages lifecycle:

Something went wrong during remote rendering. Please, save this Ray ID:
b3220e78-c4af-4425-ba7a-60863e87e1b0 and contact Redoc.ly team.



  Error: Something went wrong during remote rendering. Please, save this Ray ID:
   b3220e78-c4af-4425-ba7a-60863e87e1b0 and contact Redoc.ly team.

  - index.js:1 remoteRender
    [redocly-12-7-21]/[@redocly]/developer-portal/dist/engine/plugins/gatsby-red
    ocly-mermaid/index.js:1:696

  - task_queues.js:93 processTicksAndRejections
    internal/process/task_queues.js:93:5

  - index.js:1 module.exports
    [redocly-12-7-21]/[@redocly]/developer-portal/dist/engine/plugins/gatsby-red
    ocly-mermaid/index.js:1:1002

  - extend-node-type.js:209 parseString
    [redocly-12-7-21]/[gatsby-transformer-remark]/extend-node-type.js:209:11

  - extend-node-type.js:167 getAST
    [redocly-12-7-21]/[gatsby-transformer-remark]/extend-node-type.js:167:29

  - extend-node-type.js:264 getHeadings
    [redocly-12-7-21]/[gatsby-transformer-remark]/extend-node-type.js:264:19

  - extend-node-type.js:578 resolve
    [redocly-12-7-21]/[gatsby-transformer-remark]/extend-node-type.js:578:26

  - async Promise.all

  - async Promise.all

  - async Promise.all

  - async Promise.all

  - async Promise.all

  - async Promise.all

  - graphql-runner.ts:207 GraphQLRunner.query
    [redocly-12-7-21]/[gatsby]/src/query/graphql-runner.ts:207:14

  - api-runner-node.js:434 runAPI
    [redocly-12-7-21]/[gatsby]/src/utils/api-runner-node.js:434:16


info Total nodes: 205, SitePage nodes: 2 (use --verbose for breakdown)
failed createPages - 11.038s
success Checking for changed pages - 0.000s
success createPagesStatefully - 0.084s
success update schema - 0.046s
success write out redirect data - 0.001s
success Build manifest and related icons - 0.110s
success onPostBootstrap - 0.114s
info bootstrap finished - 33.347s
success onPreExtractQueries - 0.001s
success extract queries from components - 0.276s
success write out requires - 0.034s
success run static queries - 0.229s - 9/9 39.27/s
success run page queries - 0.028s - 2/2 70.83/s
⠀
You can now view portal-template in the browser.
⠀
  http://localhost:3000/
⠀
View GraphiQL, an in-browser IDE, to explore your site's data and schema
⠀
  http://localhost:3000/___graphql
⠀
Note that the development build is not optimized.
To create a production build, use gatsby build
⠀
success Building development bundle - 37.093s

Needless to say, the site isn't actually there even though the server is running. Do I need to update some dependency?

Windows 10
Node v14.16.0

Version switcher not working

When we created multiple versions of an API and followed the said documentation for configuring a .page.yaml file, we do indeed get a version switcher that shows up in the UI of the portal. However, selecting an option from the version switcher doesn't do anything, and manually changing the URL to the other version of the API shows the correct documentation, but the sidebar navigation remains collapsed.

Any suggestions? Happy to provide more feedback.

Sidebar training excercise has wrong example

On the Sidebar training exercises page, the following text states:

Open the upgrade page in a new tab.
Notice it renders without any sidebar.

Expected
When I open the upgrade page in a new tab the page renders without any sidebar

Actual
When I open the upgrade page in a new tab the page renders with a sidebar

Cause:
The sidebars.yaml already contains a reference to upgrade.md on line 68

Adding new API reference -Sidebar disappear

After adding new API reference, able to view in home page. After clicking on particular api, the side bar menu is not displayed. Only able to see the information about API and sidebar menu did not display.

Thanks
Ramkumar.C

Make all (HTML) headers themeable

Within Markdown the following headers are valid

# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading

which results in

h1 Heading

h2 Heading

h3 Heading

h4 Heading

h5 Heading

h6 Heading

However in the theme.ts only option heading1 till heading3 are valid. Please make all headings themeable.

Allow customisation of gatsby config files

Hi guys,

Fantastic job on the developer portal.

I've been playing around with this starter, and one thing I'd love to be able to do is add configuration to the gatsby config files (gatsby-ssr.js, gatsby-node.js, gatsby-config.js, gatsby-browser.js) you use under the hood. One way of achieving this could be to allow devs to optionally include their own custom-gatsby-ssr.js etc. files in the root directory of the redocly project. Not sure. Happy to provide more feedback on my use case etc.

Cheers!

Default logout functionality appends [object, object] to the end of the url causing 404 page on logout

When using the logout function from @redocly/ui it always appends [object%20Object]/ to the end of the url. This causes a 404 page to always show.

Following the documentation here. Customized the Nav and added the UserMenu based off of this example provided. https://github.com/Redocly/developer-portal-starter/pull/27/files#diff-956569b7abd1175639b59c147c5cf8e3760eec4b8bdc467bda8f2ebde51aca9d

On version 1.1.0-beta.92

six (6) attempts to get YAML (NOT JSON) APIs to display in redocly developer portal.

These APIs are YAML NOT JSON. These YAML API path and schema fragments were created by redocly's create-openapi-repo tool

As instructed by Redocly, these fragments are place in directories under the openapi directory:

developer-portal
      openapi
             schema
              paths
                   Abcdefg
                    Banana
                    Frog

Attempt 1

The .....page.yaml file in the openapi/ dir
path files, like v1@Abcdefg({key})@products({relatedKey})@$ref.yaml in the
openapi/path/Abcdefg/ directory

in sidebar.yaml

  - group: MOA APIs
    expanded: true
    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "moa_Abcdefg.page.yaml/*"

Error

No "Error" messages, but didn't work

Attempt 2: The same, but with each of

	- page: "openapi/moa_Abcdefg.page.yaml"
	- page: "openapi/moa_Abcdefg.page.yaml/*"
	- page: "openapi/moa_Abcdefg.page.yaml/"
	- page: openapi/moa_Abcdefg.page.yaml
	- page: openapi/moa_Abcdefg.page.yaml/
	- page: openapi/moa_Abcdefg.page.yaml/*

Of course, none of these worked.

Note that the last of these, which DEFINITELY does not exist, does not give an error.
Those that DO exist, DO give errors

Errors about "File not found" only appear for files that EXIST.
When a file does NOT exist, no error.

Attempt 3

Directly listed each API file.

    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "openapi/paths/Abcdefg/moa_Abcdefg.page.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@SubCategories@$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key})@SubCategories({relatedKey}) @$ref.yaml"
          - page: "openapi/paths/Abcdefg/v1@Abcdefg({key}).yaml"
          - page: "openapi/paths/Abcdefg/[email protected]"

errors

Lots of (incorrect) errors about "could not find page"

Page "openapi/paths/Abcdefg/moa_Abcdefg.page.yaml" is not found. Verify path in "sidebars.yaml"

 ERROR
Could not find page: openapi/paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml.

 ERROR
Could not find page: openapi/paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml.

Attempt 4

Based on the openapi directory. Not suprised that this didn't work - after all, nothing worked - but for completeness

  - group: MOA APIs
    expanded: true
    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "paths/Abcdefg/moa_Abcdefg.page.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@SubCategories@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key})@SubCategories({relatedKey})@$ref.yaml"
          - page: "paths/Abcdefg/v1@Abcdefg({key}).yaml"
          - page: "paths/Abcdefg/[email protected]"

error


 ERROR
Page "paths/Abcdefg/moa_Abcdefg.page.yaml" is not found. Verify path in "sidebars.yaml"

 ERROR
Could not find page: paths/Abcdefg/v1@Abcdefg({key})@Products@$ref.yaml.

 ERROR
Could not find page: paths/Abcdefg/v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml.

 ERROR
Could not find page: paths/Abcdefg/v1@Abcdefg({key})@SubCategories@$ref.yaml.

Attempt 5

Put the .....page.yaml file in the same directory as the 'path' files that describe the API. This is like the APIs represented in monolithic JSON (in the openapi dir) being in the same dir as the API path file.

  - group: MOA APIs
    expanded: true
    pages:
      - group: Abcdefg
        expanded: true
        pages:
          - page: "openapi/paths/Abcdefg/moa_Abcdefg.page.yaml/*"

error: No error, but no APIs displayed

Attempt 6

Put the path files in the opeanapi directory, like the JSON api file (that actually works).

      - group: Abcdefg
        expanded: true
        pages:
          - page: "moa_Abcdefg.page.yaml/*"
          - page: "v1@Abcdefg({key})@Products@$ref.yaml"
          - page: "v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml"
          - page: "v1@Abcdefg({key})@SubCategories@$ref.yaml"
          - page: "v1@Abcdefg({key})@SubCategories({relatedKey})@$ref.yaml"
          - page: "v1@Abcdefg({key}).yaml"
          - page: "[email protected]"

Errors

Incorrect error messages saying "Could not find page".

 ERROR
Could not find page: v1@Abcdefg({key})@Products@$ref.yaml.

 ERROR
Could not find page: v1@Abcdefg({key})@Products({relatedKey})@$ref.yaml.

 ERROR
Could not find page: v1@Abcdefg({key})@SubCategories@$ref.yaml.

Running Redocly locally on Mac M1

Hi,

I get get the following errors when running yarn start on my Macbook Air with M1 processor:

Error: Something went wrong installing the "sharp" module
  dlopen(/Users/***/src/external-documentation/node_modules/@redocly/gat  sby-plugin-sharp/node_modules/sharp/build/Release/sharp.node, 1): Symbol not f  ound: __ZTVN4vips7VOptionE
    Referenced from: /Users/fredrikryde/src/external-documentation/node_modules/  @redocly/gatsby-plugin-sharp/node_modules/sharp/build/Release/sharp.node
    Expected in: flat namespace
   in /Users/fredrikryde/src/external-documentation/node_modules/@redocly/gatsby  -plugin-sharp/node_modules/sharp/build/Release/sharp.node
  - Remove the "node_modules/sharp" directory then run
    "npm install --ignore-scripts=false --verbose" and look for errors
  - Consult the installation documentation at https://sharp.pixelplumbing.com/in  stall
  - Search for this error at https://github.com/lovell/sharp/issues

I followed the steps above but with no success. My guess is it has something to do with my new M1 Mac

Running Node 14.15.4

Any help would be much appreciated .

Try it console styling bug in Firefox on small screens

On small screens in firefox (on Windows), the try it console looks like this:

This can be resolved by changing the CSS style of one of the divs around it (from flex 1 1 0% to flex 1 1 auto):

Could this be integrated into the next release?

Update to beta.84

Upgrade MermaidJS to 8.6.0 & allow for directives

Sequence diagrams in mermaid 8.6 (https://mermaid-js.github.io/mermaid/#/8.6.0_docs) support auto wrapping & newlines, neither of which are currently supported inside the developer portal. Would it be possible to upgrade this system, as to allow for more flexibility per diagram?

Selecting API method cuts off page header

Selecting a given method from the API menu will open that method's page content but cut off the header (the page will be scrolled down slightly).
Re-clicking the menu item will load the page correctly.
I've tested this with version "1.1.0-beta.80".

2022-02-10.18-10-09.mp4

Table Of Contents .mdx files

When using a .md file and having either Table Of Contents enabled in siteConfig.yaml or via Front Matter, I see a nice Table Of Contents autogenerated from all headers of the page. :)

When renaming the same file to a .mdx file, so I can use components, then suddenly the Table Of Contents dissappears.

As a user it looks like this is a bug. As a developer it might be a feature ;)

Allow for the use of local CSS stylesheets

Currently, a local path included as a style sheet in the stylesheets part of siteConfig.yaml results in an error, making it hard to include custom CSS through this option without workarounds. Another option would be to allow for full css customisation options through theme.ts, instead of only the options selected beforehand.

Thanks!

(Mobile UX) When clicking/tapping a link under and expandable section, you are instead directed to the top-level link of that section

This requires having bundled specs via global tags, resulting in expandable menus in the left-hand navigation for rendered documentation.

This was observed on a site generated via the Redoc developer portal, version 1.0.0-beta.150.

Using a mobile browser (or view) for rendered API documentation, click the 'hamburger' icon in the lower right-hand corner of the screen (you may have to scroll down slightly for this to appear).
In the menu that appears, expand a section (the arrow next to one of the links under a bolded text line).
Click/Tap a link under the expanded section (such as one of the 'Example link' entries in the below screenshot).
Observe that instead of taking you to the specified page, you are instead redirected to the landing page for the bolded subject line. (Referring to the above screenshot, this would be the 'Example Section' link.)

Mermaid Arrowheads Disappear When Using Multiple Diagrams

Hi, thanks for adding the diagram title feature! I've tried it, but it seems arrowheads disappear from sequence diagrams on the second page - here's a code sample (same diagram code twice in a row - I've added spaces to prevent github from interpreting it as code in this issue description):

` ``mermaid X
sequenceDiagram
    participant A
    participant B
    A->>B: message
` ``
` ``mermaid Y
sequenceDiagram
    participant A
    participant B
    A->>B: message
` ``

Is there any way to prevent this?

issue in hosting with domain

We received trial enterprise license key for developer portal. After putting the license key in siteConfig.yaml and changing package.json - "scripts": {
"start": "redocly-portal build -p 3000",
"build": "redocly-portal build",
"clean": "redocly-portal clean"
getting below error.

`There was an error in your GraphQL query:

request to https://api.redoc.ly/mermaid failed, reason: connect ECONNREFUSED 35.171.214.154:443

1 | query MarkdownQuery($pageId: String!, $id: String!) {
2 | markdownRemark(fields: {contentId: {eq: $id}}) {

3 | html
| ^
4 | headings {
5 | value
6 | depth
7 | }
8 | }
9 | contentItem(pageId: {eq: $pageId}) {
10 | fields {
11 | lastModified
12 | }
13 | data {

File path: D:/redoc_workarea/developer-portal-starter-master/node_modules/@redocly/developer-portal/dist/engine/src/templates/simple-markdown.js
Url path: /developer-portal/mermaid/
Plugin: none

success run page queries - 2.761s - 57/57 20.65/s`

Please let me know how to configure to host with domain name.

Thanks
Ram

Disable ToC if there is only one subheader

Currently, if there is only one subheader on a page, the table of contents is still shown on the right (if it is enabled globally) - however, in this situation there is no added value (and it is confusing to users). Would it be possible to allow this to be disabled per page or in the case where only a single subheader is present on the page?

Display of center column content overlaps with specific specifications and browsers

We've ben investigating an apparent CSS issue concerning the overlap of the table in the center column. This has been most noted using Firefox with specifications that have long parameter names. We have tried a few CSS modifications to get a fix in place but ultimately found nothing that did not create new issues.

You can see the issue clearly in Firefox at https://api.docs.cpanel.net/openapi/whm/operation/createacct/. You may need to resize the screen down and note that at a certain point the center content overlaps the right sidebar. I am also attaching a screenshot and an example spec that reproduces the issue.

  schemas: {}
  securitySchemes:
    BasicAuth:
      scheme: basic
      type: http
externalDocs:
  url: 'https://cpanel.net/developers/'
info:
  contact:
    email: [email protected]
    name: cPanel L.L.C.
    url: 'https://cpanel.net/support/'
  description: WHM API.
  license:
    name: cPanel License
    url: 'https://cpanel.net/legal-notices/'
  termsOfService: 'https://cpanel.net/legal-notices/'
  title: WHM API
  version: 11.93.9999.13
openapi: 3.0.2
paths:
  /createacct:
    get:
      summary: createacct
      description: |-
        This function creates a cPanel account and sets up its domain information.

        **Note:**

        * On servers that run CentOS 7, you may see a `named` warning about the absence of SPF resource records on DNS.
        * This warning is **not** relevant on CentOS 7 servers, because [RFC 7208 deprecated SPF records](https://tools.ietf.org/html/rfc7208). CentOS 7 servers use TXT records instead of SPF records.
        * Red Hat 7.1 and CentOS 7.1 both contain `bind-9.9.4-23.el7`, which is an updated version of BIND that complies with RFC 7208. To resolve this issue, update your operating system to a version that contains the updated version of BIND. For more information, read the [Red Hat Bugzilla case about SPF record errors](https://bugzilla.redhat.com/show_bug.cgi?id=1215164).
      operationId: createacct
      parameters:
        - description: |-
            The new account's username. cPanel usernames **must** adhere to the following criteria:
            * The first eight characters of a username **must** be unique.
            * A username **cannot** begin with a number or the test string.

            **Note:**

            * Use the `Cpanel::Validate::Username` Perl module to validate usernames before you call this function. For more information, read the `/usr/local/cpanel/Cpanel/Validate/Username.pod` file.
            * The system will automatically convert this value to all lowercase letters.
            * MySQL's unique character limitations do **not** exist on servers that use MariaDB.
          in: query
          name: username
          required: true
          schema:
            example: username
            maxLength: 16
            type: string
        - description: The account's main domain.
          in: query
          name: domain
          required: true
          schema:
            example: example.com
            type: string
        - description: |-
            The account's maximum bandwidth.
            * `0`, `unlimited`, or `null` ? The account possesses unlimited bandwidth.
          in: query
          name: bwlimit
          required: false
          schema:
            example: unlimited
            format: megabytes
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - minimum: 0
                type: integer
        - description: |-
            Whether the account has [Common Gateway Interface (CGI)](https://en.wikipedia.org/wiki/Common_Gateway_Interface) access enabled.
            * `1` ? Enabled.
            * `0` ? Disabled.

            **Note:**

             When a [server profile](https://docs.cpanel.net/whm/server-configuration/server-profile/) disables the [Web Server](https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-use-server-profiles/86/) role, this parameter defaults to `0`. On these servers, you **cannot** enable CGI access.
          in: query
          name: cgi
          required: false
          schema:
            default: 1
            enum:
              - 1
              - 0
            example: 1
            type: integer
        - description: The account's contact email address.
          in: query
          name: contactemail
          required: false
          schema:
            default: ''
            example: [email protected]
            format: email
            type: string
        - description: |-
            The account's cPanel theme.

            **Note:**

            This parameter defaults to the server's [default cPanel theme](https://docs.cpanel.net/whm/server-configuration/basic-webhost-manager-setup/).
          in: query
          name: cpmod
          required: false
          schema:
            example: paper_lantern
            type: string
        - description: |-
            The account's IP address.

            **Note:**

            If you do not specify this parameter, the system will determine the account's IP address.
          in: query
          name: customip
          required: false
          schema:
            example: 192.0.2.0
            format: ipv4
            type: string
        - description: |-
            Whether [DomainKeys Identified Mail (DKIM)](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) is enabled for the account.
            * `1` ? Enabled.
            * `0` ? Disabled.

            **Note:**

            This parameter defaults to the *Enable DKIM on domains for newly created accounts* setting's value in WHM's *[Tweak Settings](https://docs.cpanel.net/whm/server-configuration/tweak-settings/) interface (WHM >> Home >> System Configuration >> Tweak Settings)*.
          in: query
          name: dkim
          required: false
          schema:
            enum:
              - 0
              - 1
            example: 1
            type: integer
        - description: The account's assigned feature list.
          in: query
          name: featurelist
          required: false
          schema:
            default: default
            example: feature_list
            type: string
        - description: |-
            Whether to overwrite an existing DNS zone with the new account's information. The system performs this action if a matching DNS zone currently exists.
            * `1` ? Overwrite.
            * `0` ? Do **not** overwrite.
          in: query
          name: forcedns
          required: false
          schema:
            default: 0
            enum:
              - 0
              - 1
            example: 0
            type: integer
        - deprecated: true
          description: |-
            Whether the account has Microsoft® FrontPage Extensions enabled.

            **Note:**

             cPanel & WHM ignores all FrontPage settings and parameters.
          in: query
          name: frontpage
          required: false
          schema:
            default: ~
            nullable: true
            type: integer
        - description: |-
            The account's group ID.

            **Note:**

            * To use this parameter, the function's caller **must** authenticate as the root user.
            * If you do **not** specify this parameter, the system generates a group ID.
            * This **must** be a unique value that is **not** currently associated with disk usage and does **not** exist on the server.
          in: query
          name: gid
          required: false
          schema:
            example: 123456789
            minimum: 1
            type: integer
        - description: |-
            Whether the account has shell (SSH) access enabled.
            * `1` ? Enabled.
            * `0` ? Disabled.
          in: query
          name: hasshell
          required: false
          schema:
            default: 0
            enum:
              - 0
              - 1
            example: 0
            type: integer
        - description: |-
            A legacy parameter.
            * `1` ? Enabled.
            * `0` ? Disabled.

            **Important:**

             Only include this parameter if you set a useregns value of 1.
          in: query
          name: hasuseregns
          required: false
          schema:
            default: 0
            enum:
              - 0
              - 1
            example: 1
            type: integer
        - description: |-
            The absolute path to the account's `home` directory.

            **Note:**

            * To use this parameter, the function's caller **must** authenticate as the `root` user.
            * If you do not specify a value, the system uses the `/home/user` directory, where `user` is the account's username.
          in: query
          name: homedir
          required: false
          schema:
            example: /home/user
            type: string
        - description: |-
            Whether the account has a dedicated IP address.
            * `y` ? The account possesses a dedicated IP address.
            * `n` ? The account does **not** possess a dedicated IP address.
          in: query
          name: ip
          required: false
          schema:
            default: n
            enum:
              - y
              - n
            example: n
            type: string
        - description: |-
            The account's default locale.

            **Note:**

            * This value is case-sensitive.
            * For region-specific locales, use the ISO 639-1 code, an underscore (`_`), and the [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) code.
          in: query
          name: language
          required: false
          schema:
            example: en
            type: string
        - description: |-
            The name of the account owner.
            * `root`
            *  A valid reseller account username on the server.
          in: query
          name: owner
          required: false
          schema:
            example: root
            type: string
        - description: |-
            A [linked cPanel mail server](https://docs.cpanel.net/whm/server-configuration/link-server-nodes/) on which to also create the account. This is the server's alias (friendly name) defined when creating the link to a cPanel mail server.

            **Warning:**

             This parameter is **experimental**. Do **not** use this on a production server.

            **Note:**

             This function **requires** a linked cPanel mail server.
          in: query
          name: mail_node_alias
          required: false
          schema:
            example: mailnode
            type: string
        - description: |-
            A mailbox format to use, if you do not wish to use the system's default mailbox format.

            **Note:**

            * Use this parameter when you transfer between servers with different mailbox formats.
            * This parameter defaults to the *The mailbox storage format for new accounts setting* in the *Mail* section of WHM's [*Tweak Settings*](https://docs.cpanel.net/whm/server-configuration/tweak-settings/#mail) interface (*WHM >> Home >> Server Configuration >> Tweak Settings*).
          in: query
          name: mailbox_format
          required: false
          schema:
            enum:
              - mdbox
              - maildir
            example: mdbox
            type: string
        - description: |-
            The percentage of failed or deferred email messages that the account can send per hour. If the account exceeds this value its outgoing mail is rate-limited.
            * `0` or `unlimited` ? The account can send an unlimited number of failed or deferred messages.
          in: query
          name: max_defer_fail_percentage
          required: false
          schema:
            default: unlimited
            example: unlimited
            oneOf:
              - enum:
                  - unlimited
                type: string
              - minimum: 0
                type: integer
        - description: |-
            The maximum number of emails that the account can send in one hour.
            * `0` or `unlimited` ? The account can send an unlimited number of emails.
          in: query
          name: max_email_per_hour
          required: false
          schema:
            example: unlimited
            oneOf:
              - enum:
                  - unlimited
                type: string
              - minimum: 0
                type: integer
        - description: |-
            The maximum size that the account can define when it creates an email account.
            * `0` or `unlimited` ? The account possesses an unlimited quota.

            **Important:**

             * This value applies to each email account, **not** each cPanel account.
             * If you define this parameter it overwrites the hosting plan's defined value for the account.
             * We recommend that you allow the account's plan to determine this value.
          in: query
          name: max_emailacct_quota
          schema:
            default: 1024
            example: 1024
            format: megabytes
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 4294967296
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of addon domains.
            * `unlimited`, or `null` ? The account possesses unlimited addon domains.
          in: query
          name: maxaddon
          required: false
          schema:
            default: 0
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of FTP accounts.
            * `0`, `unlimited`, or `null` ? The account possesses unlimited FTP accounts.
          in: query
          name: maxftp
          required: false
          schema:
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of mailing lists.
            * `0`, `unlimited`, or `null` ? The account possesses unlimited mailing lists.
          in: query
          name: maxlst
          required: false
          schema:
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of parked domains (aliases).
            * `unlimited` or `null` ? The account possesses unlimited parked domains.
          in: query
          name: maxpark
          required: false
          schema:
            default: 0
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of email accounts.
            * `0`, `unlimited`, or `null` ? The account possesses unlimited email accounts.
          in: query
          name: maxpop
          required: false
          schema:
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of each available type of SQL database.
            For example, this parameter has a `5` value and the system administrator allows
            MySQL® and PostgreSQL® databases. Users can create up to five MySQL databases
            and up to five PostgreSQL databases.
            * `0`, `unlimited`, or `null` ? The account possesses unlimited databases.
          in: query
          name: maxsql
          required: false
          schema:
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's maximum number of subdomains.
            `unlimited` or `null` ? The account possesses unlimited subdomains.
          in: query
          name: maxsub
          required: false
          schema:
            example: unlimited
            nullable: true
            oneOf:
              - enum:
                  - unlimited
                type: string
              - maximum: 999999
                minimum: 0
                type: integer
        - description: |-
            The account's main mail exchanger's type.
            * `local` - Local Mail Exchanger.
            * `secondary` - Backup Mail Exchanger.
            * `remote` - Remote Mail Exchanger.
            * `auto` - Automatically Detect Configuration.

            **Note:**

             The function does **not** configure the primary MX entry to point to the appropriate exchanger. You must [perform this function separately](https://docs.cpanel.net/whm/dns-functions/edit-mx-entry/).
          in: query
          name: mxcheck
          required: false
          schema:
            default: local
            enum:
              - local
              - secondary
              - remote
              - auto
            example: auto
            type: string
        - description: |-
            The account's password.

            **Note:**

             * You can use either the `pass` or the `password` parameter, but **not** both.
             * If you don't specify this value, the system generates a secure password.
          in: query
          name: pass
          required: false
          schema:
            example: 123456luggage
            type: string
        - description: |-
            The account's password.

            **Note:**

             * You can use **either** the `pass` or the `password` parameter, but **not** both.
             * If you don't specify this value, the system generates a secure password.
          in: query
          name: password
          required: false
          schema:
            example: 123456luggage
            type: string
        - description: |-
            A new plan name. Use this parameter to save unique account settings as a new plan.

            **Note:**

             * If you do **not** use this parameter but specify `1` for the `savepkg` value, the system will generate a plan name.
             * If you do **not** use this parameter and specify `0` or do not use the `savepkg` parameter, the function does not save a new plan.
             * If you do **not** use this parameter, the function will not save the new account settings.
          in: query
          name: pkgname
          required: false
          schema:
            example: my_new_package
            type: string
        - description: |-
            The account's hosting plan (package).

            **Important:**

             If you provide this value, **do not** use the optional quota-related parameters below. Instead, we recommend that you allow the account's plan to determine these values.
          in: query
          name: plan
          required: false
          schema:
            default: default
            example: default
            type: string
        - description: |-
            The account's disk space quota.
            * `0` ? The account's disk space is unlimited.
          in: query
          name: quota
          required: false
          schema:
            default: 0
            example: 500
            format: megabytes
            maximum: 999999
            minimum: 0
            type: integer
        - description: |-
            Whether to grant reseller privileges to the account.
            * `1` ? Grant reseller privileges.
            * `0` ? Do **not** grant reseller privileges.
          in: query
          name: reseller
          required: false
          schema:
            default: 0
            enum:
              - 0
              - 1
            example: 0
            type: integer
        - description: |-
            Whether to save the account's settings as a new plan.
            * `1` ? Save.
            * `0` ? Do **not** save.
          in: query
          name: savepkg
          required: false
          schema:
            default: 0
            enum:
              - 0
              - 1
            example: 1
            type: integer
        - description: |-
            Whether the account has Apache SpamAssassin? enabled.
            * `1` ? Enabled.
            * `0` ? Disabled.
          in: query
          name: spamassassin
          required: false
          schema:
            default: 1
            enum:
              - 0
              - 1
            example: 1
            type: integer
        - description: |-
            Whether [Sender Policy Framework (SPF)](https://en.wikipedia.org/wiki/Sender_Policy_Framework) is enabled for the account.
            * `1` ? Enabled.
            * `0` ? Disabled.

            This parameter defaults to the *Enable SPF on domains for newly created accounts*
            setting's value in WHM's [*Tweak Settings*](https://docs.cpanel.net/whm/server-configuration/tweak-settings/) interface (*WHM >> Home >> System Configuration >> Tweak Settings*).
          in: query
          name: spf
          required: false
          schema:
            enum:
              - 0
              - 1
            example: 1
            type: integer
        - description: |-
            Whether to enable spam box filtering for the account.
            * `y` - Enable spam box filtering.
            * `n` - Disable spam box filtering.
            **Note:**

             You **must** enable Apache SpamAssassin? to use the Spam Box feature.
          in: query
          name: spambox
          required: false
          schema:
            default: y
            enum:
              - y
              - n
            example: y
            type: string
        - description: |-
            The account's user ID.

            **Note:**

             * To use this parameter, the function's caller **must** authenticate as the `root` user.
             * If you do not specify this parameter, the system generates a user ID.
             * This **must** be a unique value that is **not** currently associated with disk usage and does **not** exist on the server.
          in: query
          name: uid
          required: false
          schema:
            example: 123456789
            minimum: 0
            type: integer
        - description: |-
            Whether to use registered nameservers for the domain.
            * `1` - Use registered nameservers.
            * `0` - Use the server's default nameservers.

            **Important:**

             If you set this parameter to `1`, you must also include the `hasuseregns` parameter with a value of `1`.
          in: query
          name: useregns
          required: false
          schema:
            default: 0
            enum:
              - 0
              - 1
            example: 0
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      ip:
                        description: The account's primary nameserver's IP address.
                        example: 192.0.2.0
                        format: ipv4
                        type: string
                      nameserver:
                        description: The account's primary nameserver.
                        example: ns1.example.com
                        type: string
                      nameserver2:
                        description: The account's secondary nameserver.
                        example: ns2.example.com
                        type: string
                      nameserver3:
                        description: The account's tertiary nameserver.
                        example: ns3.example.com
                        type: string
                      nameserver4:
                        description: The account's quaternary nameserver.
                        example: ns4.example.com
                        type: string
                      nameservera:
                        description: The account's primary nameservers' IP address.
                        example: 192.0.2.1
                        format: ipv4
                        nullable: true
                        type: string
                      nameservera2:
                        description: The account's secondary nameservers' IP address.
                        example: 192.0.2.2
                        format: ipv4
                        nullable: true
                        type: string
                      nameservera3:
                        description: The account's tertiary nameservers' IP address.
                        example: 192.0.2.3
                        format: ipv4
                        nullable: true
                        type: string
                      nameservera4:
                        description: The account's quaternary nameservers' IP address.
                        example: 192.0.2.4
                        format: ipv4
                        nullable: true
                        type: string
                      nameserverentry:
                        description: The primary nameserver's DNS name.
                        example: dnsentry1
                        nullable: true
                        type: string
                      nameserverentry2:
                        description: The secondary nameserver's DNS name.
                        example: dnsentry2
                        nullable: true
                        type: string
                      nameserverentry3:
                        description: The tertiary nameserver's DNS name.
                        example: dnsentry3
                        nullable: true
                        type: string
                      nameserverentry4:
                        description: The quaternary nameserver's DNS name.
                        example: dnsentry4
                        nullable: true
                        type: string
                      package:
                        description: The account's plan (package) name.
                        example: my_new_package
                        type: string
                    type: object
                  metadata:
                    properties:
                      command:
                        description: The method name called.
                        example: createacct
                        type: string
                      output:
                        description: An object that contains the function's raw output
                          information.
                        properties:
                          raw:
                            description: The raw output from the account creation
                              operation. This return may contain HTML code.
                            example: 'Checking input data...Forced Dns is enabled.\nValidating
                                Username......Done\nValidating IP......Done\nValidating
                                Contact Email......Done\n...Done\nValidating system
                                setup......Done\nChecking for database conflicts......Done\nWWWAcct
                                12.6.0 (c) 2020 cPanel, L.L.C...\n\n+===================================+\n|
                                New Account Info |\n+===================================+\n|
                                Domain: example.com\n| Ip: 192.0.2.0 (n)\n| HasCgi:
                                y\n| UserName: username\n| PassWord: 123456luggage\n|
                                CpanelMod: paper_lantern\n| HomeRoot: /home\n| Quota:
                                1 GB\n| NameServer1: ns1.example.com\n| NameServer2:
                                ns2.example.com\n| NameServer3:\n| NameServer4:\n| Contact
                                Email: [email protected]\n| Package: my_new_package\n|
                                Feature List: feature_list\n| Language: en\n+===================================+\n...Done\nCustom
                                Account Data Provided: no\nRunning pre creation script
                                (/usr/local/cpanel/scripts/prewwwacct)......Done\nAdding
                                User...Removing Shell Access (n)\nSuccess...Done\nAdding
                                Entries to userdata......Done\nSetting up Mail & Local
                                Domains...localdomains...valiases ...vdomainaliases
                                ...vfilters ......Done\nConfiguring DNS...Zone example.com
                                has been successfully added\n...Done\nVerifying MX Records
                                and Setting up Databases...Reconfiguring Mail Routing:\nLOCAL
                                MAIL EXCHANGER: This server will serve as a primary
                                mail exchanger for example.com''s mail.:\n This configuration
                                has been automatically detected based on your mx entries.\n\n...Done\nSetting
                                up Service Subdomains......Done\nUpdating Authentication
                                Databases......Done\nSetting passwords......Done\nUpdating
                                the userdata cache......Done\nSetting up Horde database
                                in the background.......Done\nCreating bandwidth datastore......Done\nUpdating
                                the dedicated IP address usage cache......Done\nGenerating
                                and installing DKIM keys......Done\nEnabling Apache
                                SpamAssassin......Done\nEnabling Apache SpamAssassin
                                Spam Box......Done\nSending Account Information......Done\nRunning
                                post creation scripts (/usr/local/cpanel/scripts/legacypostwwwacct,
                                /usr/local/cpanel/scripts/postwwwacct, /usr/local/cpanel/scripts/postwwwacctuser)......Done\nwwwacct
                                creation finished\nAccount Creation Complete!!!...Account
                                Creation Ok...Done\n'
                            type: string
                        type: object
                      reason:
                        description: The reason the API function failed when the `metadata.result`
                          field is `0`. This field may display a success message when
                          a function succeeds.
                        example: Account Creation Ok
                        type: string
                      result:
                        description: |-
                          * `1` - Success.
                          * `0` - Failed. Check the `reason` field for more details.
                        enum:
                          - 0
                          - 1
                        example: 1
                        type: integer
                      version:
                        description: The version of the API function.
                        example: 1
                        type: integer
                type: object
          description: HTTP Request was successful.
      tags:
        - Accounts
      x-code-samples:
        - label: CLI
          lang: Shell
          source: whmapi1 createacct username='username' domain='example.com'
        - label: URL
          lang: HTTP
          source: https://hostname.example.com:2087/cpsess##########/json-api/createacct?api.version=1&username=username&domain=example.com
      x-cpanel-api-version: WHM API 1
      x-cpanel-available-version: '11.32'
security:
  - BasicAuth: []
servers:
  - description: A server running WHM.
    url: 'https://fictitious.com/json-api'
    variables:
      host:
        default: whm-server.tld
        description: The hostname of a server running WHM.
      port:
        default: '2087'
        description: The WHM port.
tags:
  - description: The Account Restoration module for WHM API 1.
    name: Account Restoration
  - description: The Accounts module for WHM API 1.
    name: Accounts
  - description: The Addon Domains module for WHM API 1.
    name: Addon Domains
  - description: The Authentication module for WHM API 1.
    name: Authentication
  - description: The Backups module for WHM API 1.
    name: Backups
  - description: The cPanel Analytics module for WHM API 1.
    name: cPanel Analytics
  - description: The cPHulk module for WHM API 1.
    name: cPHulk
  - description: The Databases module for WHM API 1.
    name: Databases
  - description: The DNS module for WHM API 1.
    name: DNS
  - description: The EasyApache module for WHM API 1.
    name: EasyApache
  - description: The Greylisting module for WHM API 1.
    name: Greylisting
  - description: The Integration module for WHM API 1.
    name: Integration
  - description: The IP Addresses module for WHM API 1.
    name: IP Addresses
  - description: The Mail module for WHM API 1.
    name: Mail
  - description: The Market module for WHM API 1.
    name: Market
  - description: The ModSecurity module for WHM API 1.
    name: ModSecurity
  - description: The Packages module for WHM API 1.
    name: Packages
  - description: The PHP module for WHM API 1.
    name: PHP
  - description: The Resellers module for WHM API 1.
    name: Resellers
  - description: The RPM module for WHM API 1.
    name: RPM
  - description: The Script Hooks module for WHM API 1.
    name: Script Hooks
  - description: The Security module for WHM API 1.
    name: Security
  - description: The Server Administration module for WHM API 1.
    name: Server Administration
  - description: The SSL module for WHM API 1.
    name: SSL
  - description: The Styles and Themes module for WHM API 1.
    name: Styles and Themes
  - description: The Support Tickets module for WHM API 1.
    name: Support Tickets
  - description: The Transfers module for WHM API 1.
    name: Transfers
  - description: The Updates module for WHM API 1.
    name: Updates

Allow for alias domains

We would like to have several domain extensions point to our developer portal - is there a feature in the pipeline that would allow this on your end (through DNS settings)?

Thanks!

Allow custom UI components to be registered via dependency injection

Hi guys,

I really like the work you've put into the theming aspect of the developer portal; I've been able to customise the look/feel of my POC portal 80% of the way there.

That being said, there are still some components which feel quite different to the rest of the brand I'm working with, and to work around this issue, I was wondering whether it would be possible to expose the ability for devs to register their own implementations (using the same props) of certain components you've written, e.g. NavBar/NavItem etc.

Again, happy to run through my use case and assist if need be!

Cheers!

Security issues in packages

There are many security issues in the dependencies of @redocly/[email protected] that I can't seem to fix using Yarn or NPM due to those tools being unable to resolve the dependency tree. Yarn reports 52 overall vulnerabilities, with 15 being deemed high risk. NPM reports 86 vulnerabilities (61 moderate, 25 high).

Any chance we can get the dependencies brought up to date to help resolve these issues? Thanks in advance.
eresolve-report692021.txt

Feature Request - Allow ability to set section to 100% width

I would like the ability to set the section to have 100% width for mdx files. This allows me to have better styling control over the page. At the moment, the width on the section has large white spaces. This also means I can have a bottom border on a box that spans the full width of the section that makes it look like a horizontal rule.

Where are the docs describing adding files to (OpenAPI) tag-based heirarchies?

My API has tags.

Redocly generates hierarchies based on tags, rather than based on other criteria (path similarities, orders in some directory or other, order in an openapi.yaml file).

The company I work for has paid (yes, already) for redocly to add contextural info to OpenAPI API descriptions.

Where are the docs describing adding files (e.g. markdown files) into (OpenAPI) tag-based heirarchies?

How to access nested nav items?

Looking through the compiled code (such as@redocly/developer-portal/dist/engine/src/fragments.jsand @redocly/developer-portal/dist/engine/auto-graphql.d.ts) your system supports nested items in the header navigation. Example from fragments.js:

  fragment HeaderNavItemFragment on NavItem {
    type
    label
    link
    icon
    target
    external
    activateWithSidebar
  }

  fragment HeaderNavFragment on Query {
    siteConfig {
      logo {
        altText
        image
        href
      }
      nav {
        ...HeaderNavItemFragment
        items {
          ...HeaderNavItemFragment
          items {
            ...HeaderNavItemFragment
          }
        }
      }
    }
  }

I have the following structure in siteConfig.yaml:

nav:
  - search: true
  - group: Guides
    items:
      - label: Get started
        page: guides/get-started/index.md
      - label: Onboarding
        page: guides/onboarding/index.md
      - label: Feature guides
        page: guides/index.md
  - label: API reference
    # icon: ./images/redocly-icon-white.png
    page: api-reference/index.md
  - label: Training exercises
    page: developer-portal/index.md

However, when I run a query in graphiql, I get the following:

query MyQuery {
  siteConfig {
    nav {
      label
      link
      type
      target
      items {
        label
        link
        type
        target
        items {
          label
          link
          type
          target
        }
      }
    }
  }
}

Result:

{
  "data": {
    "siteConfig": {
      "nav": [
        {
          "label": "",
          "link": null,
          "type": "search",
          "target": null,
          "items": []
        },
        {
          "label": "Guides",
          "link": null,
          "type": "group",
          "target": null,
          "items": []
        },
        {
          "label": "API reference",
          "link": "/api-reference/",
          "type": "page",
          "target": null,
          "items": []
        },
        {
          "label": "Training exercises",
          "link": "/developer-portal/",
          "type": "page",
          "target": null,
          "items": []
        }
      ]
    }
  },
  "extensions": {}
}

Why are items all null? How can I access these? Is my yaml incorrectly formatted? I need to implement a dropdown menu in _override/NavBar.tsx and I'm unable to get past this barrier. Perhaps someone can point me in the right direction?

Rename UI components

On the portal homepage you are using the undocumented @redocly/ui components.

To make clear what is a reusable component and what is either markdown or HTML, please prevent using reserved HTML tags for component names.
Please use <Head1>, <Header1> or something else instead of <H1> as this could be a an HTML tag, or HTML in markdown.

OpenApiTryIt component shows "Incorrect definitionId" error

I forked this starter and tried to use the OpenApiTryIt MDX component as described in these docs:
https://redocly.com/docs/developer-portal/guides/step-by-step/

I added the catFacts API in the siteConfig.yaml file:

oasDefinitions:
  catFacts: https://catfact.ninja/docs/api-docs.json

Then I created this page in a file named developer-portal/openapi-try-it.mdx:

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

# Testing the openapi try it component

<OpenApiTryIt
  definitionId="catFacts"
  operationId="getRandomFact"
  id="step-1"
  onResponse={({ response }) => {
    console.log(response);
  }}
/>

When I run the portal locally and go to http://localhost:3000/developer-portal/openapi-try-it/ , I see an error that says Incorrect definitionId: "catFacts". What am I doing wrong? I've also tried downloading the openapi file and linking to it locally instead of putting the link in oasDefinitions.

Here's my minimal reproduction:
https://github.com/timothymcmackin/redocly-openapi-try-it

Markdownquery error

The version 1.0.0-beta.131 display following error when accessing http://localhost:3000/. Running in wndows server 2016 :-

ERROR #85910
Open in Editor
C:/redocly-workarea/developer-portal-starter-master/node_modules/@redocly/developer-portal/dist/engine/src/templates/simple-markdown.js
Multiple "root" queries found: "MarkdownQuery" and "MarkdownQuery".
Only the first ("MarkdownQuery") will be registered.

Instead of:

1 | query MarkdownQuery {
2 | markdownRemark {
3 | #...
4 | }
5 | }
6 |
7 | query MarkdownQuery {
8 | markdownRemark {
9 | #...
10 | }
11 | }

Do:

1 | query markdownQueryAndMarkdownQuery {
2 | markdownRemark {
3 | #...
4 | }
5 | markdownRemark {
6 | #...
7 | }
8 | }

This can happen when you use two page/static queries in one file. Please combine those into one query.
If you're defining multiple components (each with a static query) in one file, you'll need to move each component to its own file.
See our docs page for more info on this error: https://www.gatsbyjs.org/docs/graphql/

Thanks
Ramkumar.C

Control the position of list items

Add an option to the theme to control the position of elements for the list items, like CSS list-style-position to force the elements to be positioned outside of the text.

Feature Request - Add CSS classes for styling

Right now I'm finding it very difficult to style the portal. Styled Components are great and I love to use them for all of my own projects, but at the same this is a portal that is meant to be customized, often according to corporate design rules. The generated class names make it impossible to target specific elements of a page.

Example:

I need to add a simple left-hand border to the right-hand TOC menu. That's impossible right now because in the entire hierarchy there is no class to target it. I can't use aside.sc-bRubDb because obviously this can change. I could try to add a nested child selector (starting from body) to target it, but this can easily break if anything in the main structure happens to change in an update. It's also not possible to override the TOC component via the _overrides directory because it's not a UserComponent, and even if it were, the portal components are not open source (at least I can't find the original source anywhere apart from a few PR examples), and I would be stuck to reading the compiled and minified React.createElement code in node_modules/@redocly/developer-portal/dist/engines/src and painstakingly reinterpreting that as JSX to make sure it retains the identical behavior, just to add a few styles to it. I already had to do this this with the NavBar component because I had to add dropdown menus. It took a while to understand that your PRs are code examples because it's far from obvious and I haven't seen them mentioned anywhere in your documentation, and they of course don't match the original components 1:1.

It would be really helpful if you could add CSS classes to all of your components as hooks for styling. I would save myself hours of work if I could just add a global style such as .toc { border-left: 1px solid grey; } instead of going through the process above.

Components in nav allowed?

I want to set the context by having a couple of button components in the nav
E.g.

Can't start dev server - incorrect Gatsby dependency

Since upgrading to the latest version of developer-portal (1.0.0-beta.154), my development server no longer functions. When I run yarn start I get 2 warnings stating warn Plugin gatsby-remark-image-attributes is not compatible with your gatsby version 3.7.2 - It requires gatsby@^2.0.0 and then the process fails with an error:

Missing onError handler for invocation 'building-schema', error was 'Error: Cannot create as TypeComposer the following value:
  Date.'. Stacktrace was 'Error: Cannot create as TypeComposer the following value:
  Date.
    at SchemaComposer.createTempTC (/Users/llaidley/Projects/devportal-trial/node_modules/graphql-compose/lib/SchemaComposer.js:463:11)
    at SchemaComposer.createTC (/Users/llaidley/Projects/devportal-trial/node_modules/graphql-compose/lib/SchemaComposer.js:426:84)
    at SchemaComposer.add (/Users/llaidley/Projects/devportal-trial/node_modules/graphql-compose/lib/SchemaComposer.js:715:21)
    at createSchemaComposer (/Users/llaidley/Projects/devportal-trial/node_modules/@redocly/developer-portal/node_modules/gatsby/src/schema/schema-composer.js:16:18)
    at build (/Users/llaidley/Projects/devportal-trial/node_modules/@redocly/developer-portal/node_modules/gatsby/src/schema/index.js:104:26)
    at buildSchema (/Users/llaidley/Projects/devportal-trial/node_modules/@redocly/developer-portal/node_modules/gatsby/src/services/build-schema.ts:19:3)'

This is followed by the terminal hanging on building schema

For the moment, I'm going to try rolling my repo back to whichever previous version that works. Any chance we can get this fixed asap? Thanks in advance.

How do you style the button(s) in the documentation section?

Hello,

I would like to know how to change the styling of the buttons generated in the documentation section of the portal. See screenshot below(red arrow):

I have tried to style it through the theme.ts file, but it is quite limited. I can change the primary color but then the background color of the navbar and footer is changed as well.
Is there a way to style it or a way to create a custom React component that can overwrite this button?

Thanks in advance.

Greetings,

Kasra Tabrizi

How to access route changes?

In order to implement analytics, we need to be able to access route changes. In Gatsby, we make use of onClientEntry and onRouteUpdate since it behaves like an SPA. Your developer portal is built on Gatsby, but as far as I can tell, it does not expose these APIs for further use. There was a feature request for something like this in May 2020, but no reactions from Redocly. Could you please advise on how we could watch route changes with the current version of @redocly/developer-portal?

Dead link on developer-portal-starter/developer-portal/redoc-integration.md page

On this page

https://github.com/Redocly/developer-portal-starter/blob/8622c77f37a2cc7c58032c31a2cb5a5799722377/developer-portal/redoc-integration.md

This link

https://github.com/Redocly/developer-portal-starter/blob/resources/multi-file-definitions.md

is dead

MDX error

When using e472582 and going to a page with MDX directly: http://localhost:3000/developer-portal/mdx/, and an error is seen in Chrome developer console -

Warning: Invalid DOM property `class`. Did you mean `className`?
    in div (created by MDXTag)
    in MDXTag (created by Context.Consumer)
    in Unknown (at mdx.mdx:43)

Front conversations

Enterprise builds fail with "No space left on device"

We have a critical issue updating our documentation site using Enterprise builds. Earlier versions of our specifications were building fine, but after updating and re-adding a second specification to the portal, builds fail with the messages below using "@redocly/developer-portal": "1.0.0-beta.89".

success onPostBuild - 73.553s
9:28:15 AM: 
warning The size of at least one page context chunk exceeded 500kb, which could lead to degraded performance. Consider putting less data in the page context.
9:28:16 AM: 
warning Error persisting state: ENOSPC: no space left on device, write
...
9:28:17 AM: 
Portal build failed
9:28:17 AM: 
Deploy failed: updating build status

I beleive this to be due to the size of the specifications, and I was able to reproduce the issue using publically available specifications for the GitHub API. Both specs in our case are registry links, but this also fails with local files.

Reproduction steps (using public specifications)

Copy two versions of the GitHub OpenAPI spec
https://github.com/github/rest-api-description/blob/main/descriptions/api.github.com/api.github.com.yaml

Add to siteConfig.yaml

oasDefinitions:
  g1: specifications/github-one.openapi.yaml
  g2: specifications/github-two.openapi.yaml

Both are defined as below in /openapi directory, with a config for each.

definitionId: g2
showInfo: true
expand: true
settings:
  jsonSampleExpandLevel: 'all'
  expandResponses: '200'
  hideDownloadButton: true
  requiredPropsFirst: false
  sortPropsAlphabetically: false
  showExtensions: false
  showConsole: false

When committing this change, the build fails as described.

This issue is currently blocking progress for our team, so please reach out should you need help reproducing.

theme.ts: Explain use of typography

I am making great progress with branding the developer portal. Customisation of fonts, colours, etc. seems quite easy to understand and to implement. The devil is in the details however.

For example:
When I look at the rendered output of the links <a> in the footer, they seem to have a font-weight:700, which I didn't define anywhere. The <a> in the navigation has font-weight:600 in turn. In theme.ts I only find a 'fontWeightBold'; however there is no pointing to where this is applicable in the rendered output.

Please be a bit more descriptive on where each property is being used.

Sidebar styling issue

Hey everyone,

I have a problem styling the sidebar of the portal. I can only style the backgroundColor and the width (see code snippet in theme.ts)

sidebar: {
    backgroundColor: '#fafafa',
    width: '260px',
  },

However, I would like to style the text color, border radius, background color when hovering. Adding those properties doesn't seem to do anything. I did a bit of a digging in the redoc/typings/utils/theme.d.ts where I found the following:

    sidebar: {
        width: string;
        backgroundColor: string;
        textColor: string;
        activeTextColor: string;
        groupItems: {
            textTransform: string;
        };
        level1Items: {
            textTransform: string;
        };
        arrow: {
            size: string;
            color: string;
        };
    };

I tried adding a textColor and arrow property to my theme.ts file but nothing happened to the styling.
Is there a way to add extra properties to the theme.ts or do I also have to override the whole sidebar nav?

Thanks in advance,

Greetings,

Kasra Tabrizi

Feature Request: Allow the API Info section to be hidden

This is the same request from earlier, from the API Reference Product - Redocly/redoc#942

user confused by multiple "components" dirs with different functions

create-openapi-repo makes the structure:

./
    openapi/
         components/ 
         paths/
         openapi.yaml

the developer-portal-starter has the strucure

./
    components/
    openapi/
         paths/
         openapi.yaml

So, the relative inter-directory relationships between file paths in the paths files and in the component files are also different.

Great fun when coming to a project built from the developer-portal and wanting to add an API split up by create-openapi-repo.

Are Redocly's tools meant to be internally inconsistent?

Sidebar Floating Action Button styles

Need some help to customise the floating action button for mobile users.

the majority of our site is black and white, this causes an issue with the FAB. with the use of colors.primary.main = black because the FAB bg is based on the colors.primary.main and the icon is also set to black. Need a way to customise the FAB