diff --git a/public/img/rafiki-overflow-table.png b/public/img/rafiki-overflow-table.png new file mode 100644 index 0000000..87142d4 Binary files /dev/null and b/public/img/rafiki-overflow-table.png differ diff --git a/public/img/rafiki-overflow-wide.png b/public/img/rafiki-overflow-wide.png new file mode 100644 index 0000000..03668ad Binary files /dev/null and b/public/img/rafiki-overflow-wide.png differ diff --git a/public/img/rafiki-overflow-wider.png b/public/img/rafiki-overflow-wider.png new file mode 100644 index 0000000..06bcc37 Binary files /dev/null and b/public/img/rafiki-overflow-wider.png differ diff --git a/src/content/docs/classes/details.mdx b/src/content/docs/classes/details.mdx index 14d4ff1..daa9145 100644 --- a/src/content/docs/classes/details.mdx +++ b/src/content/docs/classes/details.mdx @@ -8,7 +8,7 @@ The `
` disclosure element is an HTML element that creates a disclosure We also have an in-house [Disclosure component](/shared/disclosure), but we decided in October 2024 to move away from using it. We may deprecate the component completely in the future. ::: -You can nest any other Markdown syntax inside a `
` element. Some, if not all, of Starlight's components can also be nested. For example, you can use an aside within the element. +You can nest any other Markdown syntax inside a `
` element. Some, if not all, of Starlight's components can also be nested. For example, you can use an aside in the element. ## Example usage diff --git a/src/content/docs/content/api.mdx b/src/content/docs/content/api.mdx index d67c740..7b8f869 100644 --- a/src/content/docs/content/api.mdx +++ b/src/content/docs/content/api.mdx @@ -9,7 +9,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components' This guide is designed for writers and contributors involved in documenting our APIs, which use both GraphQL and REST API technologies. -At Interledger, we maintain multiple repositories that encompass a variety of projects, each serving different purposes within our ecosystem. This style guide aims to provide a cohesive framework for documenting these APIs so that our docs are clear, consistent, and aligned with our standards. +At Interledger, we maintain multiple repositories that encompass a variety of projects, each serving different purposes in our ecosystem. This style guide aims to provide a cohesive framework for documenting these APIs so that our docs are clear, consistent, and aligned with our standards. ## GraphQL @@ -23,7 +23,7 @@ For more in-depth information about GraphQL, take a look at the following resour ### Documenting GraphQL examples -We've created a standardized format to maintain a consistent look and feel when documenting example GraphQL queries and mutations. Each GraphQL example should be organized into three tabs: **Operation**, **Variables**, and **Response**. +We've created a standardized format to maintain a consistent look and feel when documenting example GraphQL queries and mutations. Organize each GraphQL example into three tabs: **Operation**, **Variables**, and **Response**. To create these multi-tabbed GraphQL examples, we're using the built-in Starlight [`` and ``](https://starlight.astro.build/components/tabs/) components. Each of the examples below will show the `` tags. The full example will be wrapped in the `` tag. @@ -38,7 +38,7 @@ Make sure you import the `` and `` components to your MDX file li - Include the query/mutation in a code block - Specify `graphql` as the language for syntax highlighting -- Do not include the query/mutation name in the header +- Exclude the query/mutation name from the header diff --git a/src/content/docs/content/global.mdx b/src/content/docs/content/global.mdx index 6dfec9c..e5787f2 100644 --- a/src/content/docs/content/global.mdx +++ b/src/content/docs/content/global.mdx @@ -4,25 +4,13 @@ title: Global style guide import { Tooltip } from "@interledger/docs-design-system"; -:::caution -This guide is in progress and won’t be complete until we start digging into the other doc sites. -::: - -This guide covers styles that are shared between all doc sites using the Starlight framework. - -Styles should apply to all sites whenever possible; however, there could be a need for site-specific styles. If you can’t find what you’re looking for in this guide, check in a site-specific guide. - -- [Web Monetization](/content/webmonetization) -- [Rafiki](/content/rafiki) -- [Open Payments](/content/openpayments) -- Payment Pointers (not started) -- [Interledger](/content/interledger) (not started) +There are certain styles that we should consistently follow regardless of the doc site we are working on. If you can't find information about a style here, check the site-specific guides linked in the sidenav. ## Rule #1 Break the rules. -Ok, try not to, but the audience’s best interest should always come first. Deviations are OK if they help enhance the clarity of the doc. +Ok, try not to, but the audience's best interest should always come first. Deviations are OK if they help enhance the clarity of the doc. ## Account servicing entity @@ -40,7 +28,7 @@ For buttons with labels/text strings, bold the text that appears in the button. - Click **Revoke public & private key**. ✅ - Click on Revoke public & private key. ❌ -For buttons that are icons (e.g., arrows), describe what should be clicked and don't use bold. Avoid using the word _on_ unless it helps with clarity. For example: +For buttons that are icons (for example, arrows), describe what should be clicked and don't use bold. Avoid using the word _on_ unless it helps with clarity. For example: - Click the arrow to proceed. ✅ - Click on the **arrow** to proceed. ❌ @@ -65,20 +53,20 @@ Add a comma before the conjunction in a list of three or more items. This is kno ## Content reuse -Consider using MDX transclusion, also called MDX partials, if you’re using the same content across multiple page in the same doc project. Transclusion lets you embed MDX documents in other documents. We’ll refer to these embedded documents as partials. +Consider using MDX transclusion, also called MDX partials, if you're using the same content across multiple page in the same doc project. Transclusion lets you embed MDX documents in other documents. We’ll refer to these embedded documents as partials. ### /src/partials -Place MDX files to embed within the `/src/partials` folder. Create the folder if it doesn’t exist. +Place MDX partial files in the `/src/partials` folder. Create the folder if it doesn't exist. ### Partial files -Typically, partials should be used for small chunks of repeating content. If the partial file contains more than a paragraph, there may be a better way to present the information within the doc project. +Typically, partials should be used for small chunks of repeating content. If the partial file contains more than a paragraph, there may be a better way to present the information in the doc project. Note: -- Don’t include frontmatter in your partials file (e.g., `title`). -- Headings within a partials file do not appear in a page’s table of contents. +- Don't include frontmatter in your partials file (for example, `title`). +- Headings in a partials file **will not** appear in a page’s table of contents. - Multiple partial files are supported within a single page. ### Embed a partial @@ -89,9 +77,9 @@ First, import the partial file into the page: import NoPay from "/src/partials/glitchNoPay.mdx"; ``` -Name the partial however you’d like, but without spaces. In the example above, the partial's name is `NoPay`. +Name the partial however you’d like, but without spaces. In the preceding example, the partial's name is `NoPay`. -Using the name you defined, add the partial within the page's content, in the location it should appear: +Using the name you defined, add the partial in the page's content, in the location it should appear: ```mdx This is a paragraph of text. I want the partial content to appear beneath this paragraph. @@ -140,17 +128,17 @@ https://moz.com/learn/seo/alt-text ## Initialisms - Capitalize each letter in an initialism. -- Spell out the entire phrase on first use within a page, then include initialism in parentheses. +- Spell out the entire phrase on first use in a page, then include initialism in parentheses. - In long pages, periodically spell out the entire phrase and include the initialism in parentheses. Long is subjective, use your best judgment. - If you use an initialism for a term that also appears in the glossary, add the initialism to the glossary term. -- Don’t use initialisms for a term that only appears a few times within a page. Few is subjective, use your best judgment. +- Don't use initialisms for a term that only appears a few times in a page. Few is subjective, use your best judgment. ## Lists - Lists should typically contain a minimum of three items. - Use unordered lists (bullets) when item order is unimportant. -- Use ordered (numbered) lists when order is important (e.g., item #1 must be completed before item #2). -- Keep each list as parallel as possible. This list is not a good example. +- Use ordered (numbered) lists when order is important (for example, item #1 must be completed before item #2). +- Keep each list as parallel as possible. This list isn't a good example. - All items start with a noun, or all start with a verb. - All items have ending punctuation, or none do. - All items start with a capital letter, or all start with lowercase. @@ -158,19 +146,19 @@ https://moz.com/learn/seo/alt-text ## Please -We're taking [Google's approach](https://developers.google.com/style/word-list#please): Don’t use please in the normal course of explaining how to use a product, even if you’re explaining a difficult task. +We're taking [Google's approach](https://developers.google.com/style/word-list#please): Don't use "please" in the normal course of explaining how to use a product, even if you're explaining a difficult task. ## See -Previously, we tried to be more inclusive by staying away from using *see* when referring to a link (e.g., *see XYZ for more information*). +Previously, we tried to be more inclusive by staying away from using *see* when referring to a link (for example, *see XYZ for more information*). We've decided that it **is** OK to use *see*. -The W3C uses *see* for link references within their [Accessibility, Usability, and Inclusion](https://www.w3.org/WAI/fundamentals/accessibility-usability-inclusion/) page. Similarly, Google uses it within their [Write inclusive documentation](https://developers.google.com/style/inclusive-documentation) page and their [word list](https://developers.google.com/style/word-list#see) indicates its OK to use when referring to links and cross-references. +The W3C uses *see* for link references in their [Accessibility, Usability, and Inclusion](https://www.w3.org/WAI/fundamentals/accessibility-usability-inclusion/) page. Similarly, Google uses it in their [Write inclusive documentation](https://developers.google.com/style/inclusive-documentation) page and their [word list](https://developers.google.com/style/word-list#see) indicates its OK to use when referring to links and cross-references. ## SHA (secure hash algorithm) -SHA is a common technical term that does not need to be defined before it's first use. +SHA is a common technical term that doesn't need to be defined before it's first use. When an a/an article is needed, use **a**. @@ -179,9 +167,9 @@ When an a/an article is needed, use **a**. ## Sidebar categories -Starlight does not allow a sidebar category, or book, to also be a page. For example, clicking **Shared Component** in this project's sidebar expands/collapses the category without navigating you to a new page. +Starlight doesn't allow a sidebar category, or book, to also be a page. For example, clicking **Shared Component** in this project's sidebar expands/collapses the category without navigating you to a new page. -Since a category cannot be a page, ensure the category's name and pages within the category are titled somewhat differently. +Since a category can't be a page, ensure the category's name and the pages in the category are titled somewhat differently. For example: @@ -193,7 +181,7 @@ For example: ## Sidebar external links -If an external link is required in the sidebar, you can make use of Astro's [sidebar `attrs` property](https://starlight.astro.build/guides/sidebar/#custom-html-attributes) to open the link in a new tab and also add an indicator icon to show the link is external. +If an external link is required in the sidebar, you can use Astro's [sidebar `attrs` property](https://starlight.astro.build/guides/sidebar/#custom-html-attributes) to open the link in a new tab and also add an indicator icon to show the link is external. ```js sidebar: [ @@ -215,7 +203,7 @@ Always spell out test network. Don't abbreviate to testnet. ## Tooltips -The [Tooltip](/shared/tooltip) component allows you to add additional text to a word or phrase. The text appears when you hover your cursor over the question mark. +The [Tooltip](/shared/tooltip) component allows you to add additional text to a word or phrase. The text appears when you hover your cursor over the question mark. - Tooltips should be short. Consider linking to a page or glossary term instead of using the Tooltip component if a tooltip becomes too long. - Longer tooltips that appear at the top of the page might be cut off by the UI. diff --git a/src/content/docs/content/markdown.mdx b/src/content/docs/content/markdown.mdx index 9b356e3..696bb10 100644 --- a/src/content/docs/content/markdown.mdx +++ b/src/content/docs/content/markdown.mdx @@ -6,7 +6,7 @@ sidebar: import { CodeBlock } from "@interledger/docs-design-system"; -The majority of content within the documentation projects are written in Markdown. This page touches on some high-level Markdown topics. For more information on Markdown syntax, see: +Most content in the documentation projects are written in Markdown. This page touches on some high-level Markdown topics. For more information on Markdown syntax, see: * https://starlight.astro.build/guides/authoring-content/ * https://www.markdownguide.org/basic-syntax/ @@ -18,15 +18,13 @@ Frontmatter [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) is Escape a character by adding a backslash before the character. -For example, to show \{client_domain/jwks.json\} in plain text, without Starlight giving you an error, you'd need to format it like this: +For example, to show \{client_domain/jwks.json\} in plain text (as shown here), without Starlight giving you an error, you'd need to format it like this: -`\{client_domain/jwks.json\}` +`\{client_domain/jwks.json}` ## Frontmatter -A `title` is required frontmatter for most files. One scenario in which a title is **not** required is when the file is a [partial](/content/global#content-reuse). - -Check the full list of [frontmatter configuration](https://starlight.astro.build/reference/frontmatter/) for more fun options. +Most files require a `title` in their frontmatter. ```md --- @@ -34,6 +32,10 @@ title: Remember to set this --- ``` +One scenario in which a title is **not** required is when the file is a [partial](/content/global#content-reuse). + +Check the full list of [frontmatter configuration](https://starlight.astro.build/reference/frontmatter/) for more fun options. + ## Images Images in Starlight use [Astro’s built-in optimized asset support](https://docs.astro.build/en/guides/assets/). @@ -50,7 +52,7 @@ You may want to further organise the `img` folder with subfolders if the project ## Headings -Starlight is configured to automatically use your page title as a top-level heading and will include an "Overview" heading at top of each page's table of contents. Starlight does not provide a native way hide "Overview" or change the wording. +Starlight automatically uses your page title as a top-level heading and includes an "Overview" heading at top of each page's table of contents. Starlight doesn't provide a native way hide "Overview" or change the wording. However, we do have the [RemoveOverview](/shared/removeoverview) component. ### Automatic heading anchor links @@ -60,18 +62,16 @@ Level 2 (`

`) and Level 3 (`

`) headings automatically appear in a page's ## Advanced Markdown and MDX configuration -Starlight uses Astro’s Markdown and MDX renderer built on remark and rehype. You can add support for custom syntax and behavior by adding `remarkPlugins` or `rehypePlugins` in your Astro config file. See [“Configuring Markdown and MDX”](https://docs.astro.build/en/guides/markdown-content/#configuring-markdown-and-mdx) in the Astro docs to learn more. +Starlight uses Astro's Markdown and MDX renderer built on remark and rehype. You can add support for custom syntax and behavior by adding `remarkPlugins` or `rehypePlugins` in your Astro config file. See [“Configuring Markdown and MDX”](https://docs.astro.build/en/guides/markdown-content/#configuring-markdown-and-mdx) in the Astro docs to learn more. ### Mermaid diagrams -:::danger -We no longer support mermaid diagrams using the markdown syntax. Instead, use our custom [`Mermaid` component](/shared/mermaid). -::: +Use our custom [`Mermaid` component](/shared/mermaid) to add Mermaid diagrams to the docs. ### Mathjax :::caution -This component requires an extra dependency on [remark-math](https://github.com/remarkjs/remark-math/tree/main) and [rehype-mathjax](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax) and thus is not enabled by default on all projects. Ping the person responsible for documentation architecture if your project doesn't render mathjax properly. +This component requires an extra dependency on [remark-math](https://github.com/remarkjs/remark-math/tree/main) and [rehype-mathjax](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax) and thus isn't enabled by default on all projects. Ping the person responsible for documentation architecture if your project doesn't render mathjax properly. ::: $currencyAmount = \frac{value}{10^{assetScale}}$ diff --git a/src/content/docs/content/openpayments.mdx b/src/content/docs/content/openpayments.mdx index 271c4f3..a5771d9 100644 --- a/src/content/docs/content/openpayments.mdx +++ b/src/content/docs/content/openpayments.mdx @@ -36,10 +36,10 @@ pnpm start ### Proper nouns - Interledger -- Interledger Protocol (can be abbreviated to ILP after first use on a page) -- Open Payments (always spell out, do not abbreviate as OP) +- Interledger Protocol (can abbreviate as ILP after the first use on a page) +- Open Payments (always spell out, don't abbreviate as OP) - Rafiki -- Web Monetization (always spell out, do not abbreviate as WM) +- Web Monetization (always spell out, don't abbreviate as WM) ## Spellings diff --git a/src/content/docs/content/rafiki.mdx b/src/content/docs/content/rafiki.mdx index de4565a..87b0cf1 100644 --- a/src/content/docs/content/rafiki.mdx +++ b/src/content/docs/content/rafiki.mdx @@ -2,13 +2,13 @@ title: Rafiki style guide --- -import { Card } from '@astrojs/starlight/components'; +import { Card, Tabs, TabItem } from '@astrojs/starlight/components'; 1. Your PR title must contain the appropriate prefix (`docs:`). -2. Run the following command within the `/packages/documentation` directory: +2. Run the following command in the `/packages/documentation` directory: ``` npx prettier . --write @@ -69,61 +69,50 @@ This ensures that the GraphQL API docs are included in the site search. ### backend/frontend -When writing about the backend/frontend services and packages in Rafiki, spell as shown. Don't hyphenate or add a space (e.g., back end). FWIW, this is how Microsoft, Google, and Cloudflare treat the terms in their docs. +When writing about the backend/frontend services and packages in Rafiki, spell as shown. Don't hyphenate or add a space (for example, back end). FWIW, this is how Microsoft, Google, and Cloudflare treat the terms in their docs. ## Rafiki-specific styles ### Custom table styles -We've implemented a few different custom table styles specifically for Rafiki docs. These custom styles were developed because we were running into scrolling issues as well as column width issues, primarily when text was formatted as code. +Many of the tables in the Rafiki docs are wider than the main content panel. We've tried to care for this in a few ways. -You can wrap your markdown table in an HTML `
` with one of the following custom table styles: +* We implemented toggles across all doc sites that allows you to collapse/expand the left and right panels. This gives the main content panel a wider viewable area. +* We also added support to the Rafiki docs for custom CSS table styles. -### overflow-table +You can wrap your markdown table in one of the following `div`s. -A long and wide table (vertical and horizontal scrollbars on overflow) with **regular column sizing**. - -```html -
- -| Column Header 1 | Column Header 2 | Column Header 3 | -| --------------- | --------------- | --------------- | -| Content | Content | Content | -| Content | Content | Content | - -
-``` - -### overflow-table wide-column - -A long and wide table (vertical and horizontal scrollbars on overflow) that needs extra wide columns to accommodate text formatted as code. - -`wide-column` sets the minimum width of the table (sum of the total width of all columns) to **60rem**. - -```html -
- -| Column Header 1 | Column Header 2 | Column Header 3 | -| --------------- | --------------- | --------------- | -| Content | Content | Content | -| Content | Content | Content | - -
-``` - -### overflow-table wider-column - -A long and wide table (vertical and horizontal scrollbars on overflow) that needs even larger, extra wide columns to accommodate text formatted as code. - -`wider-column` sets the minimum width of the table (sum of the total width of all columns) to **80rem**. - -```html -
- -| Column Header 1 | Column Header 2 | Column Header 3 | -| --------------- | --------------- | --------------- | -| Content | Content | Content | -| Content | Content | Content | + + + ```html +
+ // Markdown table goes here +
+ ``` + **Example** + ![Regular overflow table example](/img/rafiki-overflow-table.png) + + + The `wide-column` sets the minimum width of the table (sum of the total width of all columns) to 60rem. + + ```html +
+ // Markdown table goes here +
+ ``` + **Example** + + ![Wide overflow table example](/img/rafiki-overflow-wide.png) + + + The `wider-column` sets the minimum width of the table (sum of the total width of all columns) to 80rem. + ```html +
+ // Markdown table goes here +
+ ``` + **Example** -
-``` \ No newline at end of file + ![Wider overflow table example](/img/rafiki-overflow-wider.png) + + diff --git a/src/content/docs/content/sequence-diagrams.mdx b/src/content/docs/content/sequence-diagrams.mdx index 675d9bf..b1e7261 100644 --- a/src/content/docs/content/sequence-diagrams.mdx +++ b/src/content/docs/content/sequence-diagrams.mdx @@ -6,7 +6,7 @@ head: --- :::note -We use an in-house Mermaid component that calls the Mermaid JavaScript API directly. Our component may not support every notation that’s supported by Mermaid itself (e.g., diagonal lines). Additionally, some style decisions may deviate from industry norms due to Mermaid specifically and/or our component’s capabilities and limitations. +We use an in-house Mermaid component that calls the Mermaid JavaScript API directly. Our component may not support every notation that's supported by Mermaid itself (for example, diagonal lines). Additionally, some style decisions may deviate from industry norms due to Mermaid specifically and/or our component's capabilities and limitations. ::: ## Quick reference @@ -43,7 +43,7 @@ You can break a rule if: actor symbol -

A human entity (e.g., sender/recipient of a payment) that interacts with the system by sending or receiving messages or performing an action. An excellent example of when to depict a human is during the Open Payments interactive grant flow.

**Using the actor shape is optional, but if you do choose to use it, only use it with a human entity.**

**The ordering of actors shouldn't be arbitrary if possible.** See Participant.

Capitalization: Sentence case

+

A human entity (for example, sender/recipient of a payment) that interacts with the system by sending or receiving messages or performing an action. An excellent example of when to depict a human is during the Open Payments interactive grant flow.

**Using the actor shape is optional, but if you do choose to use it, only use it with a human entity.**

**The ordering of actors shouldn't be arbitrary if possible.** See Participant.

Capitalization: Sentence case

@@ -67,7 +67,7 @@ You can break a rule if: lifeline symbol -

A vertical line descending from the center-bottom of an actor or participant and represents the existence of the actor/participant over a period of time.

Used as a boundary to show the sequential events that occur to the actor/participant.

+

A vertical line descending from the center-bottom of an actor or participant and represents the existence of the actor/participant over time.

Used as a boundary to show the sequential events that occur to the actor/participant.

@@ -79,7 +79,7 @@ You can break a rule if: group symbol -

Actors/participants can be grouped in vertical boxes.

**Always provide a title, in sentence case, for a group.**

**Don’t use a group to give a diagram a border.**

See the [Color](#colors) section for additional info.

+

Actors/participants can be grouped in vertical boxes.

**Always provide a title, in sentence case, for a group.**

**Don't use a group to give a diagram a border.**

See the [Color](#colors) section for additional info.

@@ -94,27 +94,27 @@ The left-to-right direction of the example arrows below is for illustrative purp | Look | Description | Syntax | | ---- | ----------- | ------ | -| arrow with a solid line and solid arrowhead on the terminating end | A synchronous message being sent (e.g., an API request); the sender must wait for a response before continuing.

**The solid line represents “sending” and the shape of the arrowhead represents sync.**

| `->>` | -| arrow with a dashed line and solid arrowhead on the terminating end | A synchronous message reply (e.g., an API response).

**The dashed line represents a reply and the shape of the arrowhead represents sync.**

| `-->>` | +| arrow with a solid line and solid arrowhead on the terminating end | A synchronous message being sent (for example, an API request); the sender must wait for a response before continuing.

**The solid line represents “sending” and the shape of the arrowhead represents sync.**

| `->>` | +| arrow with a dashed line and solid arrowhead on the terminating end | A synchronous message reply (for example, an API response).

**The dashed line represents a reply and the shape of the arrowhead represents sync.**

| `-->>` | | arrow with a solid line and open arrowhead on the terminating end | An asynchronous message being sent; the sender doesn't wait for a response and immediately continues with the next step.

**The solid line represents “sending” and the shape of the arrowhead represents async.**

| `-)` | | arrow with a dashed line and open arrowhead on the terminating end | An asynchronous message reply.

**The dashed line represents a reply and the shape of the arrowhead represents async.**

| `--)` | -| solid line with solid arrowheads at each end | A bidirectional synchronous message.

**I don’t know when we’d use this.**

Note that it follows the standard syntax patterns for a dashed line and async arrowhead.

| `<<-->>` | +| solid line with solid arrowheads at each end | A bidirectional synchronous message.

**I don't know when we'd use this.**

Note that it follows the standard syntax patterns for a dashed line and async arrowhead.

| `<<-->>` | | solid line with x marking on the terminating end | A stop/destroy message being sent.

**Leads to the deletion of the actor/participant or indicates the actor/participant is no longer needed.**

| `-x` | | dashed line with x marking on the terminating end | A stop/destroy message received.

**Leads to the deletion of the actor/participant or indicates the actor/participant is no longer needed.**

| `--x` | | arrow with a solid line and solid arrowhead on the terminating end pointing back to originating lifeline | A self-message; a recursive call.

**Note that it follows the standard syntax patterns for sending/replying and sync/async.**

| `->>` | ### Lines without arrowheads -Mermaid supports solid and dashed lines without arrowheads. In general, we should save these as a last resort. Think about why you want to include the line, then see if there’s some other way to show the information (e.g., note). +Mermaid supports solid and dashed lines without arrowheads. In general, we should save these as a last resort. Think about why you want to include the line, then see if there's some other way to show the information (for example, note). -One example of an arrowless line being used is in the OP Client Keys diagram: +One example of an arrowless line is in the OP Client Keys diagram: https://openpayments.dev/introduction/client-keys/#sequence-diagram -After Step 1, there’s a line from the client to the resource server to show that Step 1 also “somehow” links to the resource server, since that’s where the keys end up being stored. But this isn’t a particular OP API call. It’s just something that an ASE would do (upload the keys to be available from the RS). In other words, a 🪄step. +After Step 1, there's a line from the client to the resource server to show that Step 1 also “somehow” links to the resource server, since that's where the keys are stored. But this isn't a particular OP API call. It's just something that an ASE would do (upload the keys to be available from the RS). In other words, a 🪄step. ### Adding text to messages -**Every message should have descriptive text even if you think it’s obvious what the messages represent.** It doesn’t need to be a novel. +**Every message should have descriptive text even if you think it's obvious what the messages represent.** It doesn't need to be a novel. A simple example... @@ -122,7 +122,7 @@ A simple example... | ---- | --- | | | | -Depending on how wide the sequence diagram is, or the information you’re conveying, **you might need to add line breaks to text**. This will make the diagram more narrow (so it fits better within Starlight’s content frame) and increase the font size, making the diagram more readable. +Depending on how wide the sequence diagram is, or the information you're conveying, **you might need to add line breaks to text**. This will make the diagram more narrow (so it fits better in Starlight's content frame) and increase the font size, making the diagram more readable. Compare: @@ -132,7 +132,7 @@ Compare: ### Formatting code -Mermaid does not allow you to format text using a code-like font. +Mermaid doesn't allow you to format text using a code-like font. @@ -140,9 +140,9 @@ If you think the text needs to stand out in some way, you could use: * Single or double quotes * Square or curly brackets * Line breaks -* A combination of what’s above +* A combination of what's above -**Instead of prescribing specific formatting, the most important thing is to remain as consistent as possible both within a single message and a single diagram.** +**Instead of prescribing specific formatting, the most important thing is to remain as consistent as possible both in a single message and a single diagram.** ### Formatting REST APIs @@ -157,7 +157,7 @@ What follows the method is up to you. Any of these are OK: * GET wallet address url * POST make initial grant request * POST /incoming-payments -* GET \{client_domain/jwks.json\} +* GET \{client_domain/jwks.json} #### Response codes @@ -170,9 +170,9 @@ If including the response number, include the number at the beginning of the des #### API names -Rafiki currently has two GraphQL APIs: the Backend Admin API and the Auth Admin API. Since they’re both “admin” APIs, it’s important that we write out the API name completely, so readers know which API we’re discussing. Capitalize each word. +Rafiki currently has two GraphQL APIs: the Backend Admin API and the Auth Admin API. Since they're both “admin” APIs, it's important that we write out the API name completely, so readers know which API we're discussing. Capitalize each word. -**We don’t have many (any?) sequence diagrams in the Rafiki docs outside of the webhook events page. I don’t know if there are any instances where we’d include the API name but not include a specific mutation.** +**We don't have many (any?) sequence diagrams in the Rafiki docs outside the webhook events page. I don't know if there are any instances where we'd include the API name but not include a specific mutation.** #### Mutations @@ -188,7 +188,7 @@ This example shows the previous points applied to the response. This way you can ## Notes -Mermaid allows you to place notes to the right of, the left of, and over an actor/participant. They can also span across multiple actors/participants. +Mermaid allows you to place notes to the right of, the left of, and over an actor/participant. They can also span multiple actors/participants. Notes have a yellow background that you can't change. @@ -231,7 +231,7 @@ An interaction operator is a container that groups interaction fragments. Contai Titles are optional **but strongly recommended**. Titles appear centered at the top and enclosed in brackets. -Operators should be used intentionally and not as a way to draw a box around something. +Use operators intentionally and not as a way to draw a box around something. loop operator symbol @@ -244,7 +244,7 @@ Some, if not all, operators can be nested. | `loop` | Loop

A basic repeating interaction.

| | `par` | Parallel

Shows actions are happening in parallel; shows interactions running concurrently with each other.

| | `critical` | Critical region

Indicates that the fragment can only have one thread that it runs at any time. The fragment must complete before another thread can run. Shows actions that must happen automatically with conditional handling of circumstances.

| -| `break` | Break

Indicates a stop of the sequence within the flow, usually to model exceptions.

The sequence breaks/stops/doesn't perform any of the remaining sequence and does what’s defined in the operator instead.

Breaks only cause the exiting of an enclosed interaction’s sequence and not necessarily the entire sequence depicted in the diagram. In cases where a break combination is part of an alt or loop, then only the alt or loop is exited.

| +| `break` | Break

Indicates a stop of the sequence in the flow, usually to model exceptions.

The sequence breaks/stops/doesn't perform any of the remaining sequence and does what's defined in the operator instead.

Breaks only cause the exiting of an enclosed interaction's sequence and not necessarily the entire sequence depicted in the diagram. In cases where a break combination is part of an alt or loop, then only the alt or loop is exited.

| ## Colors @@ -258,13 +258,13 @@ Also remember that using spanning Notes is a way to call out and section off inf Best practices when it comes to using color: -* **Use color sparingly.** Think about why you want to use colors. Groups have transparent backgrounds by default. The border around the group is probably enough to call attention to the contents within the group. -* **Use color consistently** within a single diagram. +* **Use color sparingly.** Think about why you want to use colors. Groups have transparent backgrounds by default. The border around the group is probably enough to call attention to the contents in the group. +* **Use color consistently** in a single diagram. * **Check the contrast** between color(s) and text. Make sure the text is still legible. * **Consider color blindness when selecting colors–especially if they overlap.** Difficulties distinguishing between red and green is the most common type of color blindness. [Coloring for Colorblindness](https://davidmathlogic.com/colorblind/) is one of many tools that can help you see how colors may appear to others.

The following example color palette uses a few ILF-flavored colors as the *True* colors and shows how these colors will appear to someone with colorblindness (depending on the type).

-* **Check the diagram on multiple screens** if you have them (e.g., laptop/desktop monitor). A light color on one monitor, for example, might look significantly darker on another. +* **Check the diagram on multiple screens** if you have them (for example, laptop/desktop monitor). A light color on one monitor, for example, might look significantly darker on another. * **Check the diagram in light and dark mode.** If you add color to a diagram, check that the diagram is legible in light and dark mode. *It probably will be* because I think Mermaid keeps the background white. It’s still a good habit to get into. Even if a diagram is legible in dark mode, for example, the contrast between the dark UI, the white diagram background, and a light background highlight color might be a bit harsh on the eyes. -Regardless of how nice you think the following diagram looks, the use of colors checks *most* of the boxes. I’d argue that the purple is pushing it when it comes to text contrast/legibility. +Regardless of how nice you think the following diagram looks, the use of colors checks *most* of the boxes. I'd argue that the purple is pushing it when it comes to text contrast/legibility. diagram using a purple group overtop of a blue group and a yellow note overtop the blue group diff --git a/src/content/docs/content/starlight.mdx b/src/content/docs/content/starlight.mdx index c6d5045..097617f 100644 --- a/src/content/docs/content/starlight.mdx +++ b/src/content/docs/content/starlight.mdx @@ -128,4 +128,4 @@ head: --- ``` -Starlight can get a little testy when it comes to indentations. If you're getting errors, copy the code block above and update it as needed. +Starlight can get a little testy when it comes to indentations. If you're getting errors, copy the preceding code block and update it as needed. diff --git a/src/content/docs/content/webmonetization.mdx b/src/content/docs/content/webmonetization.mdx index 803245a..04a193a 100644 --- a/src/content/docs/content/webmonetization.mdx +++ b/src/content/docs/content/webmonetization.mdx @@ -26,9 +26,9 @@ bun run start - Interledger - Interledger Protocol (can be abbreviated to ILP after first use on a page) -- Open Payments (always spell out, do not abbreviate as OP) +- Open Payments (always spell out, don't abbreviate as OP) - Rafiki -- Web Monetization (always spell out, do not abbreviate as WM) +- Web Monetization (always spell out, don't abbreviate as WM) ## Account servicing entity @@ -42,28 +42,10 @@ Payment pointer and wallet address are not synonyms. Refer to both when appropri ### monetization -We are a US-based 501(c)(3). Use the US spelling of monetization, with a z rather than an s. Z is also used in the URL and the spec. +We're a US-based 501(c)(3). Use the US spelling of monetization, with a z rather than an s. Z is also used in the URL and the spec. ### web monetize If we follow standard US grammar rules, then web monetize and its other forms (e.g., web monetized) should probably be hyphenated. In the past, I found that the term was used so frequently that the hyphens were visually distracting. I made a style decision to drop the hyphens. We can revisit this decision. - -## Web Monetization-specific styles - -### Remove overview - -The Web Monetization project gives us the ability to hide the Overview heading from a page's table of contents. This is handy on, for example, the Glossary page. - -On Nov. 21, 2024, Melissa requested this functionality be added to all of our doc projects: https://github.com/interledger/docs-design-system/issues/27 - -All you need to do is add the page that you want the Overview heading removed from to the `removeOverview` portion of `components/docs/PageSidebar.astro`. - -``` -const removeOverview = [ - 'docs/resources/glossary', -] -``` - -The magic happens because of `components/docs/shared/removeoverview.mdx`, but you don't need to make any changes to this file. \ No newline at end of file diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 404849a..325837a 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -14,7 +14,7 @@ bun run start ``` -Interledger uses [Starlight](https://starlight.astro.build/getting-started/) (powered by [Astro](https://docs.astro.build/en/getting-started/)) for all its documentation sites. In order to keep our visual styling consistent across our numerous documentation sites, we have packaged our styles and shared components in an [npm package](https://www.npmjs.com/package/@interledger/docs-design-system). +Interledger uses [Starlight](https://starlight.astro.build/getting-started/) (powered by [Astro](https://docs.astro.build/en/getting-started/)) for all its documentation sites. To keep our visual styling consistent across our numerous documentation sites, we have packaged our styles and shared components in an [npm package](https://www.npmjs.com/package/@interledger/docs-design-system). ```bash npm i @interledger/docs-design-system @@ -22,19 +22,27 @@ npm i @interledger/docs-design-system Feel free to install with the package manager of your choice. -Because we are using Starlight, content has to be authored in Markdown or MDX. +Because we're using Starlight, content must be authored in Markdown or MDX. :::caution[Best practice] Create new pages as MDX files. ::: -Components can be written in JSX, and imported into MDX files. Documentation pages cannot be `.astro` files. You are free to create Astro pages in the `/pages` folder though. +Components can be written in JSX, and imported into MDX files. Documentation pages can't be `.astro` files. You are free to create Astro pages in the `/pages` folder though. ## Visual themes -We have two visual themes for now, teal and orange. These themes are built on top of Starlight's defaults and overrides some of the out-of-the-box styling. They are just CSS files, so use them with the path to `node_modules`. Unfortunately, we did not have enough braincells to figure out how to make it prettier than that. To use them in the `astro.config.mjs`: +Visual themes change the default way the Starlight UI appears to our audience by introducing new styling and overriding some native styling. Each theme is a CSS file, used with the path to `node_modules`. -```js +If you are using them in an Astro layout file, then the import must look like this: + +```jsx wrap +import '/node_modules/@interledger/docs-design-system/src/styles/teal-theme +``` + +To use them in the `astro.config.mjs`: + +```js wrap export default defineConfig({ integrations: [ starlight({ @@ -47,18 +55,14 @@ export default defineConfig({ }); ``` -If you are using them in an Astro layout file, then the import must look like this: - -```jsx -import '/node_modules/@interledger/docs-design-system/src/styles/teal-theme -``` +When we first rolled out Starlight, we used different themes (specifically colors) across doc sets. That's why you might see `orange-theme`, for example. Now we use the teal theme pretty much across the board to promote consistency between doc sets. We also use `ilf-docs`. If we need something for a specific doc set, there could be an additional CSS file. ## Components Starlight provides some built-in components that are commonly used for documentation sites. Refer to the [Starlight documentation](https://starlight.astro.build/guides/components#built-in-components) for detailed information on how to use them. :::note -The Starlight team releases new components from time to time. If you find a component in their doc that doesn't work with an Interledger doc site, we may need to upgrade our version of Starlight. +The Starlight team releases new components from time to time. If you find a component in their doc that doesn't work with our sites, we may need to upgrade our version of Starlight. ::: We also have a number of documentation-specific helper components that can be imported and used where necessary. You can refer to the individual pages in the sidebar to see them in action. @@ -69,20 +73,20 @@ If you are using multiple shared components on a single page, you can import the import { CodeBlock, LinkOut } from "@interledger/docs-design-system"; ``` -For more information about importing things in Javascript, refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). +For more information about importing things in JavaScript, refer to [import on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). ## Docs site building -Each documentation site will inevitably have its own unique requirements. One may have custom pages and components which do not apply to any of the other documentation sites. As such, we have a general pattern for handling this. For CSS, our shared styles are all in the [docs-design-system](https://www.npmjs.com/package/@interledger/docs-design-system) npm package. If the documentation site you're building is simple enough, you might not even need more than what was [outlined above](#visual-themes). +Each documentation site inevitably has its own unique requirements. One site could have custom pages and components which don't apply to any of the other documentation sites. As such, we have a general pattern for handling this. For CSS, our shared styles are all in the [docs-design-system](https://www.npmjs.com/package/@interledger/docs-design-system) npm package. If the documentation site you're building is simple enough, you might not even need more than what was [outlined above](#visual-themes). -In the event there are certain components or elements that only apply to specific documentation sites, we will need to write additional styles. These will go into the `/src/styles` folder, and use the project name as the file name, e.g. `rafiki.css`. +In the event there are certain components or elements that only apply to specific documentation sites, we'll need to write additional styles. Put the styles into the `/src/styles` folder, and use the project name as the filename, e.g. `rafiki.css`. -```js +```js wrap export default defineConfig({ integrations: [ starlight({ customCss: [ - "./node_modules/@interledger/docs-design-system/src/styles/orange-theme.css", + "./node_modules/@interledger/docs-design-system/src/styles/teal-theme.css", "./node_modules/@interledger/docs-design-system/src/styles/ilf-docs.css", "./src/styles/rafiki.css", ], @@ -93,9 +97,9 @@ export default defineConfig({ Some of our sites also have custom pages, like [Web Monetization](https://webmonetization.org) or the [Interledger Developer Portal](https://interledger.org/developers). -These are pages that live outside the Starlight integration ecosystem, and do not come with any styles nor structure. As such, you will also need to create a layout which forms the base structure of a standard web page, down to the `` and `` elements. +These are pages that live outside the Starlight integration ecosystem, and don't come with any styles or structure. As such, you will also need to create a layout which forms the base structure of a standard web page, down to the `` and `` elements. -You can create multiple layout files if there are different types of pages required, and all these layout files will go into the `/src/layouts` folder, while the pages themselves will go into the `/src/pages` folder. It is highly recommended you read the [Astro documentation](https://docs.astro.build/en/core-concepts/astro-pages/) to familiarise yourself with how this all works. +You can create multiple layout files if there are different types of pages required. All these layout files go into the `/src/layouts` folder, while the pages themselves go into the `/src/pages` folder. It's highly recommended you read the [Astro documentation](https://docs.astro.build/en/core-concepts/astro-pages/) to familiarise yourself with how this all works. This is a very generic starter sample layout that you can work off from: @@ -168,4 +172,4 @@ import SocialIcons from "@astrojs/starlight/components/SocialIcons.astro"; ``` - \ No newline at end of file + diff --git a/src/content/docs/shared/disclosure.mdx b/src/content/docs/shared/disclosure.mdx index 83e3f0e..135b226 100644 --- a/src/content/docs/shared/disclosure.mdx +++ b/src/content/docs/shared/disclosure.mdx @@ -11,8 +11,6 @@ In October 2024, we decided to move away from using the Disclosure component in This component allows you to show/hide content within a collapsible container. -The `client:load` attribute is required for the component to work because the component uses Javascript for interactivity. - To use the component, the page must be in `.mdx` format. Change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. ## Usage @@ -26,7 +24,7 @@ import { Disclosure } from "@interledger/docs-design-system"; Use the `` component within your content like so: ```jsx - + ``` @@ -40,7 +38,7 @@ You can nest the Disclosure component with the built-in Starlight [``](htt ````jsx import { Tabs, TabItem } from '@astrojs/starlight/components' - + ```bash @@ -71,13 +69,13 @@ import { Tabs, TabItem } from '@astrojs/starlight/components' ### Simple hidden text - + Just some text that does not need to be seen on first load ### Combination of disclosures, tabs, and code blocks - + ```bash @@ -101,7 +99,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components' - + 1. Open Terminal. 2. Change the current working directory to where you want to clone repo. diff --git a/src/content/docs/shared/tooltip.mdx b/src/content/docs/shared/tooltip.mdx index 5c74a85..3f59da5 100644 --- a/src/content/docs/shared/tooltip.mdx +++ b/src/content/docs/shared/tooltip.mdx @@ -13,8 +13,6 @@ This component allows you add a small, stylized question mark element that, when The component is built to be accessible in accordance to the guidance from [WAI Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/). -The `client:load` attribute is required for the component to work because it uses Javascript for interactivity. - To use the component, the page must be in `.mdx` format. Change the format from `.md` to `.mdx` if necessary. All your existing markdown will still be supported without issue. ## Usage @@ -28,7 +26,7 @@ import { Tooltip } from "@interledger/docs-design-system"; The component can be used within your content in a few ways. Technically, you can add the following in the location you want the question mark element to appear: ```jsx - + ``` However, a better practice is to wrap the word or phrase that the tooltip pertains to. @@ -36,19 +34,19 @@ However, a better practice is to wrap the word or phrase that the tooltip pertai In the following example, the question mark element will appear after the word _this_. ```jsx -Define this term. +Define this term. ``` In this next example, the question mark element will appear between the word _to_ and the ending punctuation. ```jsx title="Example 2" - + This is the content that the tooltip relates to . ``` ## Working examples -This is a sentence that has many technical terms. A tooltip could help with explaining a term when hovered over. Don't make them too long though. +This is a sentence that has many technical terms. A tooltip could help with explaining a term when hovered over. Don't make them too long though. -This example contains a tooltip along with a link to see Bubees. \ No newline at end of file +This example contains a tooltip along with a link to see Bubees. \ No newline at end of file diff --git a/vale/config/vocabularies/ilf/accept.txt b/vale/config/vocabularies/ilf/accept.txt index c83ada2..d0c3cda 100644 --- a/vale/config/vocabularies/ilf/accept.txt +++ b/vale/config/vocabularies/ilf/accept.txt @@ -1,9 +1,11 @@ allowlist amountSent APIs +API's ASEs Astro blocklist +[Cc]onfig CSPs [Dd]iv Fedwire @@ -11,6 +13,7 @@ Fedwire GateHub [Hh]ackathon href +HTTP [Ii]frame incomingPayment [Ii]nterledger @@ -30,4 +33,6 @@ repo [Rr]afiki SDKs Shiki +[Ss]ubfolder [Tt]estnet +[Tt]ooltip diff --git a/vale/docStyles/Acronyms.yml b/vale/docStyles/Acronyms.yml index 1fb246e..d6ba548 100644 --- a/vale/docStyles/Acronyms.yml +++ b/vale/docStyles/Acronyms.yml @@ -7,8 +7,9 @@ first: '\b([A-Z]{3,5})\b' second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' # ... with the exception of these: exceptions: - - API - ACH + - API + - ASCII - ASE - ASP - CAD @@ -27,6 +28,7 @@ exceptions: - GCC - GDB - GET + - GNAP - GPU - GTK - GUI @@ -40,6 +42,7 @@ exceptions: - JSX - LESS - LLDB + - MDX - MXN - NET - NOTE @@ -53,6 +56,7 @@ exceptions: - PNPM - POST - RAM + - REST - REPL - RSA - RSS @@ -69,6 +73,7 @@ exceptions: - TCP - TODO - TSX + - UCT - URI - URL - USA diff --git a/vale/docStyles/GeneralURL.yml b/vale/docStyles/GeneralURL.yml deleted file mode 100644 index 7a4091a..0000000 --- a/vale/docStyles/GeneralURL.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: existence -message: "For a general audience, use 'address' rather than 'URL'." -level: suggestion -action: - name: replace - params: - - URL - - address -tokens: - - URL diff --git a/vale/docStyles/Passive.yml b/vale/docStyles/Passive.yml deleted file mode 100644 index ad5899f..0000000 --- a/vale/docStyles/Passive.yml +++ /dev/null @@ -1,183 +0,0 @@ -extends: existence -message: "In general, use active voice instead of passive voice ('%s')." -ignorecase: true -level: suggestion -raw: - - \b(am|are|were|being|is|been|was|be)\b\s* -tokens: - - '[\w]+ed' - - awoken - - beat - - become - - been - - begun - - bent - - beset - - bet - - bid - - bidden - - bitten - - bled - - blown - - born - - bought - - bound - - bred - - broadcast - - broken - - brought - - built - - burnt - - burst - - cast - - caught - - chosen - - clung - - come - - cost - - crept - - cut - - dealt - - dived - - done - - drawn - - dreamt - - driven - - drunk - - dug - - eaten - - fallen - - fed - - felt - - fit - - fled - - flown - - flung - - forbidden - - foregone - - forgiven - - forgotten - - forsaken - - fought - - found - - frozen - - given - - gone - - gotten - - ground - - grown - - heard - - held - - hidden - - hit - - hung - - hurt - - kept - - knelt - - knit - - known - - laid - - lain - - leapt - - learnt - - led - - left - - lent - - let - - lighted - - lost - - made - - meant - - met - - misspelt - - mistaken - - mown - - overcome - - overdone - - overtaken - - overthrown - - paid - - pled - - proven - - put - - quit - - read - - rid - - ridden - - risen - - run - - rung - - said - - sat - - sawn - - seen - - sent - - set - - sewn - - shaken - - shaven - - shed - - shod - - shone - - shorn - - shot - - shown - - shrunk - - shut - - slain - - slept - - slid - - slit - - slung - - smitten - - sold - - sought - - sown - - sped - - spent - - spilt - - spit - - split - - spoken - - spread - - sprung - - spun - - stolen - - stood - - stridden - - striven - - struck - - strung - - stuck - - stung - - stunk - - sung - - sunk - - swept - - swollen - - sworn - - swum - - swung - - taken - - taught - - thought - - thrived - - thrown - - thrust - - told - - torn - - trodden - - understood - - upheld - - upset - - wed - - wept - - withheld - - withstood - - woken - - won - - worn - - wound - - woven - - written - - wrung diff --git a/vale/docStyles/Terms.yml b/vale/docStyles/Terms.yml index 00cfaee..8e2c766 100644 --- a/vale/docStyles/Terms.yml +++ b/vale/docStyles/Terms.yml @@ -1,5 +1,5 @@ extends: substitution -message: "Prefer '%s' over '%s'." +message: "Consider '%s' instead of '%s'." level: suggestion ignorecase: true action: @@ -42,7 +42,6 @@ swap: file name: filename functionality: capability|feature grayed-out: unavailable - HTTPs: HTTPS k8s: Kubernetes keypress: keystroke monetisation: monetization @@ -54,6 +53,6 @@ swap: sign into: sign in to sign-?on: single sign-on tablet: device - url: URL vs\.: versus - World Wide Web: web \ No newline at end of file + World Wide Web: web + \ No newline at end of file