docs: housekeeping

src/content/docs/classes/details.mdx

@@ -8,7 +8,7 @@ The `<details>` 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 `<details>` 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 `<details>` 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
 

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 [`<Tabs>` and `<TabItem>`](https://starlight.astro.build/components/tabs/) components. Each of the examples below will show the `<TabItem>` tags. The full example will be wrapped in the `<Tabs>` tag.
 
@@ -38,7 +38,7 @@ Make sure you import the `<Tabs>` and `<TabItem>` 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
 
 <CodeBlock title="Operation tab markdown format">
 

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,37 +128,37 @@ 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.
 - If a list is introduced by a full sentence, end the sentence with the proper punctuation. If introduced with a sentence fragment, end with a colon.
 
 ## 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 <Tooltip content='This is an example tooltip' client:load><span>question mark</span></Tooltip>.
+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 <Tooltip content='This is an example tooltip'><span>question mark</span></Tooltip>.
 
 - 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.

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,22 +18,24 @@ 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
 ---
 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 (`<h2>`) and Level 3 (`<h3>`) 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}}$

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