Keep port documentation specific to its language - #49
Merged
Merged
Conversation
why: A Go article hid foreign code while retaining other languages' headings, API descriptions and caveats. Exported Markdown disagreed with rendered pages, and nearby working trees could change source examples. what: - Select complete prose regions before rendering, linking and exports - Curate shared library articles and preserve native guide equivalents - Bind cached examples and native guides to their documented revisions - Check language isolation, root backlinks and executable Go examples
why: Curated port pages exposed nested API names and missing transport guide destinations. what: - Match qualified nested APIs and leave known ambiguous names plain - Correct source and testing-package references - Route transport guides to each native execution guide
Replace inherited tmuxp examples on seven command pages with native commands and pinned source links. Verify the documented commands and failure handling against all seven native CLIs on isolated sockets. Refresh the Go model to the documented CLI revision. Limit docs.json output checks to the selected port and fail on malformed build defaults. Validation: outer checks pass in 32.30s; 77 native commands and 28 negative checks pass. Full publication and broader workspace curation remain in progress.
why: Native workspace readers inherited tmuxp instructions and historical comparisons instead of instructions for the CLI they selected. what: Curate configuration, installation, automation and command pages per port; link reproducible source checkouts; exercise documented commands and real tmux configuration, including failure cases.
tony
force-pushed
the
port-specific-docs
branch
from
September 29, 2026 02:26
9e67c77 to
1539597
Compare
why: Markdown-like Scala calls were rewritten as links inside examples. what: - Rewrite parsed Markdown links without touching code spans or fences - Cover Scala generic calls, definitions, images, and relative links Verification: focused staging checks and the outer suite passed; the previous regex fails the code-preservation negative controls.
why: A port reader should search that language before broadening scope. what: - Scope modal and standalone search to the current port - Keep explicit scope through empty results and asynchronous queries - Reject non-port routes when deriving search links Verification: outer suite passed in 34.94 seconds; delayed inventory and result negative controls prevent stale requests from replacing UI.
why: Native references from older source revisions lacked the shared shell, theme preferences diverged, and Furo covered the port menu. what: - Apply the Sphinx shell adapter during assembly and scope search metadata - Share Astro and native theme preferences in both navigation directions - Keep the native menu above Furo content and search within its port - Exercise desktop, tablet, phone, keyboard, and theme behavior Verification: outer suite passed in 34.94 seconds; assembled output has 1571 passing tests and one stable-reference skip. All 15473 pages and 2724729 links passed assembly checks. Browser menu and theme negative controls reproduce the previous failures.
why: Astro replaces root attributes during client navigation without
rerunning the inline enhancement script. API links then exposed
the entire mobile tree while hiding both drawer controls.
what:
- Restore the API navigation flag when initializing the current page.
- Center the documentation disclosure row above its separator.
- Exercise real Lua API navigation and Back in the routine browser gate.
- Check closing controls, scroll restoration, and desktop resizing.
validation: pnpm test passes in 58.73s. Removing the restoration line
fails the new 688px check. Full latest assembly checks 15,473 pages and
2,724,729 links with zero broken links. Independent browser review
passes 33 cases across widths, themes, navigation, and no-JS fallback.
No generated reference data changed.
why: The native Python reference inserted its shared header after the article was visible. Cold loads shifted the content by 49 pixels on desktop and 177 pixels on phones. what: - Render the existing shell's header, footer and styles during assembly with the catalog-pinned Happy DOM dependency and no network requests. - Enhance the initial navigation without replacing it, preserving the insertion fallback for previously published native references. - Exercise delayed script loading, stable article geometry, version controls and no-JavaScript navigation in the routine browser gate. verification: Outer passes in 49.55 seconds. Independent cold, throttled and delayed-script loads report CLS 0 at 1440, 688 and 390 pixels. Removing the initial header or styles fails the new regression check. Regenerated native output passes controls and theme checks; the complete preview has 15,473 pages and 2,726,643 links with no broken targets.
why: The native header gave its language list a zero flex basis. At intermediate widths, fixed controls squeezed thirteen links into a tall column above the article. what: - Reserve a useful flex basis so controls wrap before language links collapse, while retaining every port and existing phone layout. - Check visible, unobscured links and a compact language list before enhancement, including no-JavaScript navigation and 768px coverage. verification: Outer passes in 50.73 seconds. Independent light/dark and JavaScript/no-JavaScript checks pass sixteen browser cases. The header is 86px tall at 688px and 768px, with phone and desktop heights unchanged. Measured layout shift remains zero. Restoring the old flex basis fails the new regression check.
why: Kotlin and Scala share the Java repository, so their GitHub buttons opened the parent repository instead of the documented library. what: - Record each wrapper's source directory separately from its repository identity, preserving checkout and publishing ownership. - Use that directory for the library button and footer, preferring an explicit source revision, then a release tag or default branch. - Pass the homepage's selected version and source into its library links. verification: Outer passes in 54.27 seconds; assembled wrapper checks and browser checks pass at desktop and phone widths, including no-JS. Independent browser checks confirm both links and preserve Java URLs. Real tag and source-pinned alias builds resolve the expected directories. Removing the directory metadata makes both regression cases fail.
why: Publication checks must accept each wrapper library directory and reject links to unrelated trees. what: - Match wrapper footer links against their declared repository and path. - Keep repository-root links valid for core and companion products. - Exercise branch, tag, revision, wrong-directory, and wrong-owner cases.
why: Source inclusions and wrapped snippet tests can hide the imports, setup, or entry point missing from a reader's copied program. what: - Require complete programs with visible dependencies and run commands - Verify the exact displayed bytes at their documented source revision - Put comments above code and wrap them at 80 columns - Keep long attribution links outside code blocks Reviewed the policy against the renderer and existing example checks.
why: Baseline cached staging compared old guide artifacts with the new publication source before that source had been exported. what: - Exclude the selected publication port from baseline cached staging - Retain strict source checks on the later fresh export - Reject explicit cached staging of the selected port - Exercise Ruby, Lua, and Kotlin through real CLI fixtures The three regression fixtures fail when the exclusion is removed.
why: Preview assemblies prepend pr-N to each page path. The footer check consequently mistook the locale for the port and rejected valid Kotlin and Scala source directories. what: - Strip the preview prefix before resolving the library - Check allowed and rejected targets in root and preview paths - Verify 11 focused cases and a failing removal control - Pass the outer gate in 48.51 seconds; hosted assembly remains pending
why: Extracted snippets omitted imports, entry points, and setup. Shared capture examples and their citations also obscured the tmux workflow. what: - Give the root capture page a complete shell program and compact links - Put eight complete native programs in their own port routes - Include imports, dependency files, run commands, and server cleanup - Complete the Java, .NET, and C++ workspace consumer programs - Protect executed source bytes through HTML and Markdown rendering - Enforce short capture comments and describe source checks accurately Native runs exercise exact displayed programs at their pinned revisions. Import/setup and runtime negatives fail as expected. The shell and C++/.NET/Swift capture programs pass on tmux 3.2a and 3.7c; the other capture programs run on 3.7c. All three workspace programs pass on both. Browser checks compare copied content and inspect desktop/phone layout. The combined outer gate passes in 49.41 seconds. Full publication remains separate.
why: Publication CI caught example project filenames misclassified as API references after the outer development gate had passed. what: - Run the existing API-link checker in medium and outer gates - Remove redundant filename mentions and retain the named code blocks - Regenerate the mention index without those local project references The full API-link check passes across 403 pages. The new gate uses the existing checked-in inputs and performs no fetch or site assembly.
why: Go and TypeScript session creation can start a daemon and then fail while fetching its snapshot. Registering cleanup after the call leaked that daemon and removed its socket directory. what: - Establish cleanup before session creation in the Go program - Check TypeScript's private socket even when creation throws - Preserve operation and cleanup errors together - Keep the endpoint reachable when stopping the daemon fails - Update the executed-program receipts without changing dependencies Real tmux 3.2a and 3.7c fault injection reproduces the old leaks and proves the corrected cleanup. Combined failures preserve both diagnostics and the endpoint; proof cleanup reaps only the recorded owned processes. Fresh independent reviews pass for both programs. The rendered HTML, clipboard content, Markdown, and full-text exports retain their bytes.
why: Complete Java consumer projects need a settings file. The assembled content audit mistook its Kotlin DSL for a foreign port example. what: - Accept settings.gradle.kts beside the existing build.gradle.kts rule - Keep the exemption limited to Java pages and Kotlin configuration validation: The assembled product content check and seven predicate cases pass. The outer loop passes in 45.99s. Hosted runs 36655549814 and 36655731965 exposed the missing settings filename; full CI reruns next.
why: Workspace and MCP pages showed callable fragments or assumed an existing server. Readers need complete consumer projects they can run. what: - Publish full TypeScript and Swift workspace/MCP programs and setup - Provide a private Swift stdio launcher and correct .NET lifecycle guide - Preserve verified program and project bytes across HTML and Markdown - Retire the unused source include and refresh guide backlinks validation: Native cases cover tmux 3.2a and 3.7c, startup and cleanup failures, exact dependency resolution, and missing-import controls. Twenty-seven receipt checks and the outer loop pass (45.66s). Fresh Astro output matches nine native files through HTML, copying and text exports. Thirty-two browser cases and ten actual copy buttons pass. The combined local search index was rebuilt; three filtered queries see current pages. Historical-version execution and the broader publication audit remain separate from these checks.
tony
marked this pull request as ready for review
September 30, 2026 02:39
tony
added a commit
that referenced
this pull request
Sep 30, 2026
what: - Select port-owned prose, APIs, examples, and exports - Provide complete capture and companion-product programs - Fix native-page navigation, menus, themes, and wrapper links why: A port page must teach the selected language throughout its article. Readers also need examples they can copy and run, with navigation and exports that preserve the same content boundaries.
This branch was successfully deployed
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.
Port articles now select complete language-owned prose, APIs, defaults and examples. Root articles explain tmux behavior and may use language tabs. The capture example now has one shell program and compact links to eight owned port variants. HTML, headings, Markdown copies and LLM exports share that selection; article links stay in the selected port and version. Port search retains its language scope through empty results and delayed requests.
Ruby and Lua use revision-bound native guides. Kotlin, Scala and F# retain library-only guides. Kotlin/Scala quickstarts now include complete programs, exact dependencies, private tmux configuration and cleanup from reviewed Java source
3c9ad0ee5698554b9311b3fbc63d3e33873830c6. F# task links stay inside the selected documentation version; other same-repository source links use the guide revision. Parsed link rewriting preserves code. Cached examples read committed source bytes, so dirty files or newer checkout HEADs cannot replace them.Workspace pages select native CLI or Python tmuxp instructions. Installation fetches an explicit public source revision; configuration, automation and error guidance follows verified native behavior. Native builder pages link to their own terminal walkthrough.
Native Sphinx pages include navigation and styles in their initial HTML. Theme choices transfer between Astro and native pages, port menus remain above the table of contents, and tablet headers keep all 13 ports visible. API navigation preserves drawer controls after client transitions. Landing pages omit article controls. Kotlin/Scala source and footer buttons open their own library directories at the selected revision.
Capture examples include complete imports, entry points, dependency/project files, commands and owned-server cleanup. Java, .NET and C++ workspace examples do the same. TypeScript and Swift workspace/MCP pages now provide complete consumers; Swift also has a private stdio launcher. The .NET guide links its complete consumer and explains actual owned-server and partial-failure behavior. Their exact executed code is protected through HTML and Markdown rendering; source-path checks are explicitly distinguished from native execution. Comments belong above code and wrap at 80 columns. Go and TypeScript clean up after partial session startup and preserve the endpoint when stopping tmux fails.
Verification
bb06e26e116e941813ca40bf45e7e3a47d38f52awith isolated tmux fixtures. Restoring the wrong return count fails compilation.Broader native example execution, remaining product audits, all-version publication and operational publishing proofs remain in progress. Targeted preview updates preserve native references. The combined English Pagefind index was refreshed (15,214 pages, 9.90 seconds); after reload, filtered root/TypeScript/Swift searches return the new content. Native API output remains from the existing assembly. The requested adoption assessment remains open.