redocly / developer-portal-starter Goto Github PK
View Code? Open in Web Editor NEWStarter template for the Redocly developer portal
Home Page: https://redoc.ly
License: Other
Starter template for the Redocly developer portal
Home Page: https://redoc.ly
License: Other
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?
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?
This is the same request from earlier, from the API Reference Product - Redocly/redoc#942
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.
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
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)
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
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
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!
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
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?
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.
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
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.
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
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
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
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.
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
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
?
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?
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 .
Looking through the compiled code (such as@redocly/developer-portal/dist/engine/src/fragments.js
and @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?
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.
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!
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
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.
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?
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?
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
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!
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
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/*"
No "Error" messages, but didn't work
- 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.
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]"
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.
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
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.
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
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]"
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.
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.
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.
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.
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.
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".
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!
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?
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 ;)
Within Markdown the following headers are valid
# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
which results in
However in the theme.ts
only option heading1 till heading3 are valid. Please make all headings themeable.
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
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
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.