Migrate curated Hiro docs into Stacks docs#1847
Conversation
|
54 files 😭 I'll start picking away @huth-stacks |
Ah fyi I added you too early maybe? I don’t think it’s ready for a review until he promotes from draft. Sorry! |
totally fine! better to start checking early when there are this many files |
|
@wileyj i am happy to decompose this into many section by section PRs for you as well. My goal is to make this as painless as possible |
|
I discussed with @wileyj today and confirmed that this effort should be focused on migration rather than page-level accuracy auditing for this pass, but @huth-stacks we should still glance through these to sanity check the content, even if the top-level goal is just getting them into the appropriate information architecture locations for the Stacks docs. |
alexis-stacks
left a comment
alexis-stacks
left a comment
There was a problem hiding this comment.
Overall, top-level comments:
- The very small sections with surgical edits are fine and good (Operate, Press, Tutorials)
- The two larger sections, Build and Reference, both need substantial and targeted reworks. I left smaller comments throughout. Many pages are destructively edited compared to Hiro docs pages and its unclear how much of that was intentional.
- More thought needs to go into how the Hiro docs should be structured in the information architecture context of the Stacks docs. Many of these pages made more sense in the Hiro-specific docs context and probably require a different containment level to avoid confusing readers.
- OpenAPI specs for any migrated APIs need to be uploaded through Gitbook (or otherwise pointed at a live source via Gitbook) and properly referenced by name on the API page so that the full references are available in Stacks docs.
- We should have a plan for the docs pages that refer to deprecated services which is better than consignment to the void. Or at least we should consider that before consigning them to the void.
- Claude skipped some guides entirely and skipped or badly truncated some content on other pages.
My recommendation here is to go back to the drawing board and make a more intentional plan that we do (and review) section by section from the existing Hiro Docs.
There was a problem hiding this comment.
Please do a thorough audit of the Chainhooks section as a whole vs the Hiro docs. I noticed that there are some key differences between this and the overview provided in the Hiro docs. The Hiro docs organized these sections differently and included a few files or retitled sections (introduction, replay -> evaluate) that aren't present in the Stacks docs version.
- The naming is inconsistent: We call this section "Chainhooks" at the top level but later "the Chainhooks SDK" or "The Hiro Chainhooks SDK"--Hiro treats these as different concepts and differentiates the concept of Chainhooks from the SDK as a means for interacting with them, and also explains that the platform can serve as the visual representation. This nuance is more buried in the Stacks docs.
- The overview on Hiro contains useful context that isn't present on the Stacks rewrites about v1 vs v2 and the purpose and identity of Chainhooks, which serve to orient new users on what these are and differentiate the already confusing legacy chainhooks (which had two versions) from the new ones.
- The introduction appears to have been reframed as a "quickstart" and it's unclear exactly how much rewrite happened.
- Some pages have key information missing or re-contextualized in a way that doesn't make sense.
If this is all Claude auto-formatting, I'd rather pull these pages over in a form closer to their current state and do a targeted recomposition later with a careful rewrite, because we know that the Hiro docs were structured with intent.
I had Claude do a quick comparison pass on the Chainhooks section port and it flagged a number of potential issues (more in the full pass, so don't just take this summary please):
Summary: What to Flag in Review
Likely mistakes:
- Migration mapping table: "v2 handles secrets automatically" → "Delivery target stays the same" — changed the
meaning of migration guidance- FAQ question swap: "Can I test locally?" replaced with a different question rather than updated — the original answer ("no, working on it") was presumably still accurate or should have been removed, not rewritten as a different Q&A
Significant content loss (worth pushing back on):
3. reference/filters.md — 9 missing code examples for mint/burn variants, sender/receiver filters, and tenure_change
extended. The table promises these filters exist but there are no examples showing how to use them.
4. reference/payload-anatomy.md — JSON examples gutted to the point of limited reference value. Developers won't know
what fields to expect in webhook payloads.
5. reference/options.md — Per-option documentation and 7 code examples dropped.Minor but worth noting:
6. update.md dropped the ❌ anti-pattern example — that was pedagogically useful
7. create.md dropped the "(maximum 200)" bulk UUID limit
8. quickstart.md dropped the TypeScript types section
9. secrets.md dropped server.listen() from the Fastify example
There was a problem hiding this comment.
I noticed that the Bitcoin Indexer is omitted entirely, but the Hiro docs state that, while updates will cease, it's going to continue to be open sourced. Should we try to preserve that documentation somewhere rather than just not porting it over? I think it's worth thinking about that a bit more.
Same question for ordinals and runes. I think we should examine what's available in those GitHub repos before we decide that those docs should be omitted entirely.
Same question for the platform API. Are we no longer making that available? If we want to migrate all the Hiro docs and we're still going to allow people to interact with that API, I don't think we should cut it.
There was a problem hiding this comment.
Claude punted on translating this entirely. It literally just describes it as a placeholder. Additionally, I don't think this guide fits with this section.
See: https://docs.hiro.so/en/resources/guides/build-a-decentralized-kickstarter
Probably a better fit for tutorials or cookbook.
There was a problem hiding this comment.
This guide truncates the intro in a way that makes it harder to understand what it's doing compared to the Hiro equivalent. Also, probably belongs in tutorials or cookbook rather than build.
https://docs.hiro.so/en/resources/guides/build-an-nft-marketplace
There was a problem hiding this comment.
Same comment here. Wrong location. Claude got lazy with the summary.
There was a problem hiding this comment.
Contract monitoring as a concept probably doesn't belong as a top-level tool under "build" in the Stacks docs because of its close association with the Hiro platform. Most likely we should create a "Hiro platform" top-level subject area for platform features that will continue to be supported and find the right place to put that in the docs.
Subtle word changes are noted across both contract monitoring files--please confirm that these are intentional and non-destructive for the port.
There was a problem hiding this comment.
The ordering of these sections is going to be extremely confusing for people who aren't interested in the Hiro-specific APIs but are just trying to look for the Stacks node RPC documentation or some of the other non-Hiro APIs, which don't require Hiro API keys. We don't elaborate on the applicable APIs in the sections where rate limits and keys are discussed, nor do we make it clear that response headers are specific to Hiro-owned API calls, and the Hiro-specific sections are inserted partway down the list.
These are more properly cordoned off in a Hiro or platform-specific section where we discuss what they apply to rather than making them generic top-level sections that appear before the RPC section. I'd recommend that we keep the notices about which APIs are owned by Hiro in the overviews, but co-locate them in their own section so that it's clear that these are more tertiary APIs and it's easier to visibly scan the left side menu.
| kind: openapi | ||
| spec: stacks-blockchain-api-dereferenced | ||
| ``` | ||
| * [Chainhooks API](api/chainhooks-api/README.md) |
There was a problem hiding this comment.
All three of these API sections lack the OpenAPI spec that they have on the Hiro site which provides the detailed API call references. These need to be added before these sections can be considered complete.
There was a problem hiding this comment.
Wording differs and limits are not provided in the Migrated Doc.
There was a problem hiding this comment.
Wording differs arguably destructively.
3 participants
Summary
This PR migrates the approved Hiro documentation into first-class Stacks docs locations and removes the need to send users to separate Hiro-hosted docs for the covered topics.
The migration is GitBook-native:
docs/reference/SUMMARY.md./hirosubtree.What Changed
docs/buildThis PR adds a new first-class
Chainhookssection to the build space.New pages:
docs/build/chainhooks/overview.mddocs/build/chainhooks/quickstart.mddocs/build/chainhooks/create.mddocs/build/chainhooks/fetch.mddocs/build/chainhooks/update.mddocs/build/chainhooks/evaluate.mddocs/build/chainhooks/secrets.mddocs/build/chainhooks/faq.mddocs/build/chainhooks/migration.mddocs/build/chainhooks/reference/README.mddocs/build/chainhooks/reference/filters.mddocs/build/chainhooks/reference/options.mddocs/build/chainhooks/reference/payload-anatomy.mdThis PR also adds a new first-class
Contract Monitoringsection to the build space.New pages:
docs/build/contract-monitoring/README.mddocs/build/contract-monitoring/create-alert.mdThis PR adds selected Hiro guides into
More Guides.New pages:
docs/build/more-guides/build-an-nft-marketplace.mddocs/build/more-guides/build-a-decentralized-kickstarter.mddocs/build/more-guides/no-loss-lottery.mddocs/build/more-guides/using-clarity-values.mdThis PR updates existing Stacks build pages so they point to the newly migrated Hiro content instead of old external docs.
Updated pages:
docs/build/SUMMARY.mddocs/build/get-started/clarity-crash-course.mddocs/build/get-started/create-a-token/fungible-tokens.mddocs/build/get-started/create-a-token/non-fungible-tokens.mddocs/build/get-started/developer-quickstart.mddocs/build/get-started/path-to-production.mddocs/build/stacks-devtools-catalog.mdThis PR also fixes existing broken links in user-facing build pages that were outside the imported Hiro content itself.
Broken-link cleanup in build:
docs/build/README.mddocs/build/more-guides/bridging-usdcx.mddocs/build/more-guides/sbtc/sbtc-builder-quickstart.mddocs/referenceThis PR adds shared Hiro API guidance pages at the root of the API reference section.
New pages:
docs/reference/api/api-keys.mddocs/reference/api/rate-limits.mddocs/reference/api/response-headers.mdThis PR adds a first-class
Stacks Blockchain APIsection to the reference space, following the GitBook pattern already used in the repo for other APIs.New pages:
docs/reference/api/stacks-blockchain-api/README.mddocs/reference/api/stacks-blockchain-api/usage.mddocs/reference/api/stacks-blockchain-api/architecture.mddocs/reference/api/stacks-blockchain-api/pagination.mddocs/reference/api/stacks-blockchain-api/nonce-handling.mddocs/reference/api/stacks-blockchain-api/requesting-proofs.mddocs/reference/.gitbook/assets/stacks-blockchain-api-architecture.svgThis PR adds a first-class
Chainhooks APIsection.New pages:
docs/reference/api/chainhooks-api/README.mddocs/reference/api/chainhooks-api/usage.mdThis PR adds a first-class
Token Metadata APIsection.New pages:
docs/reference/api/token-metadata-api/README.mddocs/reference/api/token-metadata-api/usage.mdThis PR adds a first-class
Signer Metrics APIsection.New pages:
docs/reference/api/signer-metrics-api/README.mddocs/reference/api/signer-metrics-api/usage.mdThis PR updates the existing Node RPC page to better distinguish the self-hosted Node RPC API from the Hiro-hosted indexed Stacks Blockchain API.
Updated pages:
docs/reference/SUMMARY.mddocs/reference/api/stacks-node-rpc/README.mdThis PR also fixes existing broken links in older reference landing and rollout pages.
Broken-link cleanup in reference:
docs/reference/README.mddocs/reference/node-operations/signer-configuration.mddocs/reference/nakamoto-upgrade/nakamoto-rollout-plan/nakamoto-for-exchanges.mddocs/operateThis PR updates the signer monitoring guide to point readers to the new Signer Metrics API reference.
Updated pages:
docs/operate/run-a-signer/how-to-monitor-signer.mddocs/tutorialsThis PR fixes the broken landing card link for the Bitcoin Primer tutorial.
Updated pages:
docs/tutorials/README.mddocs/press-and-reportsThis PR fixes broken monthly index links in the press-and-top-links archives.
Updated pages:
docs/press-and-reports/press-and-top-links/2024/README.mddocs/press-and-reports/press-and-top-links/2025/README.mdContent Treatment
This migration is not a raw dump of the Hiro docs repo.
The content in this PR was curated and normalized for GitBook:
hiro.soruntime endpoints were retained where they are still the current product endpoints.stx-labsor@stacksdestinations where those moves are already live./broken/pages/...GitBook placeholders were replaced with live destinations where the correct targets could be identified confidently.Deliberately Excluded
This PR does not migrate everything from Hiro docs.
Deliberately excluded from this PR:
The excluded items were left out on purpose because they are deprecated, deferred, already covered elsewhere in Stacks docs, or are intended to be handled outside the repo through GitBook translations.
GitBook / OpenAPI Notes
This PR adds GitBook OpenAPI entries for the following Hiro API sections:
stacks-blockchain-api-dereferencedchainhooks-apitoken-metadata-apisigner-metrics-apiThe Stacks Blockchain API content follows the existing baseline established in #1845.
Before merge, GitBook admins should verify that the referenced spec IDs are registered and rendering correctly in the preview for:
chainhooks-apitoken-metadata-apisigner-metrics-apiPreview / Review Guidance
GitBook revision previews are available on this PR for the affected spaces:
docs/builddocs/referencedocs/operateThe fastest review path is:
Follow-Up Work
Follow-up work that is intentionally not part of this PR:
Validation
Manual validation completed for this branch:
/hirosubtree./broken/pages/...placeholders in the edited pages were removed.docs.hiro.sowhere an in-site replacement now exists.docs/build,docs/reference, anddocs/operate.