mirror of
https://github.com/XRPLF/xrpl-dev-portal.git
synced 2025-11-21 04:05:49 +00:00
Merge pull request #2522 from XRPLF/contribution_updates
Contribution updates
This commit is contained in:
Dennis Dawson
BIN
docs/img/xrplf-logo.png
Normal file
BIN
docs/img/xrplf-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
@@ -19,8 +19,6 @@ The XRPL Dev Portal provides comprehensive documentation of the the XRP Ledger,
|
||||
|
||||
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](https://github.com/XRPLF/xrpl-dev-portal/blob/master/LICENSE).
|
||||
|
||||
|
||||
|
||||
## Repository Layout
|
||||
|
||||
- `_api-examples/` - Sample API requests and responses, especially ones used in the documentation.
|
||||
@@ -101,6 +99,26 @@ Use the following conventions when creating a page:
|
||||
- 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.
|
||||
|
||||
### 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:
|
||||
|
||||
`{badge href="myurl" date="<date of release>"} New in: <program> <version number>{% /badge%}`
|
||||
|
||||
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 %}`
|
||||
|
||||
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 %}.
|
||||
|
||||
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 %}.
|
||||
|
||||
It is a best practice to remove any new/updated badges more than 2 years old.
|
||||
|
||||
### Terminology
|
||||
|
||||
Use the following words and phrases as described:
|
||||
@@ -144,12 +162,213 @@ seo:
|
||||
|
||||
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.
|
||||
|
||||
### Next and Previous Buttons
|
||||
|
||||
The documentation and blog pages have "Next" and "Previous" buttons at the bottom of the page.
|
||||
|
||||
If these buttons don't make sense as a proper reading order in context you can disable them by updating the frontmatter of the page.
|
||||
|
||||
```yaml
|
||||
---
|
||||
theme:
|
||||
navigation:
|
||||
nextButton:
|
||||
hide: true
|
||||
---
|
||||
```
|
||||
|
||||
## 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/`.
|
||||
|
||||
## Common Links
|
||||
### Graphics
|
||||
|
||||
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.)
|
||||
Store your graphics in the `/docs/img` directory. Embed graphics using the syntax:
|
||||
|
||||
``
|
||||
|
||||
For example, `` renders as follows.
|
||||
|
||||
|
||||
|
||||
### Videos
|
||||
|
||||
Videos are stored on YouTube. Once uploaded, you can copy the embed instructions and paste them into your document.
|
||||
|
||||
To embed a YouTube video in your topic:
|
||||
|
||||
1. Locate your video on YouTube.
|
||||
2. Under the video, click **Share**.
|
||||
3. Click **Embed**.
|
||||
4. Click **Copy** in the lower right corner of the pop-up.
|
||||
5. Paste the `<iframe>` element in your topic.
|
||||
|
||||
For example, here is the code to embed the _Send Checks_ video.
|
||||
|
||||
```
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/5zRBC7dGSaM?
|
||||
si=Mbi8diaFTDR2fc20" title="YouTube video player" frameborder="0" allow="accelerometer;
|
||||
autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
```
|
||||
|
||||
<iframe width="560" height="315" src="https://www.youtube.com/embed/5zRBC7dGSaM?
|
||||
si=Mbi8diaFTDR2fc20" title="YouTube video player" frameborder="0" allow="accelerometer;
|
||||
autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
||||
|
||||
### Tables
|
||||
|
||||
Markdoc provides three different syntax styles for generating tables.
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
| 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! |
|
||||
```
|
||||
|
||||
| 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 (--:).
|
||||
|
||||
```
|
||||
| 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 |
|
||||
|
||||
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
|
||||
|
||||
Links use the syntax `[<link text>](<url>)`.
|
||||
|
||||
For example, the sentence:
|
||||
|
||||
`See [XRPL.org](http://xrpl.org) for solutions to all the world's problems.`
|
||||
|
||||
renders to:
|
||||
|
||||
See [XRPL.org](http://xrpl.org) for solutions to all the world's problems.
|
||||
|
||||
### Common Links
|
||||
|
||||
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
|
||||
|
||||
Format method names and other code structures inline enclosing the code in backtick (`) characters. For example:
|
||||
|
||||
My favorite method ever is `nft_info`.
|
||||
|
||||
renders as
|
||||
|
||||
My favorite method ever is `nft_info`.
|
||||
|
||||
For longer code blocks, use three backtics (```) 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 (```).
|
||||
|
||||
For example:
|
||||
|
||||
```javascript<br/>
|
||||
const prepared = await client.autofill({<br/>
|
||||
"TransactionType": "Payment",<br/>
|
||||
"Account": standby_wallet.address,<br/>
|
||||
"Amount": xrpl.xrpToDrops(sendAmount),<br/>
|
||||
"Destination": standbyDestinationField.value<br/>
|
||||
})
|
||||
```
|
||||
|
||||
renders as
|
||||
|
||||
```javascript
|
||||
const prepared = await client.autofill({
|
||||
"TransactionType": "Payment",
|
||||
"Account": standby_wallet.address,
|
||||
"Amount": xrpl.xrpToDrops(sendAmount),
|
||||
"Destination": standbyDestinationField.value
|
||||
})
|
||||
```
|
||||
|
||||
### 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 _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>
|
||||
{% admonition type="warning" name="Caution" %}<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.
|
||||
|
||||
{% 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>
|
||||
|
||||
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>
|
||||
|
||||
{% child-pages /%}
|
||||
|
||||
Reference in New Issue
Block a user