Skip to content

chore: resolve breaking changes in new Starlight #2

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

Merged
huijing merged 1 commit into from
Oct 9, 2023
Merged

chore: resolve breaking changes in new Starlight #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
238 changes: 19 additions & 219 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,232 +40,32 @@ import { CodeBlock, Disclosure } from "@interledger/docs-design-system";

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
All the above components are documented at our [documentation style guide](https://interledger.tech).

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:
## Contributing

```jsx
import { CodeBlock } from "@interledger/docs-design-system";
```
As this is a shared library, it is a dependency for other projects, specifically all Interledger documentation websites. A good way to check who is using this library is via GitHub search: https://github.com/search?q=%22%40interledger%2Fdocs-design-system%22%3A+&type=code.

Use the `<CodeBlock>` component within your content like so:
Our theme does override a number of Starlight defaults, therefore it is inevitable that if the Starlight internals are modified as they continue to release new features, we will have to make the corresponding updates to this library as well, to make sure nothing breaks. The documentation style guide is a good target to determine if the proposed changes you want to make to the library work correctly or not.

````
<CodeBlock title="Response">
The suggested workflow is as follows:

```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",
}
```
1. Clone both the documentation style guide and this library

</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:

```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.

```jsx
<LargeImg
src="/img/OMG_A_GIGANTIC_IMG.png"
alt="A really large diagram"
hasBorder={false}
/>
```

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

Starlight does not support Mermaid by default, so you would have to install [remark-mermaidjs](https://github.com/remcohaszing/remark-mermaidjs) on your Starlight site before you can use this 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";
```
```bash
git clone https://github.com/interledger/docs-design-system.git
```

Use the `<Tooltip>` component within your content like so:
```bash
git clone https://github.com/interledger/docs-styleguide.git
```

```jsx
<Tooltip content='THIS CONTENT IS DISPLAYED IN THE TOOLTIP UPON INTERACTION' client:load><span>text that you are trying to explain</span></Tooltip>.
```
2. Make the documentation style guide read from the local version of the docs-design-system library by modifying the package.json. This will depend on the file structure of your local machine but it would look something like this:

If the text you are trying to explain is also a link to somewhere else, please put the link within the `<Tooltip>` like so:
```json
"dependencies": {
"@interledger/docs-design-system": "../docs-design-system",
}
```

```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>.
```
3. After you're done with your changes and have tested that all is well, feel free to make a pull request and it will get reviewed, and hopefully merged into the source code. The version will get bumped and all the sites will have to make an update to their dependencies as well.
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@interledger/docs-design-system",
"version": "0.0.13",
"version": "0.0.14",
"type": "module",
"description": "Shared styles and components used across all Interledger Starlight documentation sites",
"exports": {
Expand Down
16 changes: 8 additions & 8 deletions src/styles/ilf-docs.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,25 +74,25 @@
}

/* Navigation sidebar styles */
.sidebar-content .sidebar ul {
.sidebar-content ul {
--sl-sidebar-item-padding-inline: var(--space-s);
}

.sidebar-content .sidebar li {
.sidebar-content li {
margin: 0;
}

.sidebar-content .sidebar a {
.sidebar-content a {
padding: var(--space-2xs) var(--sl-sidebar-item-padding-inline);
}

.sidebar-content .sidebar summary {
.sidebar-content summary {
padding: var(--space-2xs) var(--sl-sidebar-item-padding-inline);
}

.sidebar-content .sidebar a[aria-current="page"],
.sidebar-content .sidebar a[aria-current="page"]:hover,
.sidebar-content .sidebar a[aria-current="page"]:focus {
.sidebar-content a[aria-current="page"],
.sidebar-content a[aria-current="page"]:hover,
.sidebar-content a[aria-current="page"]:focus {
color: var(--sl-color-text-accent);
background-color: var(--sl-color-accent-low);
border-radius: 0;
Expand All @@ -105,7 +105,7 @@
z-index: 0;
}

.sidebar-content .sidebar {
.sidebar-content {
padding: 0;
}
}
Expand Down