Last updated

Contribute Documentation

Thanks for considering a contribution to the XRP Ledger Developer Portal!

We're thrilled you're interested and your help is greatly appreciated. Contributing is a great way to learn about the XRP Ledger (XRPL).

We are happy to review your pull requests. To make the process as smooth as possible, please read this document and follow the stated guidelines.

About This Site

The XRPL Dev Portal provides comprehensive documentation of the the XRP Ledger, including sample code and other information for developers to start building.

The official source repository for the site is at https://github.com/XRPLF/xrpl-dev-portal. Contributions are copyright their respective contributors, but must be provided under the MIT LICENSE.

Repository Layout

  • _api-examples/ - Sample API requests and responses, especially ones used in the documentation.
  • _code-samples/ - Code samples used or referenced by the documentation. Where possible, these are fully functional / executable scripts.
  • @i18n - Translations into languages other than English. Currently, only Japanese.
  • @theme - Overrides and custom components used in Markdoc contents as well as custom React pages.
  • about/ - Source files for the About section's pages.
  • blog/ - Source files for the XRPL Dev Blog.
  • community/ - Source files for the Community section's pages.
  • docs/ - Source files used to build the documentation. Mostly in Markdown.
    • docs/_snippets/ - Reusable pieces of text used in the documentation.
    • docs/img/ - Diagrams and other images used in the documentation.
    • docs/img/_sources/ - Source files for images used in the documentation, where available.
  • locale/ - DEPRECATED Old localization files.
  • resources/ - Source files for the Resources section's pages.
  • shared/ - Configuration files for some dependencies like CodeMirror.
  • static/ - Static files used by the site's templates and theme.
  • styles/ - SCSS source files for custom CSS.
  • redirects.yaml - Definitions of redirects from old site URLs to current paths.
  • redocly.yaml - Main config file for the site.
  • sidebars.yaml - Defines sidebars for the Documentation and Resources sections.
  • top-nav.yaml - Defines the main top nav elements.

Requirements for a Successful Pull Request

Before being considered for review or merging, each pull request must:

Redocly Setup

The portal is built using Redocly Realm, which is currently in closed beta. Installing it for local development requires Node.js (version 20 recommended) and NPM.

You can install Realm and other necessary dependencies using NPM from the repository top:

npm i

Building the Site

After you've installed dependencies, you can start a local dev server with:

npm run start

You can view the preview in a web browser, probably at http://localhost:4000/

Config Formatting

Realm uses YAML config files to generate navigation elements in the site, including header, footer, sidebars, and breadcrumbs.

If you add a new page, you should add it to the appropriate sidebars.yaml file. There is one sidebars file for the documentation and one for the blog. Here's an example of an entry for a page with no nested children:

- page: concepts/consensus-protocol/index.md

The Markdown file for a page should start with a frontmatter stanza.

Conventions

Use the following conventions when creating a page:

  • Filenames (aside from index.md) should generally match the title of the page, including words like "and" and "the", but should be in all lowercase with hyphens instead of spaces and punctuation. For example, cash-a-check-for-an-exact-amount.md. If you change the title of a page, change the filename too. (If it has already been published at another URL, leave a redirect from the old URL.)
    • The page within a category should be in a subfolder named for that category but can be less verbose (especially if the page title includes words also in the parent directories), should have the filename index.md, and a title that is similar to the folder name. For example, the "Protocol Reference" index page is at references/protocol/index.md.
  • Always start a page with a h1 header.
  • Don't link to the top h1 anchor of a page, link to the page itself without an anchor. This helps prevent broken links in translation. It's OK to link to later headers.
  • Don't use any formatting (like italics or code font) in the title of the page.
  • Don't hard-wrap text in Markdown files.
  • For code samples, try to keep lines no longer than 80 columns wide.
  • When in doubt, follow Ciro Santilli's Markdown Style Guide (Writability Profile).
  • Don't use tab characters for indentation in Markdown or code samples. Use 4 spaces per indent, except in JavaScript code samples, which should use 2 spaces per indent.
  • Make sure text files end in a newline character. (Some text editors handle this automatically.) Encode files in UTF-8 with no byte-order mark.

Terminology

Use the following words and phrases as described:

