diff --git a/docs/img/xrplf-logo.png b/docs/img/xrplf-logo.png new file mode 100644 index 0000000000..a8cb61ec1b Binary files /dev/null and b/docs/img/xrplf-logo.png differ diff --git a/resources/contribute-documentation/index.md b/resources/contribute-documentation/index.md index b87043b7e5..acbb87152f 100644 --- a/resources/contribute-documentation/index.md +++ b/resources/contribute-documentation/index.md @@ -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 . 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=""} New in: {% /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: + +`![image_description](/docs/img/my_image.png)` + +For example, `![XRPL Foundation Logo](/docs/img/xrplf-logo.png)` renders as follows. + +![XRPL Foundation Logo](/docs/img/xrplf-logo.png) + +### 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 ` +``` + + + +### 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 `[]()`. + +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
+    const prepared = await client.autofill({
+      "TransactionType": "Payment",
+      "Account": standby_wallet.address,
+      "Amount": xrpl.xrpToDrops(sendAmount),
+      "Destination": standbyDestinationField.value
+  }) +``` + +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="" /%}`. + +For example, here is the snippet `/docs/_snippets/secret-key-warning.md`. + +
+{% admonition type="warning" name="Caution" %}
+Never submit a secret key to a server you do not control. Do not send a secret key unencrypted over the network.
+{% /admonition %} +
+ +To embed the text, use the tag `{% partial file="/docs/_snippets/secret-key-warning.md" /%}`. + +For example: + +
+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. +
+ +renders as: + +
+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. +
{% child-pages /%}