ドキュメントへの貢献

XRP Ledger開発者ポータルへの貢献を検討いただきありがとうございます！

私たちは、あなたが興味を持ってくださっていることにとても感動しています。XRP Ledger(XRPL)へ貢献することは、XRPLついて学ぶ素晴らしい機会です。

私たちはあなたのプルリクエストを喜んでレビューします。プロセスをできるだけ円滑に進めるため、このドキュメントを読み、記載されているガイドラインに従ってください。

当サイトについて

XRPL Dev Portalでは、開発者が開発を開始するためのサンプルコードやその他の情報を含む、XRP Ledgerの包括的なドキュメントを提供しています。

本プロジェクトの公式リポジトリはhttps://github.com/XRPLF/xrpl-dev-portalとなっています。投稿の著作権はそれぞれの投稿者に帰属しますが、MITライセンスの下で提供されなければなりません。

リポジトリの構成

• _api-examples/ - APIリクエストやレスポンスのサンプル(特にドキュメントで使用されているもの)
• _code-samples/ - ドキュメントで使用されているサンプルコード(可能な限り完全に動作するスクリプト)
• @l10n - 英語以外の翻訳コンテンツ
• @theme - MarkdocのコンテンツやReactのカスタムページで使用されるコンポーネントのオーバーライドやカスタムコンポーネント
• about/ - 概要セクションのソースファイル
• blog/ - XRPL開発者ブログのソースファイル
• community/ - コミュニティセクションのソースファイル
• docs/ - ドキュメントをビルドするためのソースファイル(ほとんどがMarkdownファイル)
  • docs/_snippets/ - ドキュメント内で再利用可能なテキスト
  • docs/img/ - ドキュメント内で利用する図やその他の画像
  • docs/img/_sources/ - ドキュメント内で利用する画像のソースファイル(存在する場合)
• locale/ - 廃止 以前利用されていた翻訳用のファイル
• resources/ - リソースセクションのソースファイル
• shared/ - CodeMirrorなどの依存関係の設定ファイル
• static/ - Webサイトのテンプレートやテーマで使用される静的ファイル
• styles/ - カスタムCSS用のSCSSのソースファイル
• redirects.yaml - 以前利用されていたパスから現在のコンテンツへのリダイレクトの定義
• redocly.yaml - Webサイトにの主要な設定ファイル
• sidebars.yaml - ドキュメントおよびリソースセクションのサイドバーの定義
• top-nav.yaml - ナビゲーションバーの定義

プルリクエストが承認されるための条件

レビューやマージが承認される前に、それぞれのプルリクエストは以下の条件を満たしていなければなりません。

• インテグレーションテストに合格すること。
• レビューの準備が整うまで、Draftとしてください。
• このリポジトリのコード規約を遵守してください。

Redoclyのセットアップ

このポータルはRedocly Realmを使用して構築されています。Realmは現在クローズドベータ版です。ローカル開発環境にインストールするには、Node.js(バージョン20が推奨)とNPMが必要です。

次のコマンドを実行して、Realmとその他の必要な依存関係をインストールできます。

npm i

サイトの構築

依存関係のインストール後、次のコマンドを実行してローカル開発サーバを起動できます。

npm run start

ブラウザでhttp://localhost:4000/にアクセスしてプレビューを表示できます。

設定ファイルのフォーマット

Realmの設定ファイルは、サイト内のナビゲーション要素を生成するために使用されます。これには、ヘッダー、フッター、サイドバー、パンくずリストが含まれます。

新しいページを追加する場合、そのページをsidebars.yamlファイルに追加する必要があります。ドキュメントとブログ用のサイドバーのファイルがあります。以下は、ネストされた子ページがないページの項目の例です。

- page: concepts/consensus-protocol/index.md

Markdownファイルのページは、frontmatterスタンザで始まる必要があります。

規約

ページを作成する際には、以下の規約に従ってください。

• HTMLのファイル名とMDのファイル名は、拡張子を除いて完全に一致していなければなりません。ファイル名は"and"や"the"のような単語を含め、ページのタイトルと密接に一致する必要がありますが、スペースや句読点の代わりにハイフンを使用し、すべて小文字にする必要があります。例えば、cash-a-check-for-an-exact-amount.mdのようにします。ページのタイトルを変更した場合は、ファイル名も変更する必要があります。(すでに別のURLで公開されている場合は、古いURLからのリダイレクトを残してください)
  • カテゴリ内のページは、そのカテゴリの名前のサブフォルダに配置されるべきですが、親ディレクトリにも同じ単語が含まれている場合は、より簡潔にすることができます。ファイル名はindex.mdで、タイトルはフォルダ名に似ている必要があります。例えば、"Protocol Reference"のインデックスページはreferences/protocol/index.mdにあります。