TermTerms to AvoidNotes
API, APIsAPI's, RPCApplication Programming Interface, a set of functions and definitions for software to connect to other software.
core server, core XRP Ledger serverrippledThe rippled name is probably going to be retired in the near future, so it's better to refer to it by the more generic name. When necessary, refer to rippled in all lowercase and code font. (It's pronounced "ripple dee", and the "d" stands for "daemon" per UNIX tradition.)
financial institutionbank, FI, PSP (payment services provider)This term encompasses a wider range of businesses than just bank or other terms and does not rely on an understanding of industry jargon.
ledger entryledger object, nodeA single object inside the state data of the XRP Ledger. The term ledger object could refer to one of these or to the whole ledger. The term node was sometimes used for this case because the ledger's state data can be envisioned as a graph, but this is confusing because node has other uses.
liquidity providermarket makerA business or individual who offers to exchange between two currencies or assets, often deriving income from the price differential between trades. The term market maker has a specific legal definition in some jurisdictions and may not apply in all the same circumstances.
malicious actorhackerA person, organization, or even an automated tool which might attempt to acquire secrets, break encryption, deny service, or otherwise attack a secure resource.
a NFTan NFTA NFT object in the XRP Ledger tracks or represents a non-fungible token. Pronounced "nifty" and written a NFT rather than an NFT.
PostgreSQLPostgresA specific brand of relational database software. Always use the full name, not an informal short version.
order bookorderbook, offer bookA collection of trade orders waiting to be matched and executed, typically sorted by exchange rate. Use two words.
servernodeA server is software and/or hardware, especially the ones that connect to the XRP Ledger peer-to-peer network. The term node is sometimes used for this purpose but is also overloaded with other meanings including entries in a graph and Node.js, a JavaScript interpreter.
stablecoin issuergatewayAn issuer is the organization that issues a token in the XRP Ledger. A stablecoin is a token where the issuer promises that it is fully backed by some outside asset (such as fiat currency), with the stablecoin issuer providing deposit and withdraw operations to convert between the two (possibly for a fee). Previously the term gateway was used (especially by Ripple, the company) to describe this use case, but the rest of the industry adopted stablecoin issuer instead.
transaction costtransaction feeThe amount of XRP burnt to send a transaction in the XRP Ledger. Even though this is specified in the Fee field of transactions, the term fee implies that the money is paid to someone, so cost is preferable.
trust linetrustlineUse two words. A trust line is a relationship between two accounts in the XRP Ledger that tracks a balance of tokens between those accounts.
tokensIOUs, issuances, issues, issued currenciesA token in the XRP ledger may not represent money owed outside of the ledger as the name IOU implies. Specify fungible tokens if necessary to distinguish from non-fungible tokens.
walletwalletDepending on the context, wallet could refer to hardware, software, a cryptographic key pair, or an online service. Be sure to provide enough context that the meaning is clear, or use an alternative such as key pair or client application.
WebSocketweb socket, WebsocketsA two way protocol for communication on the web. Always singular and in CamelCase.
XRPXRPs, ripplesThe native digital asset, or cryptocurrency, of the XRP Ledger. XRP is not a token.
the XRP LedgerXRP Ledger (no the), Ripple, Ripple Network, RCLThe XRP Ledger was called the Ripple network and the Ripple Consensus Ledger or RCL at various times in the past. These names were confusing and have been retired because of their similarity to the name of the company, Ripple (formerly Ripple Labs) which develops the reference implementation of the core server.
XRPLXRPLShort for XRP Ledger. As much as possible, spell out XRP Ledger instead; XRPL is cryptic and looks like it could be a typo for XRP.

Frontmatter Fields

Note: The details of Realm's frontmatter specification are not fully documented. Update this with a link when Realm exits closed beta.

Frontmatter for Markdown files can include details such as the following:

---
metadata:
  indexPage: true # Add this if you want the page to contain an auto-generated list of its child pages.
seo:
  description: rippled is the core peer-to-peer server that manages the XRP Ledger. This section covers concepts that help you learn the "what" and "why" behind fundamental aspects of the rippled server.
---

Some pages in the site have leftover metadata from the previous (Dactyl) toolchain, such as html, parent, or targets fields. These fields have no effect and can be omitted from new pages.

Markdoc Components

The files are processed with Markdoc, which means they can contain special tags in {% ... %} syntax. In addition to Redocly's built-in tags, this repository has some custom tags defined in /@theme/markdoc/.

To make it easier to link to pages that are commonly cited, you can add a {% raw-partial file="/docs/_snippets/common-links.md /%} tag to a Markdown file, and then use centrally-defined reference-style links such as [account_info method][] or [Payment transaction][]. The contents of the common-links file are in alphabetical order. (They have been generated by script before, but are currently manually maintained.)