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

• assets/ - Static files used by the site's templates.
• content/ - Source files used to build the documentation. Mostly in Markdown.
  • content/_code-samples/ - Code samples used or referenced by the documentation. Where possible, these are fully functional / executable scripts.
  • content/_img-sources/ - Source files for images used in the documentation. Any .uxf files are diagrams made with Umlet .
  • content/_snippets/ - Reusable chunks of Markdown text that are included in other content files, using the Dactyl preprocessor.
• img/ - Images used by the documentation contents.
• template/ - Template files for building the HTML outputs.
• tool/ - Filters, style-checker rules, and other scripts.
• styles/ - Source files (SCSS) to generate the CSS files in the assets folder.
• dactyl-config.yml - Main config file, which contains the metadata for the site. For information on our conventions, see Config Formatting.

Requirements for a Successful Pull Request

Before being considered for review or merging, each pull request must: - Pass continuous integration tests. - Be marked as drafts until they are ready for review. - Adhere to the code of conduct for this repository.

Dactyl Setup

The portal is built using Dactyl .

Dactyl requires Python 3 . Install it with pip :

pip3 install dactyl

Building the Site

This repo uses Dactyl to build HTML display versions of all the documentation. After you've done the Dactyl Setup, you can build the site from the project root directory:

dactyl_build

This outputs the generated contents to the out/ directory. These contents can be opened in a web browser as files or served as static content by a web server.

You can also run link checking or style checking from the root directory.

Link checking should be run after emptying the output folder and then building:

dactyl_link_checker

Style checking is experimental:

dactyl_style_checker

Config Formatting

The templates in this repository use metadata from the dactyl-config.yml file as well as the pages' frontmatter to generate navigation elements in the site, including header, footer, sidebars, and breadcrumbs.

If you add a new page, you must add it to the appropriate page in the pages array of the dactyl-config.yml file. An example entry looks like this:

    -   md: concepts/the-rippled-server/the-rippled-server.md
        targets:
            - en
            - ja # Include in all targets unless you have a translation

The Markdown file itself should start with a frontmatter stanza such as the following:

---
html: the-rippled-server.html
parent: concepts.html
template: pagetype-category.html.jinja
blurb: 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.
---

Most pages should have html, parent and blurb fields in the frontmatter, and the md and targets fields in the config file. For a fill list

Conventions

Use the following conventions when creating a page:

• The HTML filename and MD filename should match exactly except for the file extension.
• The filenames should closely 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.)
• 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) .

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

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

Terminology

Use the following words and phrases as described:

Frontmatter Fields

The fronmatter for a Markdown file in this repo can contain arbitrary key-value pairs; the config file entry for the page can add to those or override them. The following fields have specific uses or meaning: