Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update README and package.json #2026

Merged
merged 2 commits into from
Oct 19, 2023
Merged

chore: update README and package.json #2026

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1e7477b
Update README and package.json
huijing Oct 12, 2023
8c91341
Update dependencies again
huijing Oct 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
282 changes: 26 additions & 256 deletions packages/documentation/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ This website is built with [Starlight](https://starlight.astro.build/), a docume

### Local Development

- Make sure all the dependencies for the website are installed:
- Make sure all the dependencies for the website are installed. Because this is a monorepo, you should run the following command in the root of the project folder:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something like "should run the following in this project folder (/packages/documentation)" to differentiate from the "root"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just assumed the person would install the dependencies throughout the repo. Because when we make changes to the dependencies on the repo, the pnpm-lock is updated outside the repo anyway.


```sh
$ pnpm i
```

- Run the dev server:
- Run the dev server from the /packages/documentation folder:

```sh
$ pnpm start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

- Build the site:
- Build the site, again, this must be run from the /packages/documentation folder:

```sh
$ pnpm build
Expand All @@ -32,7 +32,13 @@ This command generates static content into the build directory and can be served

## Editing Content

Due to the nature of how Starlight deals with content and their generated URLs, all docs content lives in `/src/content/docs/`. For example, the home page of the documentation lives within the `/src/content/docs/` folder and is rendered at rafiki.dev, not rafiki.dev/docs.
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. Due to the nature of how Starlight deals with content and their generated URLs, all docs content lives in `/src/content/docs/`. For example, the home page of the documentation lives within the `/src/content/docs/` folder and is rendered at rafiki.dev, not rafiki.dev/docs.

Static assets, like favicons or images, can be placed in the `public/` directory. When referencing these assets in your markdown, you do not have to include `public/` in the file path, so an image would have a path like:

```md
![A lovely description of your beautiful image](/img/YOUR_BEAUTIFUL_IMAGE.png)
```

### Editing an existing docs page

Expand All @@ -52,246 +58,26 @@ Refer to the Starlight documentation on [authoring content](https://starlight.as

### Docs components

We have extracted some of the commonly repeated patterns within the documentation pages into custom docs components that can be reused. There are components which are shared across all our Starlight documentation sites and those which are specific to Web Monetization only. This will determine what the import path is.

- [CodeBlock](#codeblock-component)
- [Disclosure](#disclosure-component)
- [Hidden](#hidden-component)
- [LargeImg](#largeimg-component)
- [LinkOut](#linkout-component)
- [MermaidWrapper](#mermaidwrapper-component)
- [StylishHeader](#stylishheader-component)
- [Tooltip](#tooltip-component)

For more information about importing things in Javascript, please refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).

1. #### `CodeBlock` component

Use this component if you wish to add a title to your code block. It takes a `title` attribute, which will be displayed above the code. To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `CodeBlock` component like so:

```jsx
import { CodeBlock } from '@interledger/docs-design-system'
```

Use the `<CodeBlock>` component within your content like so:

````
<CodeBlock title="Response">

```http
{
"id":"https://wallet.example/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c",
"paymentPointer":"https://wallet.example/alice",
"receivedAmount": {
"value":"0",
"assetCode":"USD",
"assetScale":2
},
"completed":false,
"createdAt":"2022-03-12T23:20:50.52Z",
"updatedAt":"2022-03-12T23:20:50.52Z",
}
```

</CodeBlock>
````

1. #### `Disclosure` component

Use this component if you have some content that you want to show/hide via a collapsible container. This component wraps around whatever content you wish to have this expand/collapse behaviour. Note that the `client:load` attribute is required for the functionality to work because this component relies on state.

To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `Disclosure` component like so:

```jsx
import { Disclosure } from '@interledger/docs-design-system'
```

Use the `<Disclosure>` component within your content like so:

```jsx
<Disclosure toggleText='Show code snippets' client:load>
<!-- Your content, can be markup or markdown -->
</Disclosure>
```

For the specific use-case of displaying multiple code-snippets, it might be worth considering also using the [built-in Starlight `<Tabs>`](https://starlight.astro.build/guides/components#tabs) component:

````jsx
<Disclosure toggleText='Show code snippets' client:load>
<Tabs>
<TabItem label='Request'>
```bash
GET /alice HTTP/1.1
Accept: application/json
Host: wallet.example
```
</TabItem>
<TabItem label='Response'>
```bash
HTTP/1.1 200 Success
Content-Type: application/json

{
"id":"https://wallet.example/alice",
"assetCode":"USD",
"assetScale":2,
"authServer":"https://wallet.example/auth",
}
```
</TabItem>

</Tabs>
</Disclosure>
````

1. #### `Hidden` component

Use this component to hide content that is temporarily not ready to be shown to the public. This is not meant for long-term use, but a stop-gap when the current implementation is still far away from our documentation/specifications, and the content we have will be relevant but in the future.

```jsx
import { Hidden } from '@interledger/docs-design-system'
```

Unfortunately, due to the nature of how the ToC on the right is generated, if we want to hide an entire section (including the header), we will have to manually hide the section heading by either commenting it out or deleting it.

1. #### `LargeImg` component

Use this component if you have a diagram or image that is much larger than our available space and you would like users to view the full image in another tab. This adds a link to "View full image" with an external link indicator on the bottom right corner under the image. It takes in a `src` and `alt`, just like a normal `img` element.

To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `LargeImg` component like so:

```jsx
import { LargeImg } from '@interledger/docs-design-system'
```

Use the `<LargeImg>` component within your content like so:
We have extracted some of the commonly repeated patterns within the documentation pages into custom docs components that can be reused. There are components which are shared across all our Starlight documentation sites and those which are specific to this project only. This will determine what the import path is.

```jsx
<LargeImg src='/img/OMG_A_GIGANTIC_IMG.png' alt='A really large diagram' />
```

By default, there will be a border around the image, but if you want to remove the border, pass in a `hasBorder={false}` attribute.
- CodeBlock (Shared)
- Disclosure (Shared)
- Hidden (Shared)
- LargeImg (Shared)
- LinkOut (Shared)
- MermaidWrapper (Shared)
- StylishHeader (Shared)
- Tooltip (Shared)

```jsx
<LargeImg
src='/img/OMG_A_GIGANTIC_IMG.png'
alt='A really large diagram'
hasBorder={false}
/>
```
For the shared components, if you are using both `CodeBlock` and `Disclosure` on the same page, you can import them both like so:

For user doc diagrams, be sure to include the `docs` folder in the path.

```jsx
<LargeImg
src='/img/docs/OMG_A_GIGANTIC_IMG.png'
alt='A really large diagram'
/>
```

1. #### `LinkOut` component

Use this component if you need to add an external link to your content that opens in a new tab. This component adds the necessary attributes for external links and adds an external link indicator icon to the end of the link content. The icon can be turned off, if necessary.

To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `LinkOut` component like so:

```jsx
import { LinkOut } from '@interledger/docs-design-system'
```

Use the `<LinkOut>` component within your content like so:

```jsx
<LinkOut href='https://openpayments.guide/'>OpenPayments API</LinkOut>
```

If you do not want the external link icon to appear, you can set the `withIcon` prop to `false` like so:

```jsx
<LinkOut href='https://openpayments.guide/' withIcon={false}>
OpenPayments API
</LinkOut>
```

1. #### `MermaidWrapper` component

Use this component if your Mermaid diagram is much larger than our available space and you would like users to view the full diagram in another tab. This adds "View full diagram" button with an external link indicator on the bottom right corner under the diagram. Note that the `client:load` attribute is required for the functionality to work because this component relies on state.

To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `MermaidWrapper` component like so:

```jsx
import { MermaidWrapper } from '@interledger/docs-design-system'
```

Use the `<MermaidWrapper>` component within your content like so:

````jsx
<MermaidWrapper client:load>
```mermaid sequenceDiagram Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John? Bob--x Alice: I am good thanks! Bob-x
John: I am good thanks! Note right of John: Bob thinks a long
<br />
long time, so long
<br />
that the text does
<br />
not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes...
John, how are you? ```
</MermaidWrapper>
````

By default, there will be a border around the image, but if you want to remove the border, pass in a `hasBorder={false}` attribute.

````jsx
<MermaidWrapper client:load hasBorder={false}>
```mermaid sequenceDiagram Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John? Bob--x Alice: I am good thanks! Bob-x
John: I am good thanks! Note right of John: Bob thinks a long
<br />
long time, so long
<br />
that the text does
<br />
not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes...
John, how are you? ```
</MermaidWrapper>
````

1. #### `StylishHeader` component

Use this component if you wish to create a stylized heading that does not use the heading elements such that it will not appear in the ToC right sidebar. To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `StylishHeader` component like so:

```jsx
import { StylishHeader } from '@interledger/docs-design-system'
```

Use the `<StylishHeader>` component within your content like so:

```jsx
<StylishHeader>Wow I'm a stylish header</StylishHeader>
```

1. #### `Tooltip` component

Use the tooltip component for adding a short explanation to specific terms. This component is built to be accessible in accordance to the guidance from [WAI Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/). Note that the `client:load` attribute is required for the functionality to work because this component relies on state.

To use it, your docs page must be in `.mdx` format. Please change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. Import the `Tooltip` component like so:

```jsx
import { Tooltip } from '@interledger/docs-design-system'
```

Use the `<Tooltip>` component within your content like so:

```jsx
<Tooltip content='THIS CONTENT IS DISPLAYED IN THE TOOLTIP UPON INTERACTION' client:load><span>text that you are trying to explain</span></Tooltip>.
```
```jsx
import { CodeBlock, Disclosure } from '@interledger/docs-design-system'
```

If the text you are trying to explain is also a link to somewhere else, please put the link within the `<Tooltip>` like so:
For more information about importing things in Javascript, please refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).

```jsx
<Tooltip content='THIS CONTENT IS DISPLAYED IN THE TOOLTIP UPON INTERACTION' client:load><a href="/URL">text that you are trying to explain</a></Tooltip>.
```
The available shared components are documented at our [documentation style guide](https://interledger.tech).

## Adding Content

Expand All @@ -308,23 +94,7 @@ title: This Doc Needs To Be Written
My new content here..
```

The sidebar of the documentation site is configured in the `astro.config.mjs`.

```javascript
// Add newly-created-doc to the Getting Started category of docs
{
"docs": {
"Getting Started": [
"quick-start",
"newly-created-doc" // new doc here
],
...
},
...
}
```

Refer to the Starlight documentation on [sidebar configuration](https://starlight.astro.build/reference/configuration/#sidebar/) for more detailed guidance.
The sidebar of the documentation site is configured in the `astro.config.mjs`. Refer to the Starlight documentation on [sidebar configuration](https://starlight.astro.build/reference/configuration/#sidebar/) for more detailed guidance.

### Adding custom pages

Expand Down
3 changes: 0 additions & 3 deletions packages/documentation/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'

import react from '@astrojs/react'

import remarkMath from 'remark-math'
import rehypeMathjax from 'rehype-mathjax'
import remarkMermaid from 'remark-mermaidjs'
Expand Down Expand Up @@ -177,7 +175,6 @@ export default defineConfig({
}
]
}),
react(),
GraphQL({
schema: '../backend/src/graphql/schema.graphql',
output: './src/content/docs/apis/backend/',
Expand Down
9 changes: 2 additions & 7 deletions packages/documentation/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,11 @@
"astro": "astro"
},
"dependencies": {
"@astrojs/react": "^3.0.3",
"@astrojs/starlight": "^0.11.1",
"@interledger/docs-design-system": "^0.1.0",
"@types/react": "^18.2.28",
"@types/react-dom": "^18.2.13",
"astro": "3.2.3",
"@interledger/docs-design-system": "^0.1.1",
"astro": "3.3.2",
"astro-graphql-plugin": "^0.1.0",
"graphql": "^16.8.1",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"rehype-mathjax": "^5.0.0",
"remark-math": "^6.0.0",
"remark-mermaidjs": "^6.0.0",
Expand Down
14 changes: 8 additions & 6 deletions packages/documentation/src/components/Header.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@ import type { Props } from '@astrojs/starlight/props';
import Search from "@astrojs/starlight/components/Search.astro";
import ThemeSelect from "@astrojs/starlight/components/ThemeSelect.astro";
import SocialIcons from "@astrojs/starlight/components/SocialIcons.astro";
import RafikiLogo from "../components/RafikiLogo.astro";
---
<div class="header sl-flex">
<a href="/" class="site-logo">
<img src="/img/logo.svg" alt="Rafiki logo">
<RafikiLogo />
</a>
<div class="secondary-wrap">
<Search {...Astro.props} />
Expand Down Expand Up @@ -39,15 +40,16 @@ import SocialIcons from "@astrojs/starlight/components/SocialIcons.astro";
.site-logo {
display: flex;
align-items: center;
gap: 0.5em;
gap: var(--space-xs);
font-size: larger;
}

.site-logo img {
.site-logo svg {
width: 6em;
flex: none;
}

.site-logo span {
font-size: larger;
white-space: nowrap;
[data-theme='dark'] :global(.logo-text) {
fill: white;
}
</style>
Loading