docs: v3 documentation overhaul + review fixes#494
Merged
Conversation
Rewrites the docs around the napi-rs v3 flow — getting-started, simple-package,
release, and the concept/CLI reference — and adds new concept pages
(cargo-features, napi-attributes, type-conversions, error-handling, iterators,
manual-setup, async-concurrency, integrations, support-compatibility,
testing-debugging, troubleshooting, v2-v3-migration-guide), bringing cn/pt-BR
to parity. Generated pages/ mirrors, nav, and route map regenerated.
Review fixes applied on top of the overhaul:
- Compile-correct the Rust/TS code samples (verified against crates/napi +
examples/napi): JsNumber .to_unknown(); create_obj(&Env)+Object::new;
get_tuple_array(&Env); unsafe { as_mut() }; Rc<RefCell> WeakReference field;
get_options<'env>; @napi-rs/image .webp() and new Uint8Array(...).
- Fix dead same-language anchors by tagging target headings with explicit
{#id} (@void/md uses markdown-it-anchor's encodeURIComponent slugify, so
commas and translated headings shift the id).
- Translate the reference "JavaScript Value Reference" section and the
typed-array safety/lifetime sections into cn/pt-BR.
- Correct release npm-version prose + publish step order, add the build
--pipe flag row, fix build --bin (pt-BR), and scope the AsyncBlock feature note.
Verification: pages/content.test.ts 45/45; a slug-aware anchor check reports
zero dead same-language anchors.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9f7fcf54d2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The Chinese docs translated "target triple(s)" to 三元组/目标三元组; revert to the English term across 8 pages (+mirrors) to match the en/pt-BR convention. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
content/ is authored in Nextra-flavored MDX; convert-content.mjs strips
top-level imports and converts <Callout> to ::: containers, so
nextra-theme-docs (no longer a dependency) never reaches the served
pages/ mirrors. Remove the 110 dead `import { Callout } from
'nextra-theme-docs'` lines. Mirrors are byte-identical (content test 45/45).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
In a cn/pt-BR page, a bare `[t](/docs/x#frag)` link renders verbatim, so the browser requests `/docs/x`, which void.json rewrites `/docs/* -> /en/docs/:splat` and serves the ENGLISH page — the reader silently leaves the locale, and any translated `#fragment` is dead on the English page (8 such cases, e.g. new.cn.mdx -> /docs/cross-build#向现有项目添加新目标). Prefix every internal /docs, /blog, /changelog link in cn/pt-BR pages (content/ source + pages/ mirrors) with the file's locale. The i18n-fallback middleware serves the en page under the unchanged /<locale>/... URL when a localized page is missing, so prefixing never 404s and keeps the reader in-locale; translated fragments now resolve against the translated headings on the localized page. 194 links across 52 pages (× mirrors). A routing-aware link checker reports 0 locale leaks and 0 dead fragments; content.test.ts 45/45, docs/i18n/seo units 126/126. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ee76d631fe
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
pages/{cn,pt-BR}/docs/concepts/webassembly.md share the identical byte-0
`<script>` island shape as the already-exempted en page, but were missing from
`fmt.ignorePatterns`. Current oxfmt (vp 0.2.2) skips byte-0 island pages so it
does not corrupt them today, but the exemption keeps the list consistent across
all three locales and guards against oxfmt version drift regressing to the
documented `---`-as-thematic-break corruption. A scan confirms these were the
only two unprotected island pages.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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
1 participant
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.
What
A comprehensive v3 documentation overhaul, plus the review fixes surfaced while validating it against the real napi-rs source.
Overhaul
napi newflow.cargo-features,napi-attributes,type-conversions,error-handling,iterators,manual-setup,async-concurrency,integrations,support-compatibility,testing-debugging,troubleshooting,v2-v3-migration-guide.pages/mirrors, nav, and route map.Review fixes (applied on top)
crates/napi+examples/napi:JsNumber::to_unknown(),create_obj(&Env)+Object::new,&Envparams,unsafe { as_mut() },Rc<RefCell>WeakReference field,get_options<'env>,@napi-rs/image.webp()+new Uint8Array(...){#id}—@void/mduses markdown-it-anchor'sencodeURIComponentslugify, so commas and translated headings shift the idnpm versionpremise + publish step order, added the build--pipeflag row, fixed build--bin(pt-BR), and scoped theAsyncBlockfeature noteVerification
pages/content.test.ts— 45/45<Callout>balance, heading ids, and imports — OKRelated (separate repos, same coordinated change)
cross-flags-dx): the@napi-rs/clichanges, including anew.tsfix so a programmaticnewProject({ minNodeApiVersion: undefined })can no longer overwrite the4default and emit an invalidnapiundefinedcargo feature.wasm32-wasi-preview1-threads→wasm32-wasip1-threads.🤖 Generated with Claude Code