From 7a30d979e459bebf5e9957643e648c971c5e8eae Mon Sep 17 00:00:00 2001 From: John Wooten Date: Wed, 22 Jul 2026 04:17:41 -0400 Subject: [PATCH 1/8] =?UTF-8?q?=F0=9F=93=9D=20Update=20Anchor=20Platform?= =?UTF-8?q?=20contribution=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace obsolete versioning instructions with the current documentation, OpenAPI, OpenRPC, sidebar, and validation workflows. Co-authored-by: Codex --- .../platforms/anchor-platform/CONTRIBUTING.md | 430 ++++-------------- 1 file changed, 89 insertions(+), 341 deletions(-) diff --git a/docs/platforms/anchor-platform/CONTRIBUTING.md b/docs/platforms/anchor-platform/CONTRIBUTING.md index bf1c8dd94b..148e16f705 100644 --- a/docs/platforms/anchor-platform/CONTRIBUTING.md +++ b/docs/platforms/anchor-platform/CONTRIBUTING.md @@ -1,362 +1,110 @@ ---- -draft: true ---- - -# Welcome to Anchor Platform Madness - -Hello, and welcome to the newly versioned home of the Anchor Platform -documentation! - -We're super glad to have you here, and hopefully this document will help you -understand how (and more importantly _where_) to make the needed changes to our -documentation. Let's start off with a bit of Docusaurus vocabulary, shall we? - -## NOTICE! AP HAS BEEN DE-VERSIONED - -The Anchor Platform documentation has been de-versioned, and we're only keeping -a "current" version of the docs from now on. So, anything in this page that -references creating a new version, updating old versions, etc. can be -disregarded. - -~~However, the Anchor Platform docs _still_ remain in their own docusaurus -instance. So, information here about linking between/across instances is still -relevant. (This will not be the case forever, but for now, it is.)~~ - -It's no longer a separate plugin instance!! I'll update this doc soon, but for -now the finer points of linking can be summed up with: - -- almost always `[use a](../../relative/link.mdx)` with the file extension, - unless you're linking to/from a meeting notes document. - -## TL;DR - -- For _unreleased_ versions of Anchor Platform: - - Add and edit docs in `/platforms/anchor-platform` - - Update and regenerate API docs in `/openapi/anchor-platform/main-*.yaml` -- For _released_ versions of Anchor Platform: - - Update and change docs in `/ap_versioned_docs` - - Update and regenerate API docs in `/openapi/anchor-platform/versions/*.yaml` - -Release a **new version** using the following yarn script: - -```bash -# replace `3.0.0` with the needed version -VERSION=3.0.0 yarn ap:versions:new -``` - -> _Note:_ I think the above yarn command is currently incompatible with Windows, -> though I could be wrong. - -Regenerate API docs for **already released** versions using the following yarn -script. This regenerates API docs for **all** the released versions, so you may -want to be judicious about which files you add to your commit. - -```bash -yarn ap:versions:regen -``` - -## Table of Contents - -- [NOTICE! AP HAS BEEN DE-VERSIONED](#notice-ap-has-been-de-versioned) -- [TL;DR](#tldr) -- [More About Docusaurus than You Ever Wanted to Know](#more-about-docusaurus-than-you-ever-wanted-to-know) - - [Versions Nomenclature](#versions-nomenclature) - - [Plugins](#plugins) - - [Instances](#instances) - - [Links](#links) - - [Examples](#examples) -- [Directories to Know](#directories-to-know) - - [Directories You Already Know About](#directories-you-already-know-about) - - [New Shiny Directories](#new-shiny-directories) -- [Making New Versions](#making-new-versions) - - [Use Docusaurus to "Tag" a New Release](#use-docusaurus-to-tag-a-new-release) - - [Configure the OpenAPI plugin](#configure-the-openapi-plugin) - - [Copy the (bundled) OpenAPI Specfiles to the Versioned Directory](#copy-the-bundled-openapi-specfiles-to-the-versioned-directory) - - [Add Configuration to the OpenAPI Plugin Instance](#add-configuration-to-the-openapi-plugin-instance) -- [Updating Old Versions](#updating-old-versions) - - [Update Documentation Pages](#update-documentation-pages) - - [Update API Specification](#update-api-specification) - -## More About Docusaurus than You Ever Wanted to Know - -I know it can feel a bit mysterious, but here's some knowledge and context to -help your understanding of what's ahead. - -### Versions Nomenclature - -This is how Docusaurus defines these terms, so that's what I'll use in this -document, as well. - -- The **current version** refers to the version of the AP docs contained in the - `/platforms/anchor-platform` directory. This set of docs is available at the - `/platforms/anchor-platform/next` URL. This is the "under construction" set of - docs. - -- The **latest version** refers to the the most recently "released" set of AP - docs. These are located in `/ap_versioned_docs` (more on that later), and is - available at the `/platforms/anchor-platform` URL. This is the "stable" set of - docs. - -### Plugins - -There are two Docusaurus plugins at play here: - -1. `@docusaurus/plugin-content-docs` is the workhorse of Docusaurus. It handles - markdown rendering, routing, etc. When you think of updating `some-file.mdx`, - this is the plugin you're using. -2. `docusaurus-plugin-openapi-docs` is the plugin that is used to generate MDX - pages from the OpenAPI specfiles. This plugin is capable of versioning on its - own some some care and consideration must be taken in regards to its - configuration. - -Both of these plugin configurations have been broken out into a -`/config/anchorPlatform.config.ts` file, to ease management of them and -de-clutter somewhat the main `docusaurus.config.ts` file. - -### Instances - -This is where it gets a bit more "in the weeds," but I promise this part is -helpful to know. Both of the [plugins](#plugins) I mentioned above are really -just _instances_ of those two plugins. In fact each of those plugins is used -elsewhere in our docs site for Horizon, SDP, and just "regular" docs. It's not -_generally_ important to consider different plugin instances, but it _is_ -**quite relevant** when we discuss links. So... - -### Links - -> [!WARNING] -> -> This section is outdated. Mostly ignore it for the time-being. - -Most often, **especially in versioned docs**, it's important to -[link to other docs by _relative_ file paths](https://docusaurus.io/docs/versioning#link-docs-by-file-paths). -This lets Docusaurus rewrite URLs when necessary at build-time. - -However, there's a **BIG EXCEPTION**! Docusaurus can only handle these links -when the source and target files are both process by the same _plugin instance_. -So, in practical terms: - -- If you are linking from **and** to MDX documents _within_ the same docs plugin - instance, use _relative file_ paths. -- If you are linking _across_ plugin instances, you **must** use _URL paths_. By - convention, we use _absolute_ paths for this, too, to make it a little more - obvious when this behavior is taking place. - -#### Examples - -This should help to make it a bit clearer. - -- I want to link _from_ the MDX document - `/platforms/anchor-platform/sep-guide/sep6/configuration.mdx` _to_ the MDX - document - `/platforms/anchor-platform/api-reference/platform/rpc/methods/notify_amounts_updated.mdx`: - - We're in the same `/platforms/anchor-platform` plugin instance - - Use a **relative file** path - - Link to it - `[something like this](../../api-reference/platform/rpc/methods/notify_amounts_updated.mdx)` -- I want to link _from_ the MDX document `/docs/learn/fundamentals/anchors.mdx` - _to_ the MDX document - `/platforms/anchor-platform/admin-guide/getting-started.mdx` - - We're "crossing" between the `/docs` and `/platforms/anchor-platform` plugin - instances - - Use an **absolute URL** path - - Link to it - `[something like this](/platforms/anchor-platform/admin-guide/getting-started)` - (note that there is no `.mdx` extension) -- I want to link _from_ the MDX document `/platforms/anchor-platform/README.mdx` - _to_ the MDX document `/docs/tools/developer-tools/wallets.mdx` - - We're "crossing" between the `/platforms/anchor-platform` and `/docs` plugin - instances - - Use an **absolute URL** path - - Link to it `[something like this](/docs/tools/developer-tools/wallets)` - (note that there is no `.mdx` extension) -- Wildcard! I want to link _from_ the MDX document - `/platforms/anchor-platform/admin-guide/events/configuration.mdx` _to_ the MDX - document - `/platforms/stellar-disbursement-platform/admin-guide/60-anchor-platform-integration-points.mdx` - - We're "crossing" between the `/platforms/anchor-platform` and - `/platforms/stellar-disbursement-platform` plugin instances - - Use an **absolute URL** path - - Link to it - `[something like this](/platforms/stellar-disbursement-platform/admin-guide/anchor-platform-integration-points)` - (note that there is no `.mdx` extension) - -> _Note:_ Replace the `/platforms/anchor-platform` plugin instance with the -> `/platforms/stellar-disbursement-platform` plugin instance in the above -> examples, and it all works pretty much identically. - -Read more about links [here](https://docusaurus.io/docs/markdown-features/links) -(especially toward the bottom of the page). - -## Directories to Know - -There are a few directories that _all_ feed into the end product that is our -versioned AP documentation. - -### Directories You Already Know About - -- `/platforms/anchor-platform` This is where you are now, and traditionally has - been the place to modify any of the markdown content that becomes our AP docs - pages. Not much has changed here, except it does require a shift in mindset. - **All the documentation and content located here should now be considered the - `current` (under construction) version of AP docs.** So, as we're building for - `v3.x` (and beyond, eventually), you'll want to be updating _content here_. - Readers will still be able to _view_ this content before it's "released," but - they'll be told it's the unreleased version. - - There is also a new directory here you should know about: - - `/platforms/anchor-platform/assets` Since it's likely that the various - images, diagrams, etc. will need to update/change from one version to - another, we're co-locating the relevant assets in this directory. This - allows them to be versioned as well. If you want to update a diagram or - image for an upcoming release, you should do so here. - -- `/openapi/anchor-platform` This is the same place you're probably already - familiar with. The files have recently been renamed, but for the most part you - want to modify `main-{platform,callbacks,custody}.yaml`, which will then be - "bundled up" later into the bundled file that contains everything in one file. - **The files in this directory should also be considered the `current` (under - construction) version of AP specification docs.** So, as we're building for - `v3.x` (and beyond, eventually), you'll want to be updating _specfiles here_. - - There is also a new directory here you should know about: - - `/openapi/anchor-platform/versions` This directory stores a copy of the - _bundled_ specfiles for each version that is released. The plugin we use to - generate the API documentation for these specfiles gets configured to use - _these_ versioned specifications for all non-`current` documentation. - -- `/openrpc/src/anchor-platform` Recently, we moved the RPC specification into - this directory so it can benefit from the same build processes and validation - checks as the `stellar-rpc` specification. Similar to the other directories - covered so far, any changes to these files should be considered to be on the - `current` (under construction) version of the documentation. There's not - (yet?) a great deal of tooling or ergonomics around updating the "old" - versions of these specifications. The `current` version of the spec is - generated at - `/platforms/anchor-platform/api-reference/platform/rpc/anchor-platform.openrpc.json`. - This means it _does_ get included in the versioning process, so any changes to - "old" versions will likely just need to be made in those versioned specfiles - for now (more on that in the next section). - -### New Shiny Directories - -- `/ap_versioned_sidebars` We can pretty well breeze right past this one. When - you make a new version of the docs, Docusaurus stores a copy of the sidebar at - that point in time. You shouldn't really need to bother yourself with anything - in here. - -- `/ap_versioned_docs` This is where the "released" sets of the AP docs live. - Each time a version is released, _everything_ from within the - `/platforms/anchor-platform` directory gets copied into a subdirectory here. - You'll notice we already have a version `v2.8.4` here. As we release `v3.x`, a - _new_ copy of the files will be placed here. The `latest` (stable) copy of AP - docs are drawn from within this directory. If you come across something to fix - or update in a released version of the docs, you'll need to update accordingly - here. - -## Making New Versions - -As noted in the [TL;DR](#tldr), this process is automated with the -`VERSION=3.0.0 yarn ap:versions:new` script. However, here's what's happening -under the hood of that script. - -### Use Docusaurus to "Tag" a New Release - -It's actually pretty simple! Use the Docusaurus CLI to make a new release: - -```bash -# `ap` is the ID of the AP `@docusaurus/plugin-content-docs` plugin instance -yarn docusaurus docs:version:ap 3.0.0 +# Contributing to the Anchor Platform Documentation + +This guide supplements the repository-wide +[contribution guide](../../../CONTRIBUTING.md) with the paths and generation +steps specific to Anchor Platform documentation. + +Docusaurus excludes `**/CONTRIBUTING.md` files from the published site, so this +file is guidance for contributors browsing the repository. Anchor Platform +documentation is not separately versioned and is built by the site's main docs +plugin at `/docs/platforms/anchor-platform`. + +## Where to Make Changes + +| Content | Source | Generated output or configuration | +| ------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| Guides and landing pages | `docs/platforms/anchor-platform/**/*.mdx` | Published directly by Docusaurus | +| REST API definitions | `openapi/anchor-platform/main-platform.yaml`, `main-callbacks.yaml`, and shared YAML files | Bundled specs in `openapi/anchor-platform/bundled-*.yaml`; generated pages under `docs/platforms/anchor-platform/api-reference/` | +| Platform RPC definitions | `openrpc/src/anchor-platform/**/*.json` | `docs/platforms/anchor-platform/api-reference/platform/rpc/anchor-platform.openrpc.json` | +| RPC method pages | `docs/platforms/anchor-platform/api-reference/platform/rpc/methods/*.mdx` | Published directly by Docusaurus using the generated OpenRPC specification | +| Sidebar structure | Page and directory metadata, plus `config/anchorPlatform.sidebar.ts` | Anchor Platform sidebar on the site | + +## Edit Documentation Pages + +Edit prose in `docs/platforms/anchor-platform/`: + +- `README.mdx` is the Anchor Platform landing page. +- `admin-guide/` contains operating and configuration guidance. +- `sep-guide/` contains guidance organized by Stellar Ecosystem Proposal (SEP). +- `api-reference/` contains a mixture of generated API content and manually + maintained landing or RPC method pages. Check the file type and the workflows + below before editing it. + +Follow the repository's +[content conventions](../../../CONTRIBUTING.md#content-conventions). In +particular, link to other documentation using a path relative to the current +source file and include the `.mdx` extension: + +```md +[Anchor Platform overview](./README.mdx) +[Learn about anchors](../../learn/fundamentals/anchors.mdx) ``` -That makes a new copy of the docs in `/ap_versioned_docs`, and it will pretty -well "work" to get the new version displayed on the site. Any future changes to -the 3.0.0 version of the docs should be made within the `/ap_versioned_docs` -directory. - -### Configure the OpenAPI plugin - -We'll also want to be able to modify/update/re-generate the API documentation if -the need arises. So, we'll need to configure that -`docusaurus-plugin-openapi-docs` plugin instance accordingly. +Do not use published `/docs/...` routes for internal documentation links. +Docusaurus validates relative source links during the build. -#### Copy the (bundled) OpenAPI Specfiles to the Versioned Directory +The sidebar is autogenerated from the Anchor Platform directory. Set page +ordering and labels in MDX front matter or directory metadata; only change +`config/anchorPlatform.sidebar.ts` when the top-level sidebar structure itself +needs to change. -At the moment, it's just as simple as copying the files: +## Update the OpenAPI Reference -```bash -cp openapi/anchor-platform/bundled-platform.yaml openapi/anchor-platform/versions/platform-3.0.0.yaml -cp openapi/anchor-platform/bundled-callbacks.yaml openapi/anchor-platform/versions/callbacks-3.0.0.yaml -cp openapi/anchor-platform/bundled-custody.yaml openapi/anchor-platform/versions/custody-3.0.0.yaml -``` +The Platform API and callback API reference pages are generated. Do not edit +generated `*.api.mdx` files or their supporting generated JSON files directly. -> Notice how we're copying the _bundled_ file, not the _main_ file. This makes -> sure the versioned file contains everything it needs. +1. Edit `openapi/anchor-platform/main-platform.yaml` or `main-callbacks.yaml`, + plus `schemas.yaml` and `examples.yaml` when shared components need to + change. +2. From the repository root, rebuild all OpenAPI documentation: -#### Add Configuration to the OpenAPI Plugin Instance + ```bash + pnpm api + ``` -> _Note_: These `versions` parts of the configuration are now generated -> dynamically, using a `makeVersions()` function, so these manual config steps -> shouldn't need to be done. You _may_ want to advance/adjust the -> `anchorPlatformNextVersion` string in the config file, when you release a new -> version of docs, though. +3. Review the diff. Commit the source YAML, updated `bundled-*.yaml` + specifications, and corresponding generated files together. Investigate + unrelated generated changes instead of including them automatically. -In order to be able to use the plugin's CLI to update already-released versions, -we have to update the configuration in `/config/anchorPlatform.config.ts`. Make -a new entry in each of the specfiles' `versions` object, and copy the formatting -of the entries already there. For reference, here's what it currently looks like -for the "platform server" in `v2.8.4`: +The OpenAPI configuration and source-to-output mappings live in +`docusaurus.config.ts`; the Redocly entry points live in `redocly.yaml`. -```typescript -ap_platform: { - specPath: "openapi/anchor-platform/bundled-platform.yaml", - outputDir: "platforms/anchor-platform/api-reference/platform/transactions", - hideSendButton: true, - template: "src/template.mustache", - version: "3.0.0", - label: "v3.0.0", - baseUrl: '/platforms/anchor-platform/next/api-reference/platform/transactions', - versions: { - "2.8.4": { - specPath: "openapi/anchor-platform/versions/platform-2.8.4.yaml", - outputDir: "ap_versioned_docs/version-2.8.4/api-reference/platform/transactions", - label: "v2.8.4", - baseUrl: "/platforms/anchor-platform/api-reference/platform/transactions" - } - } -} -``` +## Update the Platform RPC Reference -## Updating Old Versions +The Platform RPC specification is assembled from the JSON files in +`openrpc/src/anchor-platform/`. Do not edit generated `*.openrpc.json` files +directly. -### Update Documentation Pages +1. Edit the appropriate source files under `contentDescriptors/`, `examples/`, + `methods/`, or `schemas/`. +2. If you add or remove a method, also add or remove its MDX page under + `docs/platforms/anchor-platform/api-reference/platform/rpc/methods/`. These + small pages select a method from the generated specification and render it + with the `RpcMethod` component. +3. Build and validate the OpenRPC specifications: -Let's say I find a misspelling in the `v2.8.4` Admin Guide documentation. Find -the relevant file in the `/ap_versioned_docs/version-2.8.4` directory, fix it -and commit. Content updates are pretty easy here. + ```bash + pnpm rpcspec:validate + ``` -> _Note_ Since the RPC specification is treated similar to the MDX docs, use the -> same process to make updates to the RPC specfile. For `v2.8.4`, it's located -> here: -> `/ap_versioned_docs/version-2.8.4/api-reference/platform/rpc/anchor-platform.openrpc.json` +4. Commit the OpenRPC source changes, any method-page changes, and the + regenerated + `docs/platforms/anchor-platform/api-reference/platform/rpc/anchor-platform.openrpc.json` + together. -### Update API Specification +See [`openrpc/README.md`](../../../openrpc/README.md) for the OpenRPC object +structure and `$ref` conventions. -This is a little more involved, but not much. Find and change the relevant -part(s) of the -`/openapi/anchor-platform/versions/{platform, callbacks,custody}-2.8.4.yaml` -specfile. +## Validate the Changes -Then, regenerate the MDX pages: +Run the checks relevant to your change from the repository root: ```bash -# `ap-apis` is the ID of the AP `docusaurus-plugin-openapi-docs` plugin instance -yarn docusaurus gen-api-docs:version -p ap-apis:2.8.4 +pnpm check:mdx # Markdown and MDX formatting +pnpm api # Required after OpenAPI source changes +pnpm rpcspec:validate # Required after OpenRPC source changes +pnpm build # Full site build and internal-link validation ``` -> _Note:_ You can use a yarn script to automatically regenerate API docs for -> **all** released versions: `yarn ap:versions:regen`. This does indeed -> regenerate all versions, so you may want to be choosy about which files you -> add to the commit. - -Commit the changes, and you're off to the races. +Before committing generated documentation, inspect `git diff` and make sure the +change contains its source files and only the expected generated output. From ef2fe5cb6633043605448fbb526be27e19308c8e Mon Sep 17 00:00:00 2001 From: John Wooten Date: Wed, 22 Jul 2026 04:18:47 -0400 Subject: [PATCH 2/8] =?UTF-8?q?=F0=9F=93=9D=20Refine=20Anchor=20Platform?= =?UTF-8?q?=20guide=20title?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use a more formal heading for the Anchor Platform documentation contribution guide. Co-authored-by: Codex --- docs/platforms/anchor-platform/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/anchor-platform/CONTRIBUTING.md b/docs/platforms/anchor-platform/CONTRIBUTING.md index 148e16f705..07944d6acb 100644 --- a/docs/platforms/anchor-platform/CONTRIBUTING.md +++ b/docs/platforms/anchor-platform/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to the Anchor Platform Documentation +# Anchor Platform Documentation Contribution Guide This guide supplements the repository-wide [contribution guide](../../../CONTRIBUTING.md) with the paths and generation From 181b32019096f069ec5a09e493367a5492dbcc71 Mon Sep 17 00:00:00 2001 From: John Wooten Date: Wed, 22 Jul 2026 06:41:58 -0400 Subject: [PATCH 3/8] Update CONTRIBUTING.md for Anchor Platform Clarify that the CONTRIBUTING.md file is for repository browsing only and not published. --- docs/platforms/anchor-platform/CONTRIBUTING.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/platforms/anchor-platform/CONTRIBUTING.md b/docs/platforms/anchor-platform/CONTRIBUTING.md index 07944d6acb..fc57d829a7 100644 --- a/docs/platforms/anchor-platform/CONTRIBUTING.md +++ b/docs/platforms/anchor-platform/CONTRIBUTING.md @@ -4,11 +4,6 @@ This guide supplements the repository-wide [contribution guide](../../../CONTRIBUTING.md) with the paths and generation steps specific to Anchor Platform documentation. -Docusaurus excludes `**/CONTRIBUTING.md` files from the published site, so this -file is guidance for contributors browsing the repository. Anchor Platform -documentation is not separately versioned and is built by the site's main docs -plugin at `/docs/platforms/anchor-platform`. - ## Where to Make Changes | Content | Source | Generated output or configuration | From 12e7f08c47662a127918fdc7fabd2617fe37d46d Mon Sep 17 00:00:00 2001 From: John Wooten Date: Wed, 22 Jul 2026 06:53:20 -0400 Subject: [PATCH 4/8] Update linking guidelines in CONTRIBUTING.md Clarify linking guidelines for internal and external links. --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60a66d10a2..1d84dcffaf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,7 @@ A husky pre-commit hook runs the prettier check; if it fails, run `pnpm format:m ### Links - **Internal links are relative file paths, including the `.mdx` extension**: `[fees](../../learn/fundamentals/fees-resource-limits-metering.mdx#inclusion-fee)`. Docusaurus resolves these at build time, so a broken path fails the build instead of shipping a 404. + - _Exception:_ **Across plugin instances, use an absolute URL path.** For example, a page in the main docs linking to a meeting should use `[discussion](/meetings/2024/06/27)`. Docusaurus cannot resolve relative file paths between here. - Section index pages live at `parent/README.mdx` — if you're linking to a subsection's landing page, that's usually the file you want. - External links to other Stellar properties use `https://stellar.org/...` (no `www`). From 0ad69432e797e89f0f08aa2810872fdd2185efe6 Mon Sep 17 00:00:00 2001 From: John Wooten Date: Wed, 22 Jul 2026 07:05:47 -0400 Subject: [PATCH 5/8] Rename API reference section in CONTRIBUTING.md Updated the section title for API reference pages in the contributing guidelines to improve clarity. --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d84dcffaf..0d5cec9743 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ Before diving in, please read the org-wide [Stellar Contribution Guide](https:// - [Code examples](#code-examples) - [Terminology and style](#terminology-and-style) - [Site Code and Infrastructure](#site-code-and-infrastructure) - - [API reference pages are generated](#api-reference-pages-are-generated) + - [API reference pages are generated](#api-pages) - [URLs are forever](#urls-are-forever) - [Patches and swizzles are a last resort](#patches-and-swizzles-are-a-last-resort) - [Tooling, editor config, and build settings](#tooling-editor-config-and-build-settings) @@ -89,6 +89,8 @@ A husky pre-commit hook runs the prettier check; if it fails, run `pnpm format:m The bar for changes to the site itself (components, theme, config, dependencies) is deliberately higher than for content. + + ### API reference pages are generated The Horizon, Anchor Platform, and Stellar Disbursement Platform API reference pages are generated from the OpenAPI specs in `openapi/`. **Edit the spec sources, then regenerate** (`pnpm api`) and commit both together. PRs that hand-edit generated `*.api.mdx` files will be closed — the next regeneration would erase them. From 339cf1c49f774f9433d3e29c6552b939d1986cb6 Mon Sep 17 00:00:00 2001 From: John Wooten Date: Wed, 22 Jul 2026 07:07:00 -0400 Subject: [PATCH 6/8] Update section headers in CONTRIBUTING.md --- docs/platforms/anchor-platform/CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/platforms/anchor-platform/CONTRIBUTING.md b/docs/platforms/anchor-platform/CONTRIBUTING.md index fc57d829a7..5becc54d63 100644 --- a/docs/platforms/anchor-platform/CONTRIBUTING.md +++ b/docs/platforms/anchor-platform/CONTRIBUTING.md @@ -43,7 +43,9 @@ ordering and labels in MDX front matter or directory metadata; only change `config/anchorPlatform.sidebar.ts` when the top-level sidebar structure itself needs to change. -## Update the OpenAPI Reference +## Compilation Generally + +### Update the OpenAPI Reference The Platform API and callback API reference pages are generated. Do not edit generated `*.api.mdx` files or their supporting generated JSON files directly. @@ -64,7 +66,7 @@ generated `*.api.mdx` files or their supporting generated JSON files directly. The OpenAPI configuration and source-to-output mappings live in `docusaurus.config.ts`; the Redocly entry points live in `redocly.yaml`. -## Update the Platform RPC Reference +### Update the Platform RPC Reference The Platform RPC specification is assembled from the JSON files in `openrpc/src/anchor-platform/`. Do not edit generated `*.openrpc.json` files @@ -90,7 +92,7 @@ directly. See [`openrpc/README.md`](../../../openrpc/README.md) for the OpenRPC object structure and `$ref` conventions. -## Validate the Changes +### Validate the Changes Run the checks relevant to your change from the repository root: From dcfa71d9088018b9b13b8a07a58c6f1f52215017 Mon Sep 17 00:00:00 2001 From: John Wooten Date: Mon, 27 Jul 2026 12:25:23 -0400 Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=A7=B9=20Remove=20unnecessary=20contr?= =?UTF-8?q?ibution=20guide=20changes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Codex --- CONTRIBUTING.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0d5cec9743..60a66d10a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ Before diving in, please read the org-wide [Stellar Contribution Guide](https:// - [Code examples](#code-examples) - [Terminology and style](#terminology-and-style) - [Site Code and Infrastructure](#site-code-and-infrastructure) - - [API reference pages are generated](#api-pages) + - [API reference pages are generated](#api-reference-pages-are-generated) - [URLs are forever](#urls-are-forever) - [Patches and swizzles are a last resort](#patches-and-swizzles-are-a-last-resort) - [Tooling, editor config, and build settings](#tooling-editor-config-and-build-settings) @@ -59,7 +59,6 @@ A husky pre-commit hook runs the prettier check; if it fails, run `pnpm format:m ### Links - **Internal links are relative file paths, including the `.mdx` extension**: `[fees](../../learn/fundamentals/fees-resource-limits-metering.mdx#inclusion-fee)`. Docusaurus resolves these at build time, so a broken path fails the build instead of shipping a 404. - - _Exception:_ **Across plugin instances, use an absolute URL path.** For example, a page in the main docs linking to a meeting should use `[discussion](/meetings/2024/06/27)`. Docusaurus cannot resolve relative file paths between here. - Section index pages live at `parent/README.mdx` — if you're linking to a subsection's landing page, that's usually the file you want. - External links to other Stellar properties use `https://stellar.org/...` (no `www`). @@ -89,8 +88,6 @@ A husky pre-commit hook runs the prettier check; if it fails, run `pnpm format:m The bar for changes to the site itself (components, theme, config, dependencies) is deliberately higher than for content. - - ### API reference pages are generated The Horizon, Anchor Platform, and Stellar Disbursement Platform API reference pages are generated from the OpenAPI specs in `openapi/`. **Edit the spec sources, then regenerate** (`pnpm api`) and commit both together. PRs that hand-edit generated `*.api.mdx` files will be closed — the next regeneration would erase them. From e8fa4b0f9b9a61a605f21c72d2312ebab2d115ef Mon Sep 17 00:00:00 2001 From: John Wooten Date: Mon, 10 Aug 2026 04:58:03 -0400 Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=93=9D=20Document=20specification=20l?= =?UTF-8?q?ink=20exception?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Codex --- docs/platforms/anchor-platform/CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/platforms/anchor-platform/CONTRIBUTING.md b/docs/platforms/anchor-platform/CONTRIBUTING.md index 5becc54d63..26b3a4fec2 100644 --- a/docs/platforms/anchor-platform/CONTRIBUTING.md +++ b/docs/platforms/anchor-platform/CONTRIBUTING.md @@ -36,7 +36,10 @@ source file and include the `.mdx` extension: ``` Do not use published `/docs/...` routes for internal documentation links. -Docusaurus validates relative source links during the build. +Docusaurus validates relative source links during the build. Links embedded in +specifications under `openapi/` or `openrpc/` are the exception: use full +`https://developers.stellar.org/...` URLs so external spec consumers can resolve +them. The sidebar is autogenerated from the Anchor Platform directory. Set page ordering and labels in MDX front matter or directory metadata; only change