🔄 Refresh Anchor Platform contributing guide - #2671
Open
JFWooten4 wants to merge 7 commits into
Open
Conversation
Replace obsolete versioning instructions with the current documentation, OpenAPI, OpenRPC, sidebar, and validation workflows. Co-authored-by: Codex <noreply@openai.com>
Use a more formal heading for the Anchor Platform documentation contribution guide. Co-authored-by: Codex <noreply@openai.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Refreshes the Anchor Platform contributor guide to match current documentation workflows.
Changes:
- Removes obsolete versioning guidance.
- Documents OpenAPI/OpenRPC generation and validation.
- Clarifies source paths, generated files, links, and sidebar configuration.
Recommendation: NEEDS-CHANGES — document the full-URL exception for links embedded in OpenAPI/OpenRPC specifications.
Comment on lines
+43
to
+44
| Do not use published `/docs/...` routes for internal documentation links. | ||
| Docusaurus validates relative source links during the build. |
Clarify that the CONTRIBUTING.md file is for repository browsing only and not published.
Clarify linking guidelines for internal and external links.
Updated the section title for API reference pages in the contributing guidelines to improve clarity.
ElliotFriend
requested changes
Jul 22, 2026
ElliotFriend
left a comment
ElliotFriend
left a comment
Contributor
There was a problem hiding this comment.
this is a really nice update to this doc! thanks for submitting it
| ### 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. |
Contributor
There was a problem hiding this comment.
good addition!
Suggested change
| - _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. | |
| - _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 different plugins. |
Contributor
Author
There was a problem hiding this comment.
I explicitly removed the plugin distinction because it wasn't entirely clear to me. Starting off my edits, I really didn't know what plugins were. And the way this was originally framed made it sound like the docs subfolders were all different, which they aren't.
Suggested change
| - _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. | |
| - _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 root sections. |
Co-authored-by: Codex <noreply@openai.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This guide has been out of date for at least 7 months, so I'm giving it a quick refresh. It starts the process of consolidating nested contributor guides scattered throughout the docs. This came up in #2386 (comment) where the dissemination caused confusion on what practices were documented or not.