Skip to content
This repository was archived by the owner on Aug 18, 2023. It is now read-only.

Commit bc8caae

Browse files
RomanHotsiyadamaltman
RomanHotsiy
authored and
adamaltman
committed
initial commit
0 parents  commit bc8caae

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+19070
-0
lines changed

Diff for: ‎.editorconfig

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# EditorConfig is awesome: https://EditorConfig.org
2+
3+
# top-most EditorConfig file
4+
root = true
5+
6+
# Unix-style newlines with a newline ending every file
7+
[*.{md,mdx,yaml}]
8+
end_of_line = lf
9+
insert_final_newline = true
10+
charset = utf-8
11+
indent_style = space
12+
trim_trailing_whitespace = true

Diff for: ‎.gitignore

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules
2+
public/

Diff for: ‎.vscode/settings.json

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"cSpell.words": [
3+
"redocly"
4+
]
5+
}

Diff for: ‎LICENSE

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Copyright (c) 2019-present, Redocly, LLC.
2+
3+
The software depends on "@redocly/developer-portal" which requires a commercial
4+
license. See: https://redoc.ly/subscription-agreement/
5+
6+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
7+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
8+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
9+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
10+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
11+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
12+
SOFTWARE.

Diff for: ‎README.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Redocly API developer portal
2+
3+
## Prerequisites
4+
5+
- [node.js >= 10.15.1](https://nodejs.org/en/)
6+
- [yarn](https://yarnpkg.com/en/)
7+
8+
## Install
9+
10+
yarn install
11+
12+
## Start development server
13+
14+
yarn start
15+
16+
Note: search isn't functional in the development environment.
17+
18+
## Troubleshooting
19+
20+
We heavily rely on caching for performance issues so if some changes are not reflected in the resulting portal try cleaning cache by running:
21+
22+
yarn clean
23+
24+
## Docs
25+
26+
Read the [online documentation](https://docs.redoc.ly/developer-portal/introduction/).
27+
28+
## Training program
29+
30+
The starter template contains training exercises which will teach you how to build a developer portal.
31+
After you start the development server, navigate to the app and follow the instructions to get started with your training.

Diff for: ‎components/Counter.tsx

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import * as React from 'react';
2+
3+
export function Counter() {
4+
const [count, setCount] = React.useState(0);
5+
6+
return (
7+
<div style={{ border: '1px solid red', padding: '10px' }}>
8+
<div style={{ fontSize: '18px', marginBottom: '10px' }}>
9+
Clicks: <strong>{count}</strong>
10+
</div>
11+
<button onClick={() => setCount(count + 1)}> Click </button>
12+
</div>
13+
);
14+
}

Diff for: ‎contact.mdx

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Contact Us
3+
---
4+
5+
import { Flex, WideTile } from '@redocly/ui'
6+
7+
# Contact us
8+
9+
You may reach us by email, team [at] redoc [dot] ly. (replace the at and the dot with the appropriate characters)
10+
11+
**Use React components here, too!**
12+
13+
<Flex justifyContent="space-between">
14+
<WideTile to="https://google.com" title="Can't find your answer?">
15+
Google it! <br/>
16+
Use Google to find things.
17+
</WideTile>
18+
</Flex>

Diff for: ‎developer-portal/analytics.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Enable analytics
2+
3+
Whether you utilize Google Analytics, Google Tag Manager, Heap.io or something else, it can be enabled with a few lines of configuration in the `siteConfig.yaml`.
4+
5+
<div class="attention">Analytics is disabled in development server mode. So enabling will have no impact until built and deployed.</div>
6+
7+
## Google Analytics
8+
9+
Let's say our tracking id is `UA-132456789-1`.
10+
11+
```yaml
12+
ga:
13+
# you can use any options here from https://www.gatsbyjs.org/packages/gatsby-plugin-google-analytics/
14+
# note that GA doesn't work in DEV
15+
trackingId: UA-132456789-1
16+
```
17+
18+
## Other JavaScript add-ons
19+
20+
If we needed to enable some other JavaScript, we can do that too.
21+
Here is an example of enabling the Intercom chat widget.
22+
You would replace the part that says `your-code` with your intercom id.
23+
24+
```yaml
25+
scripts:
26+
- ./static/intercom.js
27+
```
28+
29+
```js
30+
window.intercomSettings = {
31+
app_id: "hvbieiwv"
32+
};
33+
34+
(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/your-code';var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};if(d.readyState === 'complete'){l()} else {if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}}})();
35+
```

Diff for: ‎developer-portal/awesome/folders.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Folder structure training
2+
3+
## Changing URL paths
4+
5+
The filename is used in the URL path and so is the folder.
6+
Nested folders will result in deep paths.
7+
8+
If you look at the path for this page, you'll see it is at `/developer-portal/awesome/folders`.
9+
10+
![path](../images/folders-url.png)
11+
12+
The title of the page is `Folder structure training` and doesn't match the path.
13+
14+
![path](../images/folders-path.png)
15+
16+
The path is generated from the folder structure path and filename less the filename extension (`.md` in this case).
17+
If the file is named `index.md` or `index.mdx` the filename does not appear in the URL path.
18+
19+
If we renamed `folders.md` to `index.md` and left it in the same folder, what would the URL be?
20+
21+
```
22+
http://localhost:3000/developer-portal/awesome/
23+
```
24+
25+
Let's try it out...
26+
27+
### Rename to index
28+
29+
Rename the `folders.md` file to `index.md`.
30+
31+
You will also need to change references to that file, which exist in the `sidebars.yaml` file located in the root directory.
32+
33+
```Original
34+
- label: Folder structure
35+
page: developer-portal/awesome/folders.md
36+
```
37+
38+
```New
39+
- label: Folder structure
40+
page: developer-portal/awesome/index.md
41+
```
42+
43+
Great? Now, revert the name back to `folders.md` and revert the change in the `sidebars.yaml` file.
44+
45+
46+
### Move the file to a different folder
47+
48+
Move this `folders.md` to the root directory.
49+
The root directory means it will site side-by-side with other files and folders such as `siteConfig.yaml` and `sidebars.yaml`.
50+
51+
This file is referenced in `sidebars.yaml`.
52+
Adjust the relative path to the file from there again.
53+
54+
```Original
55+
- label: Folder structure
56+
page: developer-portal/awesome/folders.md
57+
```
58+
59+
```New
60+
- label: Folder structure
61+
page: folders.md
62+
```
63+
64+
Adjust the relative path to the images within the actual file too.
65+
66+
If the image is broken (does not load), it indicates the path to the image is incorrect.
67+
68+
The current directory means the directory where the markdown file is located.
69+
The `./` start means starting from the current directory.
70+
The `../` moves up to the parent directory.
71+
And `../../` moves up two levels.
72+
And so on.
73+
74+
## Troubleshooting
75+
76+
Files, folders, and navigation paths may be cached.
77+
If your page isn't loading check if you have the correct path in the browser.
78+
If it still isn't loading, [try the `yarn clean` fix](/developer-portal/install#clearing-cache).

Diff for: ‎developer-portal/colors.md

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Colors
2+
3+
> “Color is a power which directly influences the soul.” - Wassily Kandinsky
4+
5+
Colors are set within the `theme.ts` file.
6+
The `theme.ts` file contains a typescript variable named `theme` which controls the colors, styles and typography.
7+
8+
```ts
9+
export const theme = {
10+
```
11+
12+
The included `theme.ts` includes all of the configuration options (most are commented out as default settings with two slashes `//`).
13+
Uncomment them to override the theme.
14+
15+
16+
## Change the primary color
17+
18+
Find this section of the theme file.
19+
20+
21+
```ts
22+
colors: {
23+
// tonalOffset: 0.2,
24+
primary: {
25+
main: '#227a88',
26+
// light: ({ colors }) => lighten(colors.tonalOffset, colors.primary.main),
27+
// dark: ({ colors }) => darken(colors.tonalOffset, colors.primary.main),
28+
// contrastText: ({ colors }) => readableColor(colors.primary.main),
29+
},
30+
```
31+
32+
Change the color.
33+
Not sure what to change it to?
34+
Try randomly guessing a hexadecimal value (0-9 and a-f are valid values).
35+
It also accepts human friendly colors like `orange`.
36+
37+
## Change the primary text color
38+
39+
Or not...
40+
41+
```ts
42+
text: {
43+
primary: '#424242',
44+
// secondary: '#4e566d',
45+
},
46+
```
47+
48+
## Change the footer background color
49+
50+
Pick a color.
51+
52+
Or change any other colors you want.
53+
54+
```ts
55+
footer: {
56+
main: '#424242',
57+
// main: ({ colors }) => colors.primary.main,
58+
contrastText: 'white'
59+
},
60+
```
61+
62+
## Free time
63+
64+
Play with some various colors.
65+
66+
Notice you can use typescript to calculate colors, if you wish.
67+
That is beyond the scope of this training exercise.

Diff for: ‎developer-portal/configuration.md

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Configuration
3+
---
4+
5+
# Configuration
6+
7+
This page describes how to organize the files and folders and how to configure the look and feel of the **Portal**.
8+
9+
---
10+
11+
## Overview ##
12+
13+
To start working with **Redocly Portal**, please get familiar with the following:
14+
* The [Markdown](https://www.markdownguide.org/basic-syntax/) syntax. We recommend using [**Visual Studio Code**](https://code.visualstudio.com/) for writing and maintaining your files.
15+
* File management basics.
16+
17+
## Organizing content ##
18+
19+
### Folders
20+
21+
The following special folders will be created automatically within your project:
22+
23+
1. **images**/ – you can keep your images in this folder.
24+
2. **node_modules**/ – do not remove or modify the contents of this folder. It contains the software library dependencies.
25+
26+
We recommend creating folders based on your content, and then organizing the content within one root folder:
27+
```
28+
[_folder_name_]/
29+
```
30+
**Important**: The folder naming influences the URL paths of the published website.
31+
32+
### File types
33+
34+
**Markdown files**
35+
36+
A regular markdown file ends with a `.md` file extension. Utilize the regular markdown files when your content doesn't require any special components.
37+
38+
**Markdown extensions**
39+
40+
A markdown extension file ends with a `.mdx` file extension. Learn more about [using markdown extensions here](markdown-extensions.mdx).
41+
42+
**Special files**
43+
44+
The following files must be kept at the top level of the project structure.
45+
If needed, you can change the contents of these files to configure look and feel of the **Portal**.
46+
47+
48+
| File | Description |
49+
| ------------- | ------------- |
50+
| `index.mdx` | The home page of the **Portal**. |
51+
| `siteConfig.yaml` | In this file, you can do the following: <br> <ul><li>Set up persistent navigation and logo.</li><li>Declare API definitions and stylesheets.</li><li>Add custom scripts.</li><li>Set up google analytics.</li></ul>|
52+
| `theme.ts` | Controls the fonts and colors used throughout the **Portal**. |
53+
| `sidebars.yaml` | Controls the [sidebar navigation](/developer-portal/sidebar-nav) among contents. |
54+
| `favicon.png` | Displays the favicon. |
55+
56+
For more details, see [Customizing Portal](/developer-portal/custom-portal/).
57+
58+
Also, you can include your OpenAPI .yaml or .json file directly in the **Portal** to be able to generate the API reference pages.
59+
60+
For more details, see [Integrating API Reference](./redoc-integration.md).
61+

Diff for: ‎developer-portal/ctrl-c.png

13.3 KB
Loading

Diff for: ‎developer-portal/custom-component.mdx

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Creating React Components
3+
---
4+
5+
import { Counter } from '../components/Counter.tsx'
6+
7+
# Creating React components
8+
9+
This page describes developing React components for **Redocly Portal**.
10+
11+
---
12+
13+
## Component example
14+
15+
<Counter />
16+
17+
TBD
18+

Diff for: ‎developer-portal/custom-portal.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Customization
3+
---
4+
5+
# Customizing Portal
6+
7+
This page describes how to customize the look and feel of the **Portal**.
8+
9+
---
10+
<!--
11+
- The following topics will be developed later
12+
-->
13+
14+
**Customize the look and feel of the website**
15+
16+
`siteConfig.yaml`
17+
18+
**Set up fonts and colors**
19+
20+
`theme.ts`
21+
22+
**Set up page navigation**
23+
24+
`sidebars.yaml`
25+
26+
For more advanced functionality, you can add the custom React components.
27+
28+
<!--
29+
- /To be continued/
30+
-->

0 commit comments

Comments
 (0)