Skip to content
GitHub

Global style guide

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.

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.

Account servicing entity

We’re currently treating account servicing entity as an improper/common noun, meaning each letter should be in lowercase. ASE is an approved initialism.

APIs/API’s

  • Plural - APIs
  • Possessive - API’s

Buttons

For buttons with labels/text strings, bold the text that appears in the button. If you’re instructing someone to click the button, don’t use the word on. For example:

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

  • Click the arrow to proceed. ✅
  • Click on the arrow to proceed. ❌

Capitalization

Headings, subheadings, and page titles

Use sentence case for headings, subheadings, and page titles unless a word/term is a proper noun or has a specific capitalization (e.g., “amountSent”, not “AmountSent” to represent a property).

Initialisms

Capitalize each letter in an initialism. For example, ASE for account servicing entity.

Commas

Add a comma before the conjunction in a list of three or more items. This is known as an Oxford, or serial, comma.

Do this…Instead of this…
Web Monetization provides an open, native, and efficient way to compensate creators.Web Monetization provides an open, native and efficient way to compensate creators.

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.

/src/partials

Place MDX files to embed within 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.

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.
  • Multiple partial files are supported within a single page.

Embed a partial

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.

Using the name you defined, add the partial within the page’s content, in the location it should appear:

This is a paragraph of text. I want the partial content to appear beneath this paragraph.


<NoPay />

That’s it!

Digital wallet vs account

The term digital wallet can be interpreted a number of ways and we want to be as unambiguous as possible. Be aware of the context in which you’re using the term. Think about whether account or Open Payments-enabled account would be more accurate than digital wallet.

Doc file extensions (MD/MDX)

Create new doc files in MDX unless you have a good reason not to.

Example URLs, including wallet addresses

Use example.com and subdomain.example.com in example URLs.

  • wallet.example.com
  • wallet.example.com/alice

Reference: https://en.wikipedia.org/wiki/Example.com

Headings and subheadings

Best practices

  • Keep headings short.
  • Avoid headings that ask questions when possible (unless you’re crafting an FAQ).
  • When using a gerund (verb + -ing) as the first word in a heading, consider whether a verb would be more direct. For example, Linking to a WM agent vs. Link to a WM agent.

Overviews

Starlight automatically sets the first heading on a page to “Overview”, even if the markdown file has an H1 or H2 defined.

Images

Alt text

Include alt text for images.
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.
  • 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.

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.
    • 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: 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).

We’ve decided that it is OK to use see.

The W3C uses see for link references within their Accessibility, Usability, and Inclusion page. Similarly, Google uses it within their Write inclusive documentation page and their word list 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.

When an a/an article is needed, use a.

  • A SHA-256 hash of the interaction is sent in the response. ✅
  • An SHA-256 has of the interaction is sent in the response. ❌

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.

Since a category cannot be a page, ensure the category’s name and pages within the category are titled somewhat differently.

For example:

  • Intro to Web Monetization
  • References
    • Web Monetization API
    • Monetization events
      • MonetizationEvent

If an external link is required in the sidebar, you can make use of Astro’s sidebar attrs property to open the link in a new tab and also add an indicator icon to show the link is external.

sidebar: [
  {
    label: 'Types of Dinosaurs',
    link: 'https://www.amnh.org/dinosaurs/types-of-dinosaurs',
    attrs: {
      target: '_blank',
      rel: 'noopener noreferrer',
      'data-icon': 'external'
    },
  },
],

Test network

Always spell out test network. Don’t abbreviate to testnet.

Tooltips

The 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 This is an example 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.