diff --git a/README.md b/README.md index c57a1dd..8cc8034 100644 --- a/README.md +++ b/README.md @@ -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 `` 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. - ```` - +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 - - ```` - -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 `` component within your content like so: - - ```jsx - - - - ``` - - For the specific use-case of displaying multiple code-snippets, it might be worth considering also using the [built-in Starlight ``](https://starlight.astro.build/guides/components#tabs) component: - - ````jsx - - - - ```bash - GET /alice HTTP/1.1 - Accept: application/json - Host: wallet.example - ``` - - - ```bash - HTTP/1.1 200 Success - Content-Type: application/json - - { - "id":"https://wallet.example/alice", - "assetCode":"USD", - "assetScale":2, - "authServer":"https://wallet.example/auth", - } - ``` - - - - - ```` - -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 `` component within your content like so: - - ```jsx - - ``` - - 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 - - ``` - - For user doc diagrams, be sure to include the `docs` folder in the path. - - ```jsx - - ``` - -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 `` component within your content like so: - - ```jsx - OpenPayments API - ``` - - If you do not want the external link icon to appear, you can set the `withIcon` prop to `false` like so: - - ```jsx - - OpenPayments API - - ``` - -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 `` component within your content like so: - - ````jsx - - ```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 -
- long time, so long -
- that the text does -
- not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes... - John, how are you? ``` - - ```` - - 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 - - ```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 -
- long time, so long -
- that the text does -
- not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes... - John, how are you? ``` - - ```` - -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 `` component within your content like so: - - ```jsx - Wow I'm a stylish header - ``` - -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 `` component within your content like so: +```bash +git clone https://github.com/interledger/docs-styleguide.git +``` - ```jsx - text that you are trying to explain. - ``` +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 `` like so: +```json +"dependencies": { + "@interledger/docs-design-system": "../docs-design-system", +} +``` - ```jsx - text that you are trying to explain. - ``` +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. diff --git a/package.json b/package.json index 74aa777..ee7cea2 100644 --- a/package.json +++ b/package.json @@ -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": { diff --git a/src/styles/ilf-docs.css b/src/styles/ilf-docs.css index 57ad38f..1e6e9f1 100644 --- a/src/styles/ilf-docs.css +++ b/src/styles/ilf-docs.css @@ -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; @@ -105,7 +105,7 @@ z-index: 0; } - .sidebar-content .sidebar { + .sidebar-content { padding: 0; } }