Repository navigation
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## docs-site #756 +/- ##
==========================================
Coverage 52.45% 52.45%
==========================================
Files 26 26
Lines 3729 3729
Branches 747 747
==========================================
Hits 1956 1956
Misses 1469 1469
Partials 304 304 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
tony
changed the title
tony
marked this pull request as ready for review
September 6, 2026 11:36
tony
force-pushed
the
docs-site-deploy
branch
from
September 6, 2026 14:50
74c2be2 to
16ec75d
Compare
tony
force-pushed
the
docs-site-deploy
branch
from
September 8, 2026 23:07
16ec75d to
b911e66
Compare
tony
force-pushed
the
docs-site-deploy
branch
from
September 8, 2026 23:21
b911e66 to
18600e0
Compare
tony
force-pushed
the
docs-site-deploy
branch
from
September 8, 2026 23:30
18600e0 to
21d7a71
Compare
tony
force-pushed
the
docs-site-deploy
branch
from
September 20, 2026 12:55
21d7a71 to
f70faac
Compare
why: Deliver the shared API reference fixes through the owning documentation publisher. what: - Bind the documentation builder and publisher to one revision
what: - Bind the owning docs builder and publisher to the reviewed revision why: Deliver the reviewed API navigation, reference previews, initial styling, and installation controls through the existing publication workflow.
what: - Pin both documentation build and publication to the reviewed shared checkpoint. why: - Deliver the verified documentation wave through the existing owner workflow without changing the library or publication scope.
what: - Change only the two shared workflow pins to 32de9876ff51cdb206acbb05785f946cc08f517a. why: - Publish with the reviewed shared documentation checkpoint.
what: - Change only the two shared workflow pins to 8f304904465a15b929e139345d9b9e4672ecb7b3. why: - Publish with the reviewed shared documentation checkpoint.
what: - Change only the two shared workflow pins to 9f5cef954e3c52e7eb239a3da56a34f92b69f161. why: - Publish with the reviewed shared documentation checkpoint.
what: - Add GitHub, package and external documentation menus to the site header, each row showing its destination's icon - Show a parameter's type and optional marker against its name, print an overload note as "for <label>" without doubled parentheses, and keep the brackets of [source] links outside the link - Finish page appearance before revealing it, and load pages with ordinary document loads instead of the client router - Upload content-hashed assets before the HTML that names them, keep earlier hashes, and cache them as immutable - Start optional Cloudflare Web Analytics after page load, only where the edge grants permission - Outside Python, present available MCP and workspace companions as concept examples - Wrap Python declarations at the 60-column reference width the way ruff format does - Render a reST rubric with no body as a heading why: The header carried no repository, package or off-site API reference links. Only a port's landing and overview pages listed them together, and every other page offered one footer GitHub link. Shared source: libtmux/docs From: 9f5cef954e3c52e7eb239a3da56a34f92b69f161 To: 7ffc04bceec2cada8149a32e46926cba9fa9ecd2
what: - Draw every API kind mark on one system of six hue families in navigation trees, member lists, index cards, search results, hover cards and prose links, mark only the first mention of a name in a section, and draw modifiers as outlines - Badge each product in the documentation picker and the solution menu with its release stage, or concept for a companion outside Python, behind a hover card that links to the support page, and head each product in the GitHub and Packages menus with a label - Browse the tmux options, hooks and format variables of each pinned release in a catalog, and link and badge tmux commands, options, hooks and formats wherever guides, the manual, API docs and MCP descriptions name them - Show tmux keys as key caps in the manual and guides, and list the CLI Manual, the tmux catalog and the C source reference in the tmux sidebar - Link workspace commands, configuration keys, and MCP tool, prompt and resource names written in code to their reference rows, resolve Sphinx roles in MCP descriptions, and list MCP arguments in the API parameter style - Document type parameters under their own heading with bounds and defaults, and link them from signatures, bounds and prose - Keep the Members heading and the active group heading in view while a long member list scrolls - Move the pages about the site under /meta/ with redirects from the old addresses, drop the cross-port /mcp/ overview, and point the header MCP chip at the current port's MCP home - Rebuild the native tmux examples as a short concept and numbered steps that lead up to the complete script, each step quoting that script - Title the home page "libtmux: pilot tmux in your language" and move a reference page's qualified name into its Source and package disclosure - List the parameters of a Python function's implementation instead of each overload stub, whether or not a docstring describes them, and leave out an undocumented self or cls receiver - Take the release stage of libtmux, tmuxp and libtmux-mcp from their PyPI Development Status classifiers why: A reference page marked names with a different colour per kind, tmux options, hooks and format variables linked nowhere and tmux keys read as plain code, a long member list lost which group a member belonged to, the menus showed no release stage, and several pages still promised a tmux their ports now refuse. Shared source: libtmux/docs From: 7ffc04bceec2cada8149a32e46926cba9fa9ecd2 To: 4e891632a66a144bd9dd7747168cf9218eb32710
what: - Read a package version or release tag as stable when it is exactly MAJOR.MINOR.PATCH, with an optional v and package label, so a final release such as v0.1.0 gets a stable badge instead of throwing, and word the stable badge line "Stable release." without naming a registry; a declared stage and a stable registry status still outrank the name - Julia only: build the Julia port's docs with tmux 3.7c, the version Julia requires, compiled by the `build-tmux` command of the Julia checkout's matrix tool and put on PATH only after that build succeeds - Julia only: show the Julia core, workspace and MCP install commands for the documented source revision when the build selects one and for the default branch otherwise, and state Julia 1.13.1 and tmux 3.7c or newer as the floor - Julia only: pass the Documenter `@raw html` blocks of the Julia guides through as page HTML with their `../source/` links rewritten to the documented revision on GitHub, and keep the explicit API references and overviews of those guides inside the selected preview version why: Go example pages opened on a whole program with no path from the tmux commands to the code that runs them. The API extraction of the TypeScript, Rust, Java, Kotlin, Scala and Swift references dropped the `#` comment lines of shell, Python, Ruby and YAML examples in doc comments as if they were rustdoc setup lines. Swift reference signatures printed their parameter list twice, Ruby and Swift type keywords showed as unresolved type names, and the publisher refused the PowerShell port's .NET alpha.22 dependency against its alpha.20 navigation pin. The stage resolver threw on the final release tag v0.1.0 of libtmux-julia. Shared source: libtmux/docs From: 4e891632a66a144bd9dd7747168cf9218eb32710 To: de7abd597bd9205c54d01498d8cdcb0bb0ec37d9
what: - Link a port's repository, its package host and, where the host serves one apart from the package page, its API reference straight from the page header (`HeaderLinks.astro`), replacing the GitHub, Packages and Docs menus; an unpublished package is never linked - Add a Packages disclosure (`HeaderPicker.astro`) that lists every other package, module, product and companion of the port as source, package and API reference links from a typed inventory (`port-inventory.ts`), with a search over names, coordinates, import aliases, repository names, kinds and hosts - Grow a related or In other ports chip with the lines of its name, keeping its kind mark one line tall on the first line, where a fixed height clipped a name that wrapped (`kind-marks.css`) - List Elixir with the other ports in the port picker (`PagePortSwitcher.astro`) and, for every API reference entry that maps to a shared concept, in its In other ports list (`concepts.ts`), linking the Elixir counterpart or saying that none is recorded - Python header: GitHub and PyPI links, and a Packages disclosure that now also reaches `pytest_plugin.py`, `libtmux.test` and the source of `libtmux-mcp` and `tmuxp` why: The page header offered a port's repository, package host and API reference only as three menus, and the menus listed just the destinations spelled out by hand for each port. For Python, Julia, Go, Java, Kotlin, Scala, C#, F#, C++ and Swift, the other packages, modules, plugins, commands and extensions of the port had no link in the header. A related chip had a fixed one-line height, so a name that wrapped overflowed the chip. Shared source: libtmux/docs From: de7abd597bd9205c54d01498d8cdcb0bb0ec37d9 To: fcf99651e5200b96af8d59a7d8b336904636aca8
what: - Offer Outline, Focus and Grouped layouts in the reference sidebar's menu, on the API pages and the Reference pages of each product, and keep the reader's choice from page to page (`api-tree.ts`), with Up to the selected declaration's parent and Root to the reference index at the bottom of the menu (`ApiTree.astro`); every library's sidebar comes from one builder (`api-sidebar.ts`) - Fold a sibling list longer than a window into "N more" rows around the selected row, so a page carries its ancestry and a window of the list instead of every member of its owner; a folded row opens on a click or from the keyboard and, without JavaScript, links to the first page it holds (`api-sidebar.ts`) - Draw every hover card from one description that the page and the browser both render (`link-preview-card.ts`): the legend chip of the declaration's kind heads the card, followed by the owner and member in the language's own separator (`native-name.ts`) - Label a related type with its owner when more than one type in the port carries its name (`api-labels.ts`) - Name the tmux command a method sends, with its scope flag and C function, on the method's reference page, from records of each library's source (`ApiEntry.astro`, `tmux-library-usage.ts`) - Land a standard-library or SDK link on the page and anchor of the symbol it names: a name is looked up among an inventory's symbols and not among the pages, command-line options and labels of its manual (`inventory.ts`), and neither a dollar-prefixed variable nor the placeholder text of a printed object links (`never-links.ts`) - Group Elixir under BEAM, beside the JVM and .NET groups, in the port picker (`port-families.ts`) - Build with `astro` 7.4.2 (was 7.3.5), `@astrojs/mdx` 8.1.1 for MDX pages, `@astrojs/markdown-remark` 7.3.4 for Markdown and `astro-expressive-code` 0.44.3 for code blocks, with the viewport-prefetch patch regenerated for the new Astro (`astro@7.4.2.patch`), and install with `pnpm` 12.15.0 (was 12.13.0) - Refresh the formatter, linter and test tools: `@biomejs/biome` 2.6.2, `oxlint` 1.89.0, `vitest` 5.0.5 and `happy-dom` 21.0.4 - Link a name of the Python standard library to the page of the CPython 3.15 manual that documents it, where functions, types, exceptions and constants moved under builtins (`python.entries.json`), and look up the dotted name before a trailing call or subscript (`link.ts`); the glossary links the same pages (`api-glossary.ts`) - Give the assembled native Python pages the shared sidebar and its layout controls, keeping their article HTML and original URLs, and insert the shared header, sidebar and footer text literally instead of as a replacement pattern (`normalize-native-shell.mjs`) - State tmuxp's tmux minimum as 3.2a, the floor of its libtmux dependency (`guides.md`, `installation.md`), link the tmux support guide from the workspace compatibility page and the MCP entry page (`compatibility.md`, `index.md`), and say the tmux filter grammar works on every supported tmux (`queries.md`) why: The reference sidebar offered a single layout, so a reader could not choose between declaration order, one owner at a time and grouped categories. A standard-library or SDK link could land on a manual page, a landing page or a neighbouring entry instead of the symbol it names. Hover cards came from separate renderers that had drifted apart, and a method page did not say which tmux command it sends. Shared source: libtmux/docs From: fcf99651e5200b96af8d59a7d8b336904636aca8 To: 00045828e6457d142d58933f603665a2ead35811
why: The site still presented libtmux as an alpha: badges, notices, install commands and examples carried alpha pins and prerelease flags, and a docs channel stood for a release state that no libtmux release has. A Sphinx project had no inventory to link to, tmux commands and cross-port links sat in small rows under each declaration, TypeScript aliases showed no declaration, and native Python documentation pages listed every page in one flat sidebar column. what: - Publish `objects.inv` and `targets.json` at the root of each port version, naming the pages, headings, workspace table rows, MCP schema fields, command options and API declarations the build rendered, and stop the build when an API declaration has no rendered target (`inventory.ts`, `inventory-publisher.ts`, `inventory-targets.ts`, `targets.ts`; libtmux/docs#166) - Link the footer of a port page to the inventory of its port version, to the full inventory and to a guide on linking from Sphinx, and list the same inventory and target files in the `docs.json` manifest (`SiteFooter.astro`, `inventory-links.ts`, `docs.json.ts`; libtmux/docs#166) - Export the rows of the shared workspace command and configuration tables as Sphinx option, setting and environment variable targets, and keep a page's identity across a move through `inventoryId` and `inventoryAliases` in its frontmatter (`rehype-row-anchors.ts`, `load.md`, `panes.md`, `environment.md`, `content.config.ts`; libtmux/docs#166) - Link the AI policy, which the root site publishes at `/meta/ai-policy/`, from the footer (`SiteFooter.astro`, `ai-policy.md`; libtmux/docs#194) - Show a final release on its badge as its series, 0.x for 0.1.0, with the line "Released; the API may change.", and replace the alpha notice with an early-release notice that returns once for a reader who dismissed it (`ports.ts`, `registry.json`, `PrereleaseNotice.astro`; libtmux/docs#200) - Remove the stable docs channel: a release tag publishes at its own version, a prerelease also as `next`, and the newest final release tag is the default and indexed version, or `latest` while the port has none; an older tag pushed later does not take the default (`port-docs-identity.sh`, `publish-plan.mjs`, `gen-versions.mjs`, `versions.ts`; libtmux/docs#201) - Leave a release-numbering label such as 0.1.N plain in prose instead of resolving it as an API name (`resolver.ts`; libtmux/docs#204) - Give a symbol's tmux commands, tmux C declarations, hooks, options and formats, Guides and equivalents in other ports their own sections on its API reference page and in its Markdown export, ahead of Related types (`api-tmux-sections.ts`, `ApiTmuxSections.astro`, `ApiReference.astro`; libtmux/docs#202) - Draw the nested guide line in every sidebar layout, set Grouped's group headings bold as Outline's are, and make the API glossary the last row of the reference sidebar and the last search result (`api-tree.css`, `ApiTree.astro`, `api-tree.ts`; libtmux/docs#208) - Open the preview card of a glossary link only after the pointer rests on it for a second, and let Escape cancel a card that has not opened (`link-preview-browser.ts`; libtmux/docs#211) - Let Tab move from the footer's inventory help link to the link in its tooltip at once (`SiteFooter.astro`; libtmux/docs#211) - Set the title of an index-style reference page, such as API reference, in the sans face (`ApiReference.astro`; libtmux/docs#211) - Start the permalink, source link and badges of a native Python declaration on its first signature line, so they stay level with it when the signature wraps (`native-sphinx.css`; libtmux/docs#198) - Pin a top-level Python class declaration under the header while its members scroll, and offset an anchored member by the pinned row's measured height, none until it is measured, so it lands below the row (`native-sphinx.css`, `NativeSphinxScript.astro`; libtmux/docs#198, libtmux/docs#211) - Show the Sphinx toctree in the sidebar of native Python documentation pages, with its captions as headings, branches that nest and open down to the current page, external rows that open in a new tab, and search results labelled by path (`native-shell-context.mjs`, `native-shell.ts`, `NativeShell.astro`; libtmux/docs#209) - Set the section titles of the MCP reference in the sans face, and keep its sidebar guide line under the parent label and not through the row's own text (`ProtocolReference.astro`, `api-tree.css`; libtmux/docs#211) Shared source: libtmux/docs From: 00045828e6457d142d58933f603665a2ead35811 To: e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e
why: A cross-reference in an API doc comment gave no sign of the kind of declaration it named, though a mention of the same name in a guide already led with a kind badge. Search also read the mark of that badge as part of the name beside it, so a name could be indexed with a stray letter. what: - Lead a cross-reference in an API doc comment with the kind badge of the declaration it names, the first time an entry mentions that declaration; a later mention is the link alone and keeps its kind in the tooltip and the accessible name (`ApiDoc.astro`, `ApiEntry.astro`) - Lead a tmux command, option, hook or format variable named in a doc comment with its tmux kind badge, whether it is named in prose or is the only name in a code span, under the same first-mention rule (`tmux-links.ts`) - Exclude the kind badge from search text, for a guide mention and for a doc-comment cross-reference, so search does not read its mark as the first letter of the name beside it (`mention-badge.ts`) - Lead a module, package or namespace named in a code span of a guide with its module kind badge, the first time a section mentions it; a later mention keeps its kind in the tooltip and the accessible name (`rehype-api-links.ts`) - Lead each entry of the Workspace Manager and MCP reference index with its kind badge, so the list shows the kind of each declaration (`ProductApiIndex.astro`) - Exclude the kind badge that leads a link in an MCP tool description from search text as well (`mcp-reference.ts`) - Lead a code cross-reference on Python's native Sphinx pages with the kind badge of its target's declaration the first time a section mentions it, and let a later mention keep its kind in the tooltip and the accessible name; a property referenced as an attribute reads as a property and an exception referenced as a class reads as an exception, a target with no declaration, a link to another site and a signature stay plain, and a page that cannot be marked keeps its navigation (`native-xrefs.ts`, `native-shell-context.mjs`, `NativeSphinxScript.astro`) Shared source: libtmux/docs From: e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e To: 4648913190eb75e4b592db2ba14e15fdcf24174f
why: A cross-reference in a doc comment led with a kind badge, so a page that names many methods read as a row of badges. The sidebar tree indented a row's label but not its mark and drew only the guide of a row's parent, and a linked type in a signature or a parameter row was drawn in the ordinary link color. A code literal could also link to an unrelated member: the argument of a call, a control-mode marker, a word of a kebab-case name. what: - Indent a row of the reference sidebar tree as a whole, mark and label together, draw a guide from every ancestor level, and mark the current row by tint and weight alone (`api-tree.css`) - Draw a cross-reference or a tmux name in a doc comment in the color of its kind with a dotted underline instead of a badge before it; the kind stays in the tooltip and the accessible name, and a linked method or function named by a plain path reads as a call (`ApiDoc.astro`, `api.css`) - Highlight every other link to a name while a reader points at it or focuses it, in the doc comments, the member list, the directory chips and the sidebar tree (`cross-highlight.ts`) - Draw a qualified name with a quiet path and its own name in the color of its kind, show the Declared in row as a code link in that color, and keep the copy button from making its row taller (`ApiQualifiedName.astro`, `ApiReference.astro`) - Fold three or more guidance rows of a doc comment, each followed by the references it covers, into a two-column directory of chips, and draw a pipe table as a table (`api-directory.ts`, `api-prose.ts`) - Keep a code literal from linking to an unrelated member: the bare argument of a call, a control-mode marker and a kebab-case word stay plain, and a path that matches no declaration links its longest prefix that is a type (`link.ts`) - Show the permalink beside an API section heading, and a table row's, only on hover, focus or target for a fine pointer; touch and forced colors always show it (`api-headings.css`, `global.css`) - Join the sticky Members and group bars into one toolbar, align each parameter's label with the first line of its value, and list the pages that discuss a symbol one to a line (`ApiPageContents.astro`, `ApiTmuxSections.astro`, `api.css`) - Draw a parameter's name in the name color and a type it links in the type color, and mute the rest of the type (`api.css`) Shared source: libtmux/docs From: 4648913190eb75e4b592db2ba14e15fdcf24174f To: c6b76c7ef7a5a2cdd0513dcbd28ccb5184b61344
why: Reference prose wrote every linked method with call parentheses whatever the language, so Ruby and Go read as Python does, and a code literal such as a file path or a plain word could link to an unrelated type's member. README badges stacked down the page instead of sitting in one line, and a preview card opened after 180 ms and said to read the reference when a declaration had no summary. what: - Write a linked symbol in a doc comment the way its language's own documentation writes it, from one table with an entry for each port; the text a reader sees and the accessible name are the same string (`symbol-form.ts`, `ApiDoc.astro`) - Write a tmux command and an MCP tool without call parentheses, and an environment variable without the shell's dollar sign; a placeholder such as an expansion example keeps the sign (`symbol-form.ts`, `mcp-catalog.ts`) - Leave a file path in a code literal unlinked, and link a plain lowercase word to a member of another type only when that type is one the page is about or the word is a call with arguments; a word that names a parameter of the page's own signature, and a member of the library's internals on a public page, never link (`link.ts`) - Open a preview card after 450 ms of hover, open the next one 100 ms after a card is open or loading, and keep the glossary at 1000 ms (`link-preview-browser.ts`) - Give a preview card's summary the same room above and below, and show only the signature when a declaration has no summary, with no filler line (`LinkPreview.astro`, `link-preview-card.ts`) - Keep an image inside a line of prose, a list item or a table cell in the line, so a row of README badges sits on one line; a lone image, a figure and anything marked not-prose keep their block margin (`global.css`) - Draw a member group's bar and list as one panel with one radius and one divider (`api.css`) - Build the site with Astro 7.4.4, @astrojs/mdx 8.1.2 and @astrojs/markdown-remark 7.3.5, and carry the viewport prefetch patch over unchanged (`site/package.json`, `pnpm-workspace.yaml`) Shared source: libtmux/docs From: c6b76c7ef7a5a2cdd0513dcbd28ccb5184b61344 To: d2d48767f0a1dc4367dd68944c992176128c28b5
why: A port's landing page listed its install commands under one heading and showed no example of the code to run, so a reader met no code until opening the examples. what: - Show a port's products on its landing page, each beside the install command of its package: tabs where the port ships an MCP server or a workspace package, one panel where it ships only the library, in place of the install commands under one heading (`PortLanding.astro`, `port-landing.ts`, `pages/index.astro`) - Show Core API as the port's complete homepage program in its own language, with the install command of its package (`PortLanding.astro`) - Offer MCP and Workspace Manager as tabs beside Core API, working without JavaScript, and carry the chosen tab in the address as the product parameter so a link shares it (`PortLanding.astro`, `landing-selection.ts`) - Show the example of an MCP or Workspace Manager tab as an excerpt of a file that the port's own CI runs, naming under the code the file, linked at the revision it was read from, the CI command that runs it and its workflow (`PortLanding.astro`, `port-landing.ts`, `landing-examples.json`) - Draw an MCP tool, prompt and resource page in the documentation layout, so the section menu stays in the sidebar, in place of a separate reference tree that replaced it (`ProtocolReference.astro`, `DocsLayout.astro`) - Nest each protocol object of that menu under its group, with tools grouped by the area they work on, prompts as workflows and resources as fixed resources or resource templates (`documentation-navigation.ts`, `mcp-reference.ts`) - Keep the sidebar's own text out of the site search, since it lists every protocol object (`DocsLayout.astro`) Shared source: libtmux/docs From: d2d48767f0a1dc4367dd68944c992176128c28b5 To: 9be37754afdeb80f043f6ef615254e0315fd2071
why: A port's Workspace page showed no workspace file that its tests load and its MCP page listed no tool its server advertises, so a reader had to open the reference to see what either product does, and the pages were not named by their language. what: - Title the Workspace and MCP pages of a port by its language, for example "tmux workspace manager, forged in Rust" and "tmux MCP, built in Rust", in place of the title each had (`workspace/index.md`, `product-copy.ts`) - Open each Workspace and MCP overview with a sentence about the product that names only the verbs, formats and MCP SDK the port's own sources show, and links the port's libtmux library (`ProductIntro.astro`, `product-copy.ts`, `product-copy.json`) - Give the Workspace page a shorter title, such as "Rust-based tmux workspace manager", for the browser tab, the social tags and the agent files llms.txt and docs.json, and keep the longer title as the page's heading (`DocPage.astro`, `DocsLayout.astro`, `llms.ts`) - Show on the Workspace page the workspace files that the port's own tests load, each as a YAML tab and a JSON tab beside a drawing of the panes every window builds, with its source file and the tests that load it, each told apart by whether it runs the command (`WorkspaceShowcase.astro`, `WorkspaceConfig.astro`, `workspace-showcase.ts`, `workspace-showcase.json`, `tmux-layout.ts`) - Offer a searchable preset picker above the overview where the port has several workspace files: a tile of each preset's first window, a button for another at random, an address for each preset, the last choice kept for the next visit and the chosen preset set while the page is parsed (`WorkspacePicker.astro`, `workspace-picker.ts`) - List the tools the server advertises on the MCP page, each as a link to its reference page with a one-line purpose from its own description (`McpShowcase.astro`, `mcp-showcase.ts`) - Group those tools as Inspect, Manage, Execute and Teardown from the toolset the server declares for each, with a tier badge on every tool, tell the reader that the toolsets setting offers only some tiers, and say in the opening sentence that the server groups its tools (`McpShowcase.astro`, `mcp-showcase.ts`, `product-copy.ts`) - Show a worked example on the MCP page: a prompt and the calls an agent makes for it, in the server's own tool names (`McpShowcase.astro`, `mcp-showcase.ts`) Shared source: libtmux/docs From: 9be37754afdeb80f043f6ef615254e0315fd2071 To: 84937633ac63297d2be2a71c7719d41109be5c63
why: A port's home page showed a tagline and a tab for each product, and no page said what the library wraps or which capabilities it has, so a reader met the products before seeing what any of them does. what: - Title a port's home page by its repository and language, as "libtmux-rs: Rust-based tmux client", and open it with "libtmux for Rust", a definition of the library and the repository and package links in the top right, in place of the tagline and the paragraph naming the version (`PortHero.astro`, `DocumentationHero.astro`, `ports.ts`) - Add a Core Library home at core/ for each port: its Server, Session, Window and Pane types with the tmux object each wraps, and the capabilities it has, each linked to the symbol of the extracted API model that provides it and refused when the symbol does not back it (`CoreHome.astro`, `core-home.ts`, `core-home.json`) - Show the language Home as one row above Core Library in the documentation picker (`documentation-navigation.ts`, `SurfacePicker.astro`) - Hold a page steady while it loads: reserve the contents rail's column on the server, so the article column is final at first paint, keep the rail after the article in the source, so keyboard and screen-reader users reach the article first, and scroll to a fragment only when the browser has not already placed it (`DocsLayout.astro`, `anchors.js`) - Read a release-number placeholder such as X.Y or X.Y-rcN in prose as text, not as a symbol to resolve (`resolver.ts`) - Set the Workspace page's heading as "tmux workspace manager," with "forged in Rust." on its own line under it, a subtitle that the heading still reads whole to a search or a screen reader (`DocsLayout.astro`, `branding.ts`, `product-copy.ts`) - Show on the home page's Workspace panel a workspace file one of the port's tests loads, the panes it builds, the test that loads it and, where a test runs the command, the command that loads it (`PortLanding.astro`, `WorkspaceWindows.astro`, `workspace-links.ts`) - Preview a preset on hover in the preset picker without changing the choice, and show a window tab's full name in a tooltip when the strip clips it (`workspace-picker.ts`, `WorkspacePicker.astro`) - Replay the MCP worked example on the MCP page and on the home page's MCP panel beside the tmux state each call leaves, with the result the server recorded under the call, drawn from the recorded session only (`McpReplay.astro`, `mcp-replay.ts`, `mcp-showcase.ts`) - Make the recorded example split a window in two panes, run the tests in one and show a log in the other, then read the layout back (`mcp-examples.ts`) - Read a capability directory in the port's own link syntax where its doc comments write one of their own: Python's roles, DocC's double backticks, ExDoc, KDoc and Scaladoc links, a name in a code span for C++ and Lua, YARD, Documenter and PowerShell's cmdlet names (`api-directory.ts`, `ApiProse.astro`) - Break a shell command wider than 78 columns across lines with a trailing backslash in the MCP install panel, so the copied text still runs as one line (`install-matrix.ts`) Shared source: libtmux/docs From: 84937633ac63297d2be2a71c7719d41109be5c63 To: c601a9f6712ee581d6520699feff76c0a8665285
why: A port's MCP page showed its worked example as requests only, because the page took a recording only when the port's head was the commit it was recorded at, and a port's own build regenerates the tool list at that head. The Core showcase also refused a Ruby program that indents its require inside a begin block, as libtmux-ruby does. what: - Keep a worked example's recorded MCP session on its page while the tools it called take and return the schemas they had when it was recorded and any list of tools in a result is the set the port advertises, so a page that documents another revision of the port still replays it, and say which revision the page documents and that the results there may differ (`mcp-showcase.ts`, `mcp-contract.ts`, `McpReplay.astro`) Shared source: libtmux/docs From: c601a9f6712ee581d6520699feff76c0a8665285 To: ae091e4d45832b34550bf9471269df9689d3c2fa
why: The Ruby documentation build stopped at the Core showcase, which listed control-mode APIs that Ruby's send-keys program no longer calls, because the data the documentation held for Ruby, TypeScript and Rust was bound to older revisions than the masters their builds read. For the same reason the MCP replay of TypeScript and Rust fell back to requests only. what: - Leave this port's pages as they are: this revision refreshes what the documentation holds for Ruby, TypeScript and Rust, and nothing it holds for this port changed Shared source: libtmux/docs From: ae091e4d45832b34550bf9471269df9689d3c2fa To: 747f7193f8518e9f5bf54e46c85664b4d8010345
why: The MCP worked example drew only what each call returned, so a split showed a step after the call that made it, and Julia's page showed requests only. The recording now holds tmux's own state after every call and Julia has one. Three Ruby programs stayed off their pages until the Ruby example manifest named each program's tmux release, and the Rust language icon was white on a light page when the device was dark and the site Light. what: - Draw each step of the MCP worked example from the tmux state the recording read after that call, so a split or a new window appears with the call that made it, and show a call that only reads as leaving tmux unchanged (`mcp-replay.ts`, `McpReplay.astro`, `mcp-tmux-state.ts`) - Record the Python worked example's MCP session again at libtmux-mcp 800aebd26, its master, with the tool snapshot read at the same revision, so the page draws tmux as it stood after each call (`mcp-transcripts/py.json`) - Say on the Third-party notices page that the Rust icon no longer carries its own dark-mode colors and that the page lightens the mark on a dark theme instead (`meta/third-party-notices.md`) Shared source: libtmux/docs From: 747f7193f8518e9f5bf54e46c85664b4d8010345 To: d3b931be3e64c962f9a3ffa1117527b40ae19a79
why: The Core API example listed capabilities beside a program and left the reader to imagine what each call does, and each port's landing page showed a different program with a different output. Following a docs link blanked the whole page for 160 to 760 ms, a swap into a code frame shifted the layout, and catalogs over 10 MB reached readers uncompressed, because CloudFront does not compress objects that large. what: - Play each port's Core API program call by call on its landing page and its Core overview: hovering or stepping a call marks it in the source and draws the tmux the call left, with what it returned and the tmux commands it sent (`CorePlayer.astro`, `CoreShowcase.astro`, `CoreHome.astro`, `core-player.ts`) - Show the same quickstart on every port: a private server, session demo, an editor window split in two, a logs window and a command typed into the new pane, pinned to the library revision that carries it, so every page prints one tree (`home-examples.json`) - Offer the preset picker on the landing page's Workspace tab, opening on a file a test loads with the command or else a layout classic, each preset with its own summary, load command and evidence (`PortLanding.astro`, `WorkspacePicker.astro`, `WorkspaceEvidence.astro`) - Draw the MCP worked example with the Core player's own tmux screen and controls: a dot for tmux before the first call, a dashed placeholder for an empty screen, and no tool-count sentence above the example on the landing page (`McpReplay.astro`, `TmuxScreen.astro`, `ReplayControls.astro`, `PortLanding.astro`) - Swap a docs page in place when a link inside the same tree is followed, instead of blanking the page while the next one loads; links to another tree, to a file and to the page's own fragments go to the browser (`BaseLayout.astro`, `router-guard.ts`) - Keep a swapped page whole: the code stylesheet loads from the head, the search panel and the MCP install cooldown are set up again after a swap, the first frame waits for the header's menu panel, the agent prompt draws its version picker from the first frame, and the API tree's hold lifts after five seconds (`code-stylesheet.ts`, `SearchPanel.astro`, `mcp-install.js`, `BaseLayout.astro`, `AgentPrompt.astro`, `page-readiness.ts`) - Publish each JSON file over 10,000,000 bytes gzip-encoded, since CloudFront does not compress an object that large, and decode it again where the immutable-tag check and the published inventory read it (`large-json.sh`, `reusable-deploy.yml`) Shared source: libtmux/docs From: d3b931be3e64c962f9a3ffa1117527b40ae19a79 To: 983db91693417c1c280895377b4428259867b240
why: The Core player drew the tmux of a program as a grid of tiles, one per window of every session, which no tmux client shows, and a program that made several windows shrank the drawing into small tiles. A call and the type it returned were plain text, and the dots of the replay track gave no visible hint of the call each stands for. what: - Draw the Core player's tmux as a client attached to the program's first session sees it: the current window of the oldest session under one status line of its windows, each window label and session name a button that shows that window until the player moves to another call, and a label drawn in the accent colour when the call added, renamed or selected its window or changed its panes out of sight (`CorePlayer.astro`, `TmuxScreen.astro`, `replay-player.ts`, `mcp-replay.css`) - Link each call's name and the type it returned to their API reference pages, this build's version on the port's own site and the default version elsewhere, and start the note under the drawing with a link to the call it follows (`core-apis.ts`, `CorePlayer.astro`) - Show a tooltip over each dot of the replay track, on hover or keyboard focus, naming the call and what it did (`ReplayControls.astro`, `replay-player.ts`, `CorePlayer.astro`, `mcp-replay.css`) Shared source: libtmux/docs From: 983db91693417c1c280895377b4428259867b240 To: ff7b2e484b4503e599dc83c212ffd21f14c35dbe
why: An MCP overview put its worked example below Install, Start here and the whole tool grid, so a reader of the overview rarely reached it, and the call the replay shows was drawn like the one the pointer rests on. The JSON a Core player call returned took the landing page's general code size, larger than the program beside it, so the answer looked heavier than the code that asked. what: - Open each MCP overview with its worked example, right after the intro and before Install, Start here and the tool grid, which now closes the page, and list the example first in the table of contents (`DocPage.astro`, `McpShowcase.astro`, `mcp-showcase.ts`) - Mark the call the replay's tmux view shows with a 3px accent edge and a tint, so it stands out from the calls around it (`mcp-replay.css`) - Set the JSON a Core player call returned at the size of the program beside it, in each view and when the window resizes (`CorePlayer.astro`, `core-player.css`) Shared source: libtmux/docs From: ff7b2e484b4503e599dc83c212ffd21f14c35dbe To: c5b56f2b90002281adb95616a3e523e0a192937c
why: A workspace or MCP API reference page drew its section headings larger than a core page's, because its body sat inside the prose column, and repeated each member as a full bordered entry under a bordered bar. The reference of a product listed every declaration in one A to Z list that mixed types, functions, constants and enums, so a reader could not find a tool, a URI constant or an error type without scanning it. On a cold load the Core player was drawn at its last call and the script reset it to the first a moment later, and the controls bar appeared and pushed the player down, so the page jumped. The MCP replay did the same: the whole chat with every result open, then the bare prompt, and the page grew when the controls appeared. Pages told a reader how they were made (the revision, sandbox and generator of a recording, a library revision under an example, a generator under an API page), which belongs in the commit that refreshed the data. The headings "Worked example" and "Try a preset" did not say what a reader gets: tmux driven through MCP tools and tmux layouts and workspaces to try. The Core player's Error handling and Cleanup toggles took a row of their own above the code, and its step dots were spread across the controls bar, so on a tight bar a long program's dots crowded until a finger could not tell them apart. The MCP replay's step dots crowded the same way on a tight bar. Chrome on iOS shrinks the window height under the on-screen keyboard, so the API reference sidebar and the sticky member bars shrank when a reader focused the search field. The site header's port picker and the ports list offered only the ports that had documentation before OCaml, Haskell, Perl, Clojure, Common Lisp and Erlang. The port build ran GitHub actions by floating tag, so a retagged release would have changed what builds this port's pages. what: - Draw the workspace and MCP API reference pages in the core API presentation: section headings at the size of a core page's, the body outside the prose column, and a type's members listed once, as its table and then linked rows, where each was also a full entry (`ProductApiPage.astro`, `ApiMemberList.astro`, `DocsLayout.astro`) - Group the MCP API reference into sections in the sidebar, the documentation navigation and the reference index: Tools, Prompts, Resources and URIs, Views and results, Server and setup, Configuration and environment, Errors and Utilities, leaving out a section with nothing in it (`product-api-sections.ts`, `product-api.ts`, `ProductApiIndex.astro`); a section's row in the sidebar links to the page of its first entry, and a breadcrumb through it does too (`sidebar.ts`) - Group the workspace API reference the same way: Workspace files, Building and freezing, Command line, Plugins and shell, Errors and Utilities, URLs unchanged (`product-api-sections.ts`, `product-api.ts`, `ProductApiIndex.astro`) - Draw the Core player on the server at the frame its script first shows, the tmux before the first call, with its controls bar in place at its first count, so binding the script moves nothing; a reader with no script, and one who asked for less motion until the script binds, see the finished frame (`CorePlayer.astro`, `ReplayControls.astro`, `core-player.css`) - Draw the MCP replay on the server at the prompt alone, the calls out of view marked and its head and controls bar in place, so binding the script moves nothing; the same finished fallbacks for no script and for reduced motion (`McpReplay.astro`, `mcp-replay.css`) - Name the MCP overview's replay "tmux through MCP", where it was "Worked example" (links to the old anchor, worked-example, still land), and drop the paragraph under it on how the recording was made: its revision, sandbox, generation and shortened values (`McpReplay.astro`, `mcp-showcase.ts`) - Drop the Core player's info button, its popover and its no-script note on how the run was recorded; the controls bar keeps its other buttons (`CorePlayer.astro`, `ReplayControls.astro`) - Drop the "Library revision" line from an example's setup details and the "Generated from the source" line under the API pages that had one (`HomeExample.astro`, `[...slug].astro`) - Head the workspace overview's preset picker "Explore tmux layout / workspace possibilities", where it was "Try a preset" (links to the old anchor, try-a-preset, still land) (`WorkspacePicker.astro`, `DocPage.astro`) - Put the Core player's Error handling and Cleanup toggles in a toolbar row at the bottom of its code panel, below the code and outside the part that scrolls, where they sat in a row above it, so toggling moves no edge of the player; and let the step dots of its controls bar scroll inside a rail with a button at each end to page them, where they were spread across the bar and crowded on a tight one (`HomeExample.astro`, `core-player.css`, `ReplayControls.astro`, `replay-player.ts`, `mcp-replay.css`) - Let the MCP replay's step dots scroll inside a rail with a button at each end to page them, keeping the shown call's dot in view, where they were spread across the bar and crowded on a tight one (`ReplayControls.astro`, `replay-player.ts`, `mcp-replay.css`) - Keep the API reference sidebar and the sticky member bars at their height when an on-screen keyboard opens, where Chrome on iOS shrank the window under it and the sidebar and the bars shrank with it: while a field has focus the pages measure the tallest height seen at this width (`stable-viewport.ts`, `api-tree.ts`, `ApiPageContents.astro`) - List OCaml among the ports of the site: in the port picker of the site header and in the Compiled & native group of the ports list; OCaml's own pages are published by its own repository, not by this caller (`shell.js`, `ports.ts`, `port-families.ts`) - List Haskell among the ports of the site: in the port picker of the site header and in the Compiled & native group of the ports list; Haskell's own pages are published by its own repository, not by this caller (`shell.js`, `ports.ts`, `port-families.ts`) - List Perl among the ports of the site: in the port picker of the site header and in the Scripting & web group of the ports list; Perl's own pages are published by its own repository, not by this caller (`shell.js`, `ports.ts`, `port-families.ts`) - Pin the port build's GitHub actions to commits of the releases it used by tag (checkout v7.0.1, setup-node v7, pnpm/action-setup v6), and have the build ask the registry whether a port excludes MCP before it generates MCP data, which no existing port does (`port-docs.yml`, `build-site.sh`) - List Clojure among the ports of the site: in the port picker of the site header and in the JVM group of the ports list; Clojure's own pages are published by its own repository, not by this caller (`shell.js`, `ports.ts`, `port-families.ts`) - List Common Lisp among the ports of the site: in the port picker of the site header and in the Compiled & native group of the ports list; Common Lisp's own pages are published by its own repository, not by this caller (`shell.js`, `ports.ts`, `port-families.ts`) - List Erlang among the ports of the site: in the port picker of the site header and in the BEAM group of the ports list; Erlang's own pages are published by its own repository, not by this caller (`shell.js`, `ports.ts`, `port-families.ts`) Shared source: libtmux/docs From: c5b56f2b90002281adb95616a3e523e0a192937c To: 8245169584882f09e302881f136512df41aba2a4
why: The landing page ended with "All versions and install instructions", a link to the port root, which redirects back to the page the reader was on. what: - Drop the link at the end of the port's landing page back to the port root, whose address redirects to the landing page the reader is on (`index.astro`) Shared source: libtmux/docs From: 8245169584882f09e302881f136512df41aba2a4 To: 30af469ec547f55bd6121fdd7bcd1259928f81b0
why: A long program could widen the example panel's grid beyond a phone's width, and a code block nested in the panel took the panel's fixed height. Haskell gained an Examples page, and the linking guide promised MCP contracts in the full export of every port. what: - Keep an example program's panel inside a narrow page: the grid that holds the program has a column that can shrink to the page, and the panel's fixed height, scrolling and column-fit type size apply to the program block itself, not to a code block nested in it (`CoreShowcase.astro`, `HomeExample.astro`) - Offer Haskell's new Examples page in the language picker of an Examples page, where Haskell had none, and scope the linking guide's llms-full.txt row to ports with and without an MCP server (`linking.md`) Shared source: libtmux/docs From: 30af469ec547f55bd6121fdd7bcd1259928f81b0 To: cfa8a14960f4b68c182c687672086f19840b1fc9
why: A bar hidden only after the page loaded would flash on every page a reader had already dismissed it on. A link to another site grew its icon after the page had loaded and pushed the text after it along. Every MCP page opened with an admonition that a reader could not close, the same sentence on every page of the product. The language picker of an MCP or Workspace Manager overview offered the page of a port that has no such product. A reader on a Server, Session, Window or Pane page could not jump to the same concept in Haskell, and the Server page had no link to Common Lisp's. what: - Read the product status bars a reader has dismissed in the page's head, with the theme settings every page applies before it paints, and hide a dismissed bar with one stylesheet rule per status, so a dismissed bar is never drawn (`ThemeScript.astro`, `global.css`) - Draw the icon of a link that leaves the site in the first paint: the build writes the external-link marker into the HTML of every page, and of the native reference pages, so the icon no longer appears after the page loads and shifts the text after it (`external-links.ts`, `mark-external-links.mjs`, `build-site.sh`) - Show the in-development status of the MCP server as a dismissible bar under the page header, on every MCP page, where each page opened with it as an admonition inside the article: dismissing a bar hides that note on every page that carries it, a reader without scripts keeps it, and a page's Markdown twin leads with the same sentence (`ProductNotice.astro`, `DocsLayout.astro`, `BaseLayout.astro`, `markdown-twins.ts`) - Show "No matching page" with a link to the language home, in the language picker of an MCP or Workspace Manager overview, for a port that publishes no such product, where the row linked to a page that said the product was not published (`ports.ts`, `docs-paths.ts`) - Link the Server, Session, Window and Pane reference pages to Haskell's counterpart, in the language picker and in the list of the same concept in other ports, and the Server page to Common Lisp's client (`concepts.ts`) Shared source: libtmux/docs From: cfa8a14960f4b68c182c687672086f19840b1fc9 To: a914a82442dbd1be9d7b799d3019db203474ade3
why: libtmux/docs #316 (merged as 15786d72e) refreshes this port's pages (registry versions and claims, package links, a port switcher that lists Raku) and lets the publisher roles trust that revision; the port builds and publishes its docs through the two reusable workflows at the pinned revision. what: - Repin port-docs.yml and reusable-deploy.yml from a914a8244 to 15786d72e in .github/workflows/docs.yml
why: tmux-python/libtmux builds and publishes its docs through the two reusable workflows of libtmux/docs; they must pin the revision whose pages it should publish and whose publisher the IAM roles trust (15786d72e, docs #316). what: - Repin port-docs.yml and reusable-deploy.yml in .github/workflows/docs.yml to 15786d72e
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
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.
Stacked on #755. Keep this PR open while its reviewed branch revision is used to refresh libtmux.org.
Python's unified docs now build through the shared source-revision workflow, including the native Sphinx reference under
api/. Pull requests build without publishing. A maintainer can dispatch an exact source ref, version and publication policy;publishdefaults to false. Workflow changes are included in the documentation path filter.libtmux.git-pull.com retains its standalone Sphinx build and publishes on default-branch pushes. Its sync follows symlinks directly from the build job. Each destination keeps its existing secrets and its own publication queue.
Both shared workflow references use the same reviewed docs commit. Python dependencies are installed from the selected source lock; the separate tmuxp and MCP source checkouts use the revisions recorded in the shared API model. Grouped weekly GitHub Actions updates are configured; a bot-generated docs-pin update has not been demonstrated.
Validation
Six documentation-configuration tests pass, covering standalone and nested Sphinx behavior.
The selected Python revision has been built locally with the shared shell and native Sphinx reference; the inventory, API index and current native branding were checked.
The caller passes actionlint with its unsupported
queue: maxdiagnostic suppressed. The shared publishers already use that GitHub concurrency setting.Successful build-only dispatch from the unmerged branch. Live publication remains a separate explicit dispatch.
Explicit publication succeeded for reviewed source
f70faacd0bdc0a00211232e52ab768a98f7e6dd1; this PR remains unmerged.Live permission probe confirms that the Python role rejects a direct job outside the approved reusable workflow and denies writes to another language prefix. The negative verdict passed, the deliberate denial job is red, and the target prefix remains empty.
The live library, MCP, workspace, example, Sphinx API pages and inventory match the selected-source artifact. The example source links name the reviewed commit. All 39 linked branding assets match their source bytes and expected content types.
Removed the extra blank line rejected by Ruff in
src/libtmux/constants.py. Ruff 0.16.8 now formats all 135 files cleanly, and the targeted lint check passes. The published source revision remains the explicitly selectedf70faacd0bdc0a00211232e52ab768a98f7e6dd1.Publication provenance
Hosted publication proof passes at
843278f595d8a4495c18c9d9dbe8ab0b2bd50289: a clean Python build publishes, three controlled artifact violations fail before AWS, and an identical immutable rerun skips sync while retaining its original receipt. Ordinary hosted GETs return HTTP 200 and all 7,699 S3 objects match their recorded bytes. Dispatch to first receipt takes 434 seconds. The run is deliberately red because its three negative jobs fail. Durable evidence and completed cleanup preserve the checks after temporary artifacts expire. These measurements cover dispatch latency; release-event latency remains open.