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

Add & use component for 'Try it!' button & related

Browse Source
This commit is contained in:
mDuo13
2025-01-28 16:38:58 -08:00
parent e637346701
commit 9d8cfc88cb
117 changed files with 378 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -103,19 +103,25 @@ Use the following conventions when creating a page:
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:
`{badge href="myurl" date="<date of release>"} New in: <program> <version number>{% /badge%}`
<pre><code>
{% badge href="url" date="date of release" %}New in: program version{% /badge%}
</code></pre>
For example, the following badge definition:
`{% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}New in: Clio v2.0.0{% /badge %}`
<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/1.1.0" date="February 18, 2024" %}New in: Clio v2.0.0{% /badge %}.
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 %}.
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.
@@ -176,11 +182,7 @@ navigation:
---
```
## 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/`.
### Graphics
## Graphics
Store your graphics in the `/docs/img` directory. Embed graphics using the syntax:
@@ -190,7 +192,7 @@ For example, `![XRPL Foundation Logo](/docs/img/xrplf-logo.png)` renders as foll
![XRPL Foundation Logo](/docs/img/xrplf-logo.png)
### Videos
## Videos
Videos are stored on YouTube. Once uploaded, you can copy the embed instructions and paste them into your document.
@@ -284,7 +286,7 @@ The left column is bold by default. If you don't want a bold label in the left c
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
## Links
Links use the syntax `[<link text>](<url>)`.
@@ -300,7 +302,7 @@ See [XRPL.org](http://xrpl.org) for solutions to all the world's problems.
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 were first generated by script, but are maintained manually.)
### Code Samples
## Code Samples
Format method names and other code structures inline enclosing the code in backtick (&#96;) characters. For example:
@@ -314,14 +316,16 @@ For longer code blocks, use three backtics (&#96;&#96;&#96;) followed by the lan
For example:
&#96;&#96;&#96;javascript<br/>
&nbsp;&nbsp;&nbsp;&nbsp;const prepared = await client.autofill({<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"TransactionType": "Payment",<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"Account": standby_wallet.address,<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"Amount": xrpl.xrpToDrops(sendAmount),<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"Destination": standbyDestinationField.value<br/>
&nbsp;&nbsp;})
&#96;&#96;&#96;
<pre><code>
```javascript
const prepared = await client.autofill({
"TransactionType": "Payment",
"Account": standby_wallet.address,
"Amount": xrpl.xrpToDrops(sendAmount),
"Destination": standbyDestinationField.value
})
```
</code></pre>
renders as
@@ -334,6 +338,14 @@ 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.
@@ -371,4 +383,78 @@ There I was, happy as a lark, skipping through the daisies, when I shyly handed
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. |
{% child-pages /%}

29
resources/dev-tools/components/websocket-api/data/command-list.json
View File

@@ -132,7 +132,8 @@
"ledger_index": "validated",
"transactions": false,
"expand": false,
"owner_funds": false
"owner_funds": false,
"api_version": 2
}
},
{
@@ -508,6 +509,16 @@
"command": "fee"
}
},
{
"name": "manifest",
"description": "Look up manifest information for a given validator public key.",
"link": "/docs/references/http-websocket-apis/public-api-methods/server-info-methods/manifest",
"body": {
"id": "manifest_example",
"command": "manifest",
"public_key": "nHUFE9prPXPrHcG3SkwP1UzAQbSphqyQkQK9ATXLZsfkezhhda3p"
}
},
{
"name": "server_definitions",
"description": "Returns an SDK-compatible definitions.json, generated from the rippled server being queried.",
@@ -524,14 +535,6 @@
"command": "server_info"
}
},
{
"name": "version",
"description": "Retrieves the API version information. When you connect to a cluster that includes a Clio server, the Clio method is used.",
"link": "/docs/references/http-websocket-apis/public-api-methods/server-info-methods/version",
"body": {
"command": "version"
}
},
{
"name": "server_state",
"description": "Reports a machine-readable version of various information about the rippled server being queried.",
@@ -539,6 +542,14 @@
"body": {
"command": "server_state"
}
},
{
"name": "version",
"description": "Retrieves the API version information. When you connect to a cluster that includes a Clio server, the Clio method is used.",
"link": "/docs/references/http-websocket-apis/public-api-methods/server-info-methods/version",
"body": {
"command": "version"
}
}
]
},