ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-04 11:55:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update contributor documentation w/ more info

Browse Source 
- Clarify frontmatter, especially titles
- Document more markdoc tags
This commit is contained in:
mDuo13
2025-10-08 17:53:13 -07:00
parent 9b1878c512
commit 755b15383b
3 changed files with 350 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files

282
resources/contribute-documentation/index.md
View File

@@ -23,18 +23,17 @@ The official source repository for the site is at <https://github.com/XRPLF/xrpl
- `_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.
- `@l10n` - Translations into languages other than English. Currently, only Japanese.
- `@l10n` - Translations into languages other than English. Currently, Japanese is deployed and Spanish is incomplete (unused).
- `@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/` - Diagrams and other images used in the documentation. Diagrams can also be placed in the folder with the files that reference them.
- `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.
- `shared/` - Configuration files for some dependencies like CodeMirror, and React components for some specially styled pages.
- `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.
@@ -45,11 +44,13 @@ The official source repository for the site is at <https://github.com/XRPLF/xrpl
## Requirements for a Successful Pull Request
Before being considered for review or merging, each pull request must:
Before being considered for merging, each pull request must:
- Pass continuous integration tests.
- Be [marked as drafts](https://github.blog/2019-02-14-introducing-draft-pull-requests/) until they are ready for review.
- Adhere to the [code of conduct](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE-OF-CONDUCT.md) for this repository.
1. Pass continuous integration tests.
2. Adhere to the [code of conduct](https://github.com/XRPLF/xrpl-dev-portal/blob/master/CODE-OF-CONDUCT.md) for this repository.
3. Pass review from at least one maintainer, who will consider the quality, relevance, and maintainability of the contents in their review.
If your PR is not yet ready to be merged, [mark it as a draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
## Redocly Setup
@@ -84,6 +85,20 @@ If you add a new page, you should add it to the appropriate `sidebars.yaml` file
The Markdown file for a page should start with a [frontmatter stanza](#frontmatter-fields).
## Writing Style
In general, follow the [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/)'s recommendations for tone, phrasing, and structure. You are allowed to deviate from the Microsoft guide.
Try to split documentation pages into the following categories, based on their contents:
- **Concepts:** Explain the _how_ and _why_ of a topic, feature, or practice. Don't go overboard with specific names, values, or code. Use [diagrams](./creating-diagrams.md) to help with understanding.
- **References:** Describe all the possible properties, modes, or features of a piece of technology. Provide only small amounts of context, while linking to concepts for the bigger picture. Use tables or bulleted lists, sorted, to help users find what they need.
- **Tutorials:** Demonstrate how to accomplish a task or use a feature. Provide step-by-step instructions with working code samples if possible. Link to references for more details of the functions used and alternative options. For more recommendations on how to build tutorials, see the [Tutorial Guidelines](./tutorial-guidelines.md).
These types of documents serve people with different roles, or sometimes the same people at different points in their process. For example, software architects or CTOs making technical decisions might read a concept page to decide how to structure their integration or to determine which technology meets their needs; engineers might copy code from tutorials while building, then use the reference to adapt it for their use case.
Some pages, like **Use Cases**, don't fit cleanly into these categories. It is OK to have exceptions where justified.
## Conventions
Use the following conventions when creating a page:
@@ -101,29 +116,7 @@ Use the following conventions when creating a page:
### New Features
When documenting a new feature, include a badge indicating the version of the program when the feature was introduced. The badge tag takes the structure:
<pre><code>
{% badge href="url" date="date of release" %}New in: program version{% /badge%}
</code></pre>
For example, the following badge definition:
<pre><code>
{% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}New in: Clio v2.0.0{% /badge %}
</code></pre>
renders as {% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}New in: Clio v2.0.0{% /badge %}.
When updating a feature, replace _New in:_ with _Updated in:_. For example, the following badge definition:
`{% badge href="https://github.com/XRPLF/clio/releases/tag/2.1.0" date="May 4, 2024" %} Updated in: Clio v2.1.0{% /badge %}`
renders as {% badge href="https://github.com/XRPLF/clio/releases/tag/2.1.0" date="May 4, 2024" %}Updated in: Clio v2.1.0{% /badge %}.
Some phrases automatically set the color of the badge, or you can add a color parameter such as `color="purple"` to the tag to set the color explicitly.
It is a best practice to remove any new/updated badges more than 2 years old.
When documenting a new feature, include a [badge](./markdoc-tags.md#badge) indicating the version of the program when the feature was introduced. It is a best practice to remove any new/updated badges more than 2 years old.
### Terminology
@@ -153,20 +146,59 @@ Use the following words and phrases as described:
## 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:
```yaml
---
metadata:
indexPage: true # Add this if you want the page to contain an auto-generated list of its child pages.
indexPage: true # Use if you want to use the {% child-pages /%} macro to display a list of page children
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.
description: Transact with confidence using the XRP Ledger's suite of compliance features for following government regulations and security practices.
title: Compliance Features
---
```
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.
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 removed. For a reference of frontmatter fields that are supported by the current (Redocly) toolchain, see [Front matter configuration options (Realm docs)](https://redocly.com/docs/realm/config/front-matter-config).
### seo.title, default title, and sidebar label
Every markdown page should have an h1 on the first line of the markdown contents, such as this:
```
# What is XRP?
```
By default, the text of this title is used as the title of the page. You don't need to specify a title separately in the frontmatter, especially since someone might change it in one place and forget to update the other. Sometimes pages have a longer title in the frontmatter's `seo.title` field, for purposes of search engine optimization (SEO). These titles are usually longer and optimized to include phrases or search terms that are likely to match queries people might type while looking for the page. **Titles in the frontmatter should only be used when recommended for SEO.** For example:
```
---
seo:
title: What is XRP and Why is it Valuable?
---
```
A third place a page might have a title is in a `label` field in the `sidebars.yaml` file. This should always come with a translation key in the `labelTranslationKey` field. Labels in the `sidebars.yaml` file should only be used in these cases:
- To provide a translatable title for a `.page.tsx` file.
- To shorten an SEO title so that it fits better in the sidebar. In this case, the label contents should match the original h1 title.
For example:
```
- page: docs/introduction/what-is-xrp.md
label: What is XRP?
labelTranslationKey: sidebar.docs.introduction.what-is-xrp
```
For reference, here's the hierarchy that determines which title gets used where:
| Location | Which title it uses |
|----------|---------------------|
| `<title>` element (the text that displays in the tab name and the title bar of your browser, if it has one) | `seo.title`, falling back to md h1 |
| `<meta name="title" ...>`, `<meta name="og:title" ...>`, `<meta name="twitter:title" ...>` and so on in the `<head>` of the page, which are used when "unfurling" a link (showing a preview) in various chat and social media apps like Facebook or Slack | `seo.title`, falling back to md h1 |
| Sidebar navigation | `label` from `sidebars.yaml`, then `seo.title`, and finally md h1 |
| In-page header, that is, the big text in the center column | md h1 only |
### Next and Previous Buttons
@@ -188,9 +220,9 @@ Store your graphics in the `/docs/img` directory. Embed graphics using the synta
`![image_description](/docs/img/my_image.png)`
For example, `![XRPL Foundation Logo](/docs/img/xrplf-logo.png)` renders as follows.
For example, `![XRPL X mark](/static/img/xrp-x-logo.png)` renders as follows.
![XRPL Foundation Logo](/docs/img/xrplf-logo.png)
![XRPL X mark](/static/img/xrp-x-logo.png)
## Videos
@@ -220,71 +252,44 @@ referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
## Tables
Markdoc provides three different syntax styles for generating tables.
Use Markdown tables liberally. Tables are a good way to convey possible options, especially in reference documentation.
In most cases, create tables using the pipe character (|) to separate columns and three or more hyphens (---) to create the column headers.
```
| | Head 1 |
| ------- | ------ |
| Label 1 | Val 1 |
```
This code renders as follows.
| | Head 1 |
| ------- | ------ |
| Label 1 | Val 1 |
The cells do not have to be the same width. The renderer aligns the columns and wraps text as needed, as shown.
The GitHub Flavored Markdown syntax uses the pipe character (|) to separate columns and three or more hyphens (---) to create the column headers. For example:
```
| Key | Value |
| --- | ----- |
|-----|-------|
| Name | H. G. Wells |
| Genre | Science Fiction |
| Hyperbole | The greatest story ever told! No one has ever written anything more important than this Victorian era classic. Oh, how swells the heart to ponder the heady philosophies introduced therein! |
```
This table displays as follows:
| Key | Value |
| --- | ----- |
|-----|-------|
| Name | H. G. Wells |
| Genre | Science Fiction |
| Hyperbole | The greatest story ever told! No one has ever written anything more important than this Victorian era classic. Oh, how swells the heart to ponder the heady philosophies introduced therein! |
Use colons in the heading lines to align columns left (:--), middle (:-:), or right (--:).
The cells do not have to be the same width. The renderer aligns the columns and wraps text as needed. However, it is often helpful for editors if you align the columns of the table in the markdown source file.
Optionally, use colons in the heading lines to align columns left (:--), middle (:-:), or right (--:). For example:
```
| Model | Color | Price |
| :-: | :-- | --: |
|:--------:|:------|------:|
| Protexra | Electric Blue | 50,000 XRP |
| Joatic | Hot Pink | 165,000 XRP |
| Zhanu | Neon Green | 234,000 XRP |
```
| Model | Color | Price |
| :-: | :-- | --: |
|:--------:|:------|------:|
| Protexra | Electric Blue | 50,000 XRP |
| Joatic | Hot Pink | 165,000 XRP |
| Zhanu | Impetuous Green | 1,728,000 XRP |
| Zhanu | Neon Green | 234,000 XRP |
The left column is bold by default. If you don't want a bold label in the left column, you can use an empty left column and start your table one column over.
```
| | French | English | German |
| --- | --- | --- | --- |
| | Fromage | Cheese | Käse |
| | Maux d'estomac | Stomach ache | Magenschmerzen |
| | Cornichon | Pickle | Essiggurke |
```
| | French | English | German |
| --- | --- | --- | --- |
| | Fromage | Cheese | Käse |
| | Maux d'estomac | Stomach ache | Magenschmerzen |
| | Cornichon | Pickle | Essiggurke |
Use these basic tables whenever possible. If you genuinely require special formatting not provided by the examples above, you can create a table using HTML syntax.
## Links
@@ -306,11 +311,11 @@ To make it easier to link to pages that are commonly cited, you can add a `{% ra
Format method names and other code structures inline enclosing the code in backtick (&#96;) characters. For example:
&nbsp;&nbsp;&nbsp;&nbsp;My favorite method ever is &#96;nft_info&#96;.
> My favorite method ever is &#96;nft_info&#96;.
renders as
&nbsp;&nbsp;&nbsp;&nbsp;My favorite method ever is `nft_info`.
> My favorite method ever is `nft_info`.
For longer code blocks, use three backtics (&#96;&#96;&#96;) followed by the language name. Type a return, and enter the sample code. At the end of your code sample, type a return and close the block again with three backticks (&#96;&#96;&#96;).
@@ -338,123 +343,8 @@ renders as
})
```
## Markdoc Components
The files are processed with [Markdoc](https://markdoc.dev/), 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/`.
### Badges
See [New Features](#new-features).
### Partials
If you have text that you use frequently, or text that requires periodic update in a number of places in the documentation, you can create a &#95;snippet file for reuse.
Store your file in the `_snippet` directory. To insert the partial file, use the syntax `{% partial file="<file url>" /%}`.
For example, here is the snippet `/docs/_snippets/secret-key-warning.md`.
<blockquote>
{&#37; admonition type="warning" name="Caution" &#37;}<br/>
Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.<br/>
{% /admonition %}
</blockquote>
To embed the text, use the tag `{% partial file="/docs/_snippets/secret-key-warning.md" /%}`.
For example:
<blockquote>
There I was, happy as a lark, skipping through the daisies, when I shyly handed my secret
key to my one true love.
{&#37; partial file="/docs/_snippets/secret-key-warning.md" /&#37;}
Alas, if only I had heeded that sage advice, I would not rue the day as I do today.
</blockquote>
renders as:
<blockquote>
There I was, happy as a lark, skipping through the daisies, when I shyly handed my secret key to my one true love.
{% partial file="/docs/_snippets/secret-key-warning.md" /%}
Alas, if only I had heeded that sage advice, I would not rue the day as I do today.
</blockquote>
### Not-Enabled Badge
The `{% not-enabled /%}` Markdoc component displays a yellow flask icon with a tooltip about how the feature is not available on the production XRP Ledger. Use this when discussing amendments that are open for voting but not currently enabled. Example: {% not-enabled /%}
This tag is self-closing, and it takes no parameters.
### Repo Link
This tag links to a particular file in the source code repository for this site, usually a code sample. For example:
<pre><code>
{% repo-link path="_code-samples/build-a-desktop-wallet/js/1_ledger-index.js" %}`1-ledger-index/index.js`{% /repo-link %}
</code></pre>
becomes: {% repo-link path="_code-samples/build-a-desktop-wallet/js/1_ledger-index.js" %}`1-ledger-index/index.js`{% /repo-link %}
If you are working from a fork or branch of the site, all such links can be updated at once with a site configuration change.
### Try It
The `{% try-it ... /%}` Markdoc tag provides a convenient shortcut for linking to the WebSocket tool as a button. This tag is self-closing.
Example:
{% try-it method="account_currencies" server="testnet" /%}
Example syntax:
<pre><code>
{% try-it method="account_currencies" server="testnet" /%}
</code></pre>
The text of the button is normally "Try it!" in English, and can be translated by setting the `component.tryit` key in the localization's `translations.yaml` file.
This tag takes the following parameters:
| Parameter | Required? | Description |
|---|---|---|
| `method` | Yes | The ID of the anchor to use on the WebSocket Tool page. For most WebSocket API methods, this is the API method exactly, but it could contain more. For example, different `ledger_entry` variations use a suffix like `ledger_entry-nft-page`. If you are documenting a new method, you must also add that method to the WebSocket tool by editing `/resources/dev-tools/components/websocket-api/data/command-list.json`. |
| `server` | No | A specific server to use for the request. You may want to specify the server if a method is specific to Clio or `rippled` servers, or if the example uses data or amendments that are only on a specific test network. |
The values you can provide to the `server` parameter are as follows:
| `server` value | Server to use |
|---|---|
| (Omitted) | The WebSocket tool's default server (currently `s1.ripple.com`) |
| `s1` | Ripple's `s1.ripple.com` Mainnet public cluster, typically served by Clio servers. |
| `s2` | Ripple's `s2.ripple.com` Mainnet full-history public cluster, typically served by Clio servers. |
| `xrplcluster` | The `xrplcluster.com` cluster of public servers, typically served by `rippled` servers with a lightweight proxy in front. |
| `devnet` | The `s.altnet.rippletest.net` cluster of Testnet servers. |
| `testnet` | The `s.devnet.rippletest.net` cluster of Devnet servers. |
### Tx Example
The `{% tx-example ... /%}` Markdoc tag provides a convenient shortcut for linking to the WebSocket tool as a button with a body pre-filled to look up a specific example transaction. This tag is self-closing. Example:
{% tx-example txid="1AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635" /%}
Example syntax:
<pre><code>
{% tx-example txid="1AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635" /%}
</code></pre>
The text of the button is normally "Query example transaction" in English, and can be translated by setting the `component.queryexampletx` key in the localization's `translations.yaml` file.
This tag takes the following parameters:
| Parameter | Required? | Description |
|---|---|---|
| `txid` | Yes | The unique hash of the transaction to look up. |
| `server` | No | A specific server to use for the request. Possible values are the same as `{% try-it %}` as defined above. For example, you may need to specify `devnet` to show a transaction added by an amendment that isn't enabled on Mainnet. |
## Markdoc Tags
The files are processed with [Markdoc](https://markdoc.dev/), which means they can contain special tags in `{% ... %}` syntax. In addition to Redocly's built-in tags, this repository has some custom tags. For details on markdoc tags and their usage, see [Markdoc Tags](./markdoc-tags.md).
{% child-pages /%}

261
resources/contribute-documentation/markdoc-tags.md Normal file
View File

@@ -0,0 +1,261 @@
# Markdoc Tags
This page serves as a reference of the [Markdoc tags](https://redocly.com/docs/realm/content/markdoc-tags/tag-library) used in XRPL documentation. These extensions of Markdown syntax allow for stylized and dynamic contents.
When using self-closing tags, be sure to include the closing slash in the tag definition. Otherwise, the unclosed tag may accidentally hide all contents of the page after it.
## Redocly Built-In Tags
This section describes the Redocly built-in tags that XRPL documentation uses most often and the conventions for using them in the site.
### Admonition
Show text in a colored box that stands out from regular paragraphs, sometimes referred to as a _callout_. There are four levels of admonition with escalating levels of severity. You can put any text in the `name` attribute, but there are recommended names for each category that can be automatically translated. For historical reasons, the recommended names do not align cleanly with the `type` options. The recommended names are:
| `type` | Color | Recommended `name` | Usage |
|-----------|---------------|--------------------|-------|
| `success` | Green | `Tip` | Optional, additional information, shortcuts, and cases where people might think there's a problem but there actually isn't. |
| `info` | Blue | `Note` | Quirks, background information, or other details that are not critical but may be good to know. |
| `warning` | Yellow/Orange | `Caution` | Common mistakes, misunderstandings, or limitations that may cause confusion and inconvenience. |
| `danger` | Red/Magenta | `Warning` | Mistakes or risks that may cause financial loss, security incidents, or other substantial problems. |
Example usage:
<pre><code>
{% admonition type="success" name="Tip" %}
Admonitions create colored boxes that stand out from regular paragraphs.
{% /admonition %}
</code></pre>
Demonstration:
{% admonition type="success" name="Tip" %}
Admonitions create colored boxes that stand out from regular paragraphs.
{% /admonition %}
It is valid to put an admonition's opening and closing tags all on the same line as its contents. To avoid a Redocly bug, make sure multi-line admonitions have their opening and closing tags on separate lines.
### Inline SVG
Include an image in SVG format inline in the page's markup. This allows the diagram's color scheme to adapt to the user's current (light/dark) theme. Typically, you should use the tag inside a link that opens the SVG file as a stand-alone image so the user can view it and zoom in or out as needed. For tips on making diagrams compatible with this feature, see [Creating Diagrams](./creating-diagrams.md). This tag is self-closing.
Example usage:
<pre><code>
[{% inline-svg file="/docs/img/anatomy-of-a-ledger-simplified.svg" /%}](/docs/img/anatomy-of-a-ledger-simplified.svg "Figure 1: Anatomy of a ledger version, which includes transactions, state, and metadata")
</code></pre>
Demonstration:
[{% inline-svg file="/docs/img/anatomy-of-a-ledger-simplified.svg" /%}](/docs/img/anatomy-of-a-ledger-simplified.svg "Figure 1: Anatomy of a ledger version, which includes transactions, state, and metadata")
### Partial and Raw Partial
Include text from another, reusable file, called a _snippet_. Unlike environment variables, partials are typically an entire paragraph or more. If text needs to be updated in multiple places, you can use this component to reuse a single file's contents in multiple places. Store the source file in the `docs/_snippets/` directory. This tag is self-closing.
Example usage:
<pre><code>
{% partial file="/docs/_snippets/secret-key-warning.md" /%}
</code></pre>
Demonstration:
{% partial file="/docs/_snippets/secret-key-warning.md" /%}
Links and markup inside snippets are parsed separately before being added to the including file. Relative links are resolved based on the location of the snippet, not on the file including it. To include a snippet that resolves its contents in the context of the including page instead, include the file as a raw partial instead. This is useful when you want the partial to refer to the name of the page that included it, or if it defines common links used throughout the site.
Example usage:
<pre><code>
&lcub;% raw-partial file="/docs/_snippets/tx-fields-intro.md" /%}
</code></pre>
### Variables
Include the contents of a predefined variable, inline in the document. Unlike partials, these are typically only a few words at most. Common use cases include `{% $frontmatter.seo.title %}` for referring to the title of the current page (used in some templates and snippets), and environment variables for the current reserve amounts on the XRP Ledger Mainnet.
Example usage:
<pre><code>
Each NFToken page requires a reserve of {% $env.PUBLIC_OWNER_RESERVE %}.
</code></pre>
Demonstration:
Each NFToken page requires a reserve of {% $env.PUBLIC_OWNER_RESERVE %}.
{% admonition type="warning" name="Caution" %}Variable references are like self-closing tags, but they don't use a slash like self-closing tags should (`/%}`).{%/admonition%}
## Custom Tags
Markdown supports creating custom tags with user-defined functionality. This repository defines several such tags for convenience in editing, as follows.
### Amendment Disclaimer
Show a disclaimer that functionality is based on an amendment to the XRP Ledger protocol, which updates live with the status of the amendment on Mainnet. The `name` parameter is required and is case-sensitive. This tag is self-closing.
Example usage:
<pre><code>
{% amendment-disclaimer name="Credentials" /%}
</code></pre>
Demonstration:
{% amendment-disclaimer name="Credentials" /%}
When the amendment is not enabled on Mainnet, the component adds a paragraph that says, "Requires the (name) amendment," with a badge showing the amendment's voting percentage. After the amendment is enabled, the paragraph changes to say, "Added by the (name) amendment," with a badge showing the date the amendment became enabled.
The `compact=true` parameter (note, it is an error to put true in quotation marks here) displays only the name of the amendment and the status badge.
The `mode="updated"` parameter (case-sensitive) changes the paragraph so that it says, "The (name) amendment updates this," before the amendment is enabled, and "Updated by the (name) amendment," afterward, with the same badges.
### Badge
Show a colored inline badge. Use these to point out new or updated features, especially in the API, that are not tied to an amendment. The contents are the text of the badge; the left and right halves are split by the `:` character in the text.
Example usage:
<pre><code>
{% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}New in: Clio 2.0.0{% /badge %}
</code></pre>
Demonstration:
{% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}New in: Clio 2.0.0{% /badge %}
The `date` parameter is optional, and is not displayed. It is helpful to remind editors when a change is old enough to remove the badge.
When updating a feature, replace _New in:_ with _Updated in:_. These and certain other phrases automatically set the color of the badge and can be automatically translated. If necessary, you can add a color parameter such as `color="purple"` to the tag to set the color explicitly.
### Card Grid and XRPL Card
Create a grid of cards with specific links and icons. By default, the grid is 3 cards wide on desktop and 1 card wide on mobile. The contents of the card grid should only be `xrpl-card` tags. The `xrpl-card` tag is self-closing.
Example usage:
<pre><code>
{% card-grid %}
{% xrpl-card title="Javascript" body="Using the xrpl.js client library." href="/docs/tutorials/javascript/" image="/img/logos/javascript.svg" imageAlt="Javascript logo" /%}
{% xrpl-card title="Python" body="Using xrpl.py, a pure Python library." href="/docs/tutorials/python/" image="/img/logos/python.svg" imageAlt="Python logo" /%}
{% /card-grid %}
</pre></code>
Demonstration:
{% card-grid %}
{% xrpl-card title="Javascript" body="Using the xrpl.js client library." href="/docs/tutorials/javascript/" image="/img/logos/javascript.svg" imageAlt="Javascript logo" /%}
{% xrpl-card title="Python" body="Using xrpl.py, a pure Python library." href="/docs/tutorials/python/" image="/img/logos/python.svg" imageAlt="Python logo" /%}
{% /card-grid %}
### Child Pages
Show a bulleted list of pages that are children of the page using this tag. The descriptions of the pages use the frontmatter's `seo.description` field. This tag is self-closing and takes no parameters.
Example usage:
<pre><code>
{% child-pages /%}
</code></pre>
This tag only works if you include the following data in the page's frontmatter:
```
metadata:
indexPage: true
```
### Not Enabled
Display a yellow flask icon with a tooltip about how the feature is not available on the production XRP Ledger. Usually, you should use an [amendment-disclaimer](#amendment-disclaimer) instead, but there may be edge cases where you want to include this icon. This tag is self-closing and takes no parameters.
Example usage:
<pre><code>
{% not-enabled /%}
</code></pre>
Demonstration:
{% not-enabled /%}
### Repo Link
Link to a particular file in the source code repository for this site, usually a code sample. If you are working from a fork or branch of the site, all such links can be updated at once with a site configuration change. The contents are the text of the link.
Example usage:
<pre><code>
{% repo-link path="_code-samples/build-a-desktop-wallet/js/1_ledger-index.js" %}`1-ledger-index/index.js`{% /repo-link %}
</code></pre>
Demonstration:
{% repo-link path="_code-samples/build-a-desktop-wallet/js/1_ledger-index.js" %}`1-ledger-index/index.js`{% /repo-link %}
### Try It
Link to the WebSocket tool as a button. The text of the button is normally "Try it!" in English, and can be translated by setting the `component.tryit` key in the localization's `translations.yaml` file. This tag is self-closing.
Example usage:
<pre><code>
{% try-it method="account_currencies" server="testnet" /%}
</code></pre>
Demonstration:
{% try-it method="account_currencies" server="testnet" /%}
This tag takes the following parameters:
| Parameter | Required? | Description |
|---|---|---|
| `method` | Yes | The ID of the anchor to use on the WebSocket Tool page. For most WebSocket API methods, this is the API method exactly, but it could contain more. For example, different `ledger_entry` variations use a suffix like `ledger_entry-nft-page`. If you are documenting a new method, you must also add that method to the WebSocket tool by editing `/resources/dev-tools/components/websocket-api/data/command-list.json`. |
| `server` | No | A specific server to use for the request. You may want to specify the server if a method is specific to Clio or `rippled` servers, or if the example uses data or amendments that are only on a specific test network. |
The values you can provide to the `server` parameter are as follows:
| `server` value | Server to use |
|---|---|
| (Omitted) | The WebSocket tool's default server (currently `s1.ripple.com`) |
| `s1` | Ripple's `s1.ripple.com` Mainnet public cluster, typically served by Clio servers. |
| `s2` | Ripple's `s2.ripple.com` Mainnet full-history public cluster, typically served by Clio servers. |
| `xrplcluster` | The `xrplcluster.com` cluster of public servers, typically served by `rippled` servers with a lightweight proxy in front. |
| `devnet` | The `s.altnet.rippletest.net` cluster of Testnet servers. |
| `testnet` | The `s.devnet.rippletest.net` cluster of Devnet servers. |
### Tx Example
Link to the WebSocket tool, as a button, with a body pre-filled to look up a specific example transaction. The text of the button is normally "Query example transaction" in English, and can be translated by setting the `component.queryexampletx` key in the localization's `translations.yaml` file. This tag is self-closing.
Example usage:
<pre><code>
{% tx-example txid="1AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635" /%}
</code></pre>
Demonstration:
{% tx-example txid="1AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635" /%}
This tag takes the following parameters:
| Parameter | Required? | Description |
|---|---|---|
| `txid` | Yes | The unique hash of the transaction to look up. |
| `server` | No | A specific server to use for the request. Possible values are the same as `{% try-it %}` as defined above. For example, you may need to specify `devnet` to show a transaction added by an amendment that isn't enabled on Mainnet. |

1
sidebars.yaml
View File

@@ -757,6 +757,7 @@
external: true
- page: resources/contribute-documentation/documentation-translations.md
- page: resources/contribute-documentation/creating-diagrams.md
- page: resources/contribute-documentation/markdoc-tags.md
- page: resources/contribute-documentation/tutorial-guidelines.md
- page: resources/contribute-documentation/tutorial-structure.md
- page: resources/contribute-blog/index.md