• 常にh1ヘッダーでページを始めます。
• ページの一番上のh1アンカーにはリンクせず、アンカーなしでページ自体にリンクしてください。これは翻訳時のリンク切れを防ぐのに役立ちます。以降のヘッダーへのリンクは問題ありません。
• ページのタイトルに書式( 斜体 やコードなど)を使わないでください。
• Markdownファイルのテキストを折り返さないでください。
• コードサンプルの場合、1行は80文字以下になるようにしてください。
• 迷ったら、Ciro SantilliのMarkdownスタイルガイド (Writability Profile)に従ってください。
• Markdownやコードサンプルでは、インデントにタブ文字を使用しないでください。JavaScriptのコードサンプルでは、1字下げにつき2個のスペースを使用してください。
• テキストファイルは改行文字で終わるようにしてください。(一部のテキストエディタはこれを自動的に処理します。)ファイルはBOMなしのUTF-8でエンコードしてください。

新機能

新機能を文書化する場合、その機能が導入されたプログラムのバージョンを示すバッジを含めてください。バッジタグは以下の構造です。

{% badge href="myurl" date="<リリース日>" %}新規: <プログラム> <バージョン番号>{% /badge%}

例えば次のようなバッジ定義になります。

{% badge href="https://github.com/XRPLF/clio/releases/tag/2.0.0" date="February 18, 2024" %}新規: Clio v2.0.0{% /badge %}

次のように表示されます。

機能の更新の場合、新規: を 更新: に置き換えてください。例えば、次のバッジ定義となります。

{% badge href="https://github.com/XRPLF/clio/releases/tag/2.1.0" date="May 4, 2024" %} 更新: Clio v2.1.0{% /badge %}

次のように表示されます。

いくつかのフレーズは自動的にバッジの色を設定し、またcolor="purple"のような色のパラメータをタグに追加することで色を明示的に設定できます。

2年以上前の新規/更新バッジは削除するのがベストプラクティスです。

技術用語

以下の単語やフレーズを説明通りに使用してください。

Frontmatterのフィールド

Note: Realmのfrontmatter仕様の詳細は完全には文書化されていません。Realmがクローズドベータを終了したら、リンクを更新する必要があります。

MarkdownファイルのFrontmatterには、以下のような内容が含まれます。

---
metadata:
  indexPage: true # 自動生成された子ページのリストを含めたい場合、追加してください。
seo:
  description: rippledはXRP Ledgerを管理するコアとなるピアツーピアサーバです。このセクションでは、rippledサーバの基本的な機能の背景にある「要素」と「その理由」を学ぶのに役立つ概念について説明します。
---

サイト内の一部のページには、以前の(Dactyl)ツールチェーンからのメタデータが残っている場合があります。これらのフィールドは効果がないため、新しいページから省略することができます。

次へと前へのボタン

ドキュメントとブログページには、ページの下部に「次へ」ボタンと「前へ」ボタンがあります。

これらのボタンが不要な場合は、ページのfrontmatterを更新して無効にすることができます。

---
navigation:
  nextButton:
    hide: true
---

グラフィック

/docs/imgディレクトリにグラフィックを保存します。グラフィックを埋め込むには、次の構文を使用します。

![image_description](/docs/img/my_image.png)

例えば、![XRPL財団のロゴ](/docs/img/xrplf-logo.png)は次のように表示されます。

ビデオ

ビデオはYouTubeに保存されます。アップロード後、埋め込み手順をコピーしてドキュメントに貼り付けることができます。

コンテンツにYouTubeビデオを埋め込むには、次の手順に従います。

1. YouTubeにビデオをアップロードします。
2. ビデオページの共有ボタンをクリックします。
3. 埋め込むをクリックします。
4. ポップアップ右下のコピーをクリックします。
5. コンテンツに<iframe>要素を貼り付けます。

例えば、Send Checks ビデオを埋め込むためのコードは次の通りです。

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

テーブル

Markdocは、テーブルを生成するための3つの異なる構文スタイルを提供します。

ほとんどの場合、列を区切るためにパイプ文字(|)を使用し、ハイフン3つ以上(---)を使用して列ヘッダを作成します。

|          | Head 1 |
| -------  | ------ |
| Label 1  | Val 1  |

次のように表示されます。

セルの幅は同じである必要はありません。自動的に列を整列し、必要に応じてテキストを折り返します。

| 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! |

ヘッダ行にコロンを使用して、列を左寄せ(:--)、中央寄せ(:-:)、または右寄せ(--:)に配置します。

| Model | Color | Price |
| :-: | :--  | --:  |
| Protexra | Electric Blue | 50,000 XRP |
| Joatic | Hot Pink | 165,000 XRP |
| Zhanu | Neon Green | 234,000 XRP |

左の列はデフォルトで太字になります。左の列に太字のラベルを表示したくない場合は、左の列を空にして、テーブルを1列目から始めてください。

|     | French | English | German |
| --- | ---    | ---     | ---    |
|     | Fromage | Cheese | Käse |
|     | Maux d'estomac | Stomach ache | Magenschmerzen |
|     | Cornichon | Pickle | Essiggurke |

可能な限り、これらの基本的なテーブルを使用してください。上記の例で提供されていない特別なフォーマットが本当に必要な場合は、HTML構文を使用してテーブルを作成できます。

リンク

リンクは[<リンクテキスト>](<URL>)の構文を使用します。

例えば、次のように書きます。

[XRPL.org](http://xrpl.org)で世界のあらゆる問題の解決策をご覧ください。

次のように表示されます。

XRPL.orgで世界のあらゆる問題の解決策をご覧ください。

共通のリンク

共通的に引用されるページへのリンクを作成するには、{% raw-partial file="/docs/_snippets/common-links.md /%}タグをMarkdownファイルに追加し、[account_infoメソッド][]や[Paymentトランザクション][]などの参照スタイルのリンクを使用できます。common-linksファイルの内容はアルファベット順になっています。(以前はスクリプトで生成されていましたが、現在は手動で管理されています。)

サンプルコード

サンプルコードを挿入する場合は、バッククォート(`)文字でコードを囲みます。例えば:

    私のお気に入りのメソッドは`nft_info`です。

次のように表示されます。

    私のお気に入りのメソッドはnft_infoです。

長いコードブロックの場合は、言語名に続いて3つのバッククォート(```)を使用します。改行を入力し、サンプルコードを入力します。コードサンプルの最後に改行を入力し、3つのバッククォート(```)でブロックを閉じます。

例えば、

```javascript
const prepared = await client.autofill({
    "TransactionType": "Payment",
    "Account": standby_wallet.address,
    "Amount": xrpl.xrpToDrops(sendAmount),
    "Destination": standbyDestinationField.value
})
```

次のように表示されます。

  const prepared = await client.autofill({
    "TransactionType": "Payment",
    "Account": standby_wallet.address,
    "Amount": xrpl.xrpToDrops(sendAmount),
    "Destination": standbyDestinationField.value
  })

Markdocのコンポーネント

これらのファイルはMarkdocで処理されるため、{% ... %}構文で特別なタグを含めることができます。Redoclyの組み込みタグに加えて、このリポジトリには/@theme/markdoc/に定義されたいくつかのカスタムタグがあります。

バッジ

新機能をご覧ください。

部分的なコンテンツ

頻繁に使用するテキストや、ドキュメント内の複数の場所で定期的に更新が必要なテキストがある場合は、再利用のために_snippetファイルを作成できます。

_snippetディレクトリにファイルを保存します。部分的なコンテンツを挿入するには、{% partial file="<file url>" /%}構文を使用します。

例えば、次のようなスニペット/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 %}

テキストを埋め込むには、{% partial file="/docs/_snippets/secret-key-warning.md" /%}タグを使用します。

例えば、

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.

次のように表示されます。

There I was, happy as a lark, skipping through the daisies, when I shyly handed my secret key to my one true love.

注意

自分が管理していないサーバに秘密鍵を送信しないでください。暗号化されていない秘密鍵をネットワーク経由で送信しないでください。

Alas, if only I had heeded that sage advice, I would not rue the day as I do today.

Not-Enabledバッジ

Markdocコンポーネントは、その機能が本番環境のXRP Ledgerでは利用できないことを示すツールチップ付きの黄色いフラスクアイコンを表示します。投票中だが現在有効になっていない修正についての説明で使用します。例:

このタグは自己終了型で、パラメータは必要ありません。

リポジトリリンク

このタグは、通常コードサンプルである、このサイトのソースコードリポジトリの特定のファイルへのリンクを作成します。例えば、

{% repo-link path="_code-samples/build-a-desktop-wallet/js/1_ledger-index.js" %}`1-ledger-index/index.js`{% /repo-link %}

次のようになります: 1-ledger-index/index.js

サイトのフォークやブランチで作業している場合、サイト設定の変更で一度にすべてのリンクを更新できます。

試してみる

{% try-it ... /%} Markdocタグは、WebSocketツールへのリンクをボタンとして提供する便利なショートカットです。このタグは自己終了型です。

構文例:

{% try-it method="account_currencies" server="testnet" /%}

ボタンのテキストは英語では "Try it!" で、ローカライゼーションのtranslations.yamlファイルのcomponent.tryitキーを設定することで翻訳できます。

このタグは以下のパラメータを受け付けます:

serverパラメータには以下の値を指定できます。

トランザクション例

{% tx-example ... /%}Markdocタグは、特定の例示トランザクションを検索するためのボディが事前に入力されたWebSocketツールへのリンクをボタンとして提供する便利なショートカットです。このタグは自己終了型です。例として、

構文例:

{% tx-example txid="1AF19BF9717DA0B05A3BFC5007873E7743BA54C0311CCCCC60776AAEAC5C4635" /%}

ボタンのテキストは通常英語では"Query example transaction"で、ローカライゼーションのtranslations.yamlファイルのcomponent.queryexampletxキーを設定することで翻訳できます。

このタグは以下のパラメータを受け付けます。