Repository navigation
Docs V2: full Docusaurus rebuild - #3
Merged
Merged
Conversation
Docusaurus aggregator delivered for the docs.freemocap.org V2 uplift, plus the coordinate-conventions content, navigation, and homepage fixes from the initial review session. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Navbar sections now expand on hover instead of requiring a click, with a two-level flyout for Tutorials (tier, then page) since Docusaurus's stock dropdown rejects nested dropdowns outright. Removes the dropdown carets and the Skelly University sidebar entry (it's link-only via the homepage's coming-soon card for now). Replaces the footer with a full sitemap grid matching the navbar, a social icon row, and the About section's links as plain text below it, following the ethereum.org /learn footer pattern. The navbar dropdowns and the footer both read from one new src/data/sitePages.ts instead of hand-duplicating the same ~65 links in three places. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The on-site placeholder had nowhere real to send readers. Links directly to github.com/freemocap/university instead, opened in a new tab, and the badge shows the URL rather than repeating "Coming soon" under a heading that already says it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The drawer (.navbar-sidebar) was collapsing to its own brand-row height on mobile instead of filling the viewport, hiding every item below it. Forcing height explicitly works regardless of why the implicit fixed-position stretch wasn't. Tutorials needed more than that: its hover-flyout component has no mobile form, since Docusaurus only builds separate desktop/mobile renderings for its own stock item types. It now reads the `mobile` prop Docusaurus passes to every navbar item and renders a genuine two-level tap accordion for the drawer, tiers then pages, using the same Collapsible primitive Docusaurus's own sidebar uses, instead of the flat single-level dropdown a first pass fell back to. Also makes the mobile menu's expand/collapse caret visible as its own tap target. Infima already gives it a rounded box and background, but only on :hover, which never fires on touch, so the two-targets-per-row split (link navigates, caret expands) was invisible on mobile. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The label became "About" a few sessions back, but the URL stayed /community/, which was misleading and, per the fetched SkellyCam docs' stale /community/roadmap reference, an actual broken link waiting to happen once /community/roadmap moved. Renames docs/community/ to docs/about/ (about.md to about-us.md specifically, so it doesn't route to the redundant /about/about), updates every internal reference, adds V1 redirect targets and a /community/* -> /about/* bridge for anything that already linked to the old paths, and fixes the hardcoded rewrite target in fetch-external-docs.mjs that was pointing SkellyCam's roadmap link at the old URL. Also adds PREVIEW.md with quick-start instructions for reviewing this branch in a browser. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
There was never a reason for docs.freemocap.org to have its own download page: the real one, with OS/GPU detection and a release selector, already lives at freemocap.org/download. The plan to "lift it wholesale" assumed otherwise. Deletes the placeholder page and points the navbar's Download item straight at the external URL instead, same pattern as the Code link. Also fixes the archival redirect for the old interim site's /freemocap/download, and extends fetch-external-docs.mjs's existing link-rewrite mechanism to catch SkellyCam's own /download references, which the build caught pointing at a page that no longer exists. Also drops the "about-us exists twice" known issue: it's a non-issue, two different sites are allowed to each have their own about page. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Four pages were stubs blocking real links: /start/, /concepts/what-is-freemocap,
/concepts/accuracy-and-limits, and /concepts/data-model. The latter two were
the sitemap's own self-identified highest-value gap ("the pages that decide
whether a researcher trusts this project"), and both had a direct source
sitting unused: Cherian's dissertation validation study (gait/balance/
prosthetic alignment against a marker-based reference) plus the array-shape
facts the sitemap had already extracted from skellymodels in code.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The homepage had four flat, equal-weight sections and no signal for a first-time visitor to know they could stop reading, or for a returning one to skip ahead, exactly the "too many docs" overwhelm problem the project wants to stay clear of. Restructures around the curriculum DAG's own 1000/2000/3000 progression instead: - TierPicker: three big Beginner/Intermediate/Advanced boxes right under the hero, the primary router, each jumping to its matching section. - Each tier holds a fixed-width tile grid, one small box per page (icon, one-line blurb, and a "?" tooltip with a real bulleted table of contents for wherever it links), replacing the old per-section cards plus a separate flat "more links" list. - The Advanced tier carries three specialization-track tags (Technology / Science / Art, matching the DAG's 3100/3200/3300 split) that link to the real per-track module content in freemocap/university, verified to exist via the GitHub API rather than guessed. - Accent color switched from an unrelated light blue to the cross-org teal/green already defined in freemocap.org's own main.css, matched per-theme (green for light mode, teal for dark) since a single flat value read weak against both a white and a near-black background. Adds react-icons (Feather set) for the per-tile icons, no other new runtime dependencies. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… tooling npm run lint:prose had never been run locally (vale wasn't installed). Running it surfaced two tooling gaps rather than prose problems: the domain vocab list was missing recurring terms (intrinsics, extrinsics, realtime, posthoc, addon), and vale sync's locally-downloaded Google style package was untracked and about to get committed by accident. Gitignore it, CI's vale-action manages its own copy and never reads this one. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Ch. 2-4 of Cherian's dissertation (the same validation study behind accuracy-and-limits.md and data-model.md) map directly onto the site's remaining /concepts/ stubs: the field's history and landscape, the four-stage pipeline, cameras and synchronization, pose estimation, and calibration. All nine /concepts/ content pages the sitemap called for now exist. Calibration's math is deliberately kept conceptual, with a pointer to triangulation.md's existing equations for anyone who wants the derivation, rather than standing up a second equation-heavy page for the sibling half of the same math. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
concepts/index.md now links all eleven /concepts/ pages instead of sitting as a stub itself. The four tutorials (multi-camera positioning, calibration best practices, post-processing, choosing a tracker) round out the action plan's suggested sequencing, sourced from the same dissertation. Scoped deliberately not to duplicate what /concepts/ already explains: better-calibration.md is the proactive counterpart to the existing reactive troubleshooting guide, and choose-a-tracker.md points at accuracy-and-limits.md's numbers rather than restating them a third time. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The dissertation isn't the right source for software-usage pages, these
needed FreeMoCap's actual V1 Writerside docs and V2 architecture docs
instead. Both are reachable via `gh api` even though this site's
automated fetch script doesn't pull them yet (data/repos.yml sets the
core repo's docs_path to null on purpose, pending its own 34-page
consolidation).
custom-pipeline.md is deliberately shallow: the real architecture doc
is ~300 lines of backend internals (IPC flags, ONNX sessions), not
end-user tutorial material, so this points to it instead of
reproducing it at the wrong altitude. analyze-in-python.md had no doc
source at all ("NEW" in the sitemap); built instead from data-model.md's
already-verified schema, generic pandas against real column names
rather than a claimed API.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Same real-source approach as the previous commit. posthoc-mocap.md's source is notably human-authored, not AI-drafted like everything else pulled this session (its own frontmatter says so), so it keeps both of its documented Alpha-build bugs verbatim rather than smoothing them over. blender-export.md here is deliberately a short companion to the fuller tutorials/blender.md rather than a second full copy that could drift out of sync with it. cite-freemocap.md resolves a real discrepancy: CITATION.cff's DOI field (zenodo.1234) is an unfilled placeholder, not a working ID. Uses Zenodo's own concept DOI instead, verified live against Zenodo's API, with a note so nobody trusts the placeholder if they check CITATION.cff directly. That placeholder is still worth fixing at the source (freemocap/freemocap, a different repo) since every citation of this software downstream inherits it until then. see-your-results.md was still a stub despite being step 3 of the main /start/ onboarding flow, one click from the homepage. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Went back through the full stub inventory and, this time, checked each page against real source before assuming it needed one, rather than just working down a list: - recording-structure.md: same source as tutorials/find-your-data.md, rewritten as a terse spec instead of a walkthrough. - rest-api.md, websocket-api.md: real source exists but is ~300+ lines of byte-level binary protocol and internal implementation detail aimed at this app's own frontend developers, mixed with an explicitly labeled "planned redesign" that isn't current. Wrong altitude and a real risk of documenting an API that doesn't exist yet as if it were current, wrote high-level orientation instead and pointed at the real source for anyone building against it. - system-requirements.md: no single doc source, but enough already-verified facts across this session's other pages to assemble an honest one. - export-formats.md: the stub's own title claimed FBX, BVH, and glTF. Checked the actual Blender addon source first: glTF is commented out, not implemented. Retitled to match reality instead of leaving the wrong title standing. - reference/index.md, guides/index.md, about/index.md: trivial hubs. - how-these-docs-are-written.md: documents the actual provenance frontmatter scheme and sourcing process this session used throughout, not a hypothetical policy. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Every page already carried provenance/reviewed/reviewed_against frontmatter, but nothing rendered it, readers had no visible signal about a page's sourcing at all. Swizzles DocItem/Content to inject a banner above the content, reading the current page's frontmatter via useDoc(), for any page that has a provenance value (external fetched content like SkellyCam's docs doesn't, and is left untouched). The banner is a small local component (src/components/ProvenanceBanner), not skellydocs' AiGeneratedBanner: that component hardcodes emoji into its icon set with no override prop, and its three-valued GenerationType doesn't map cleanly onto this site's two-valued provenance field anyway. The local version shows this site's own provenance value directly and surfaces the actual reviewed_against string when present, instead of a hardcoded assumption that goes stale the moment a page gets a real review pass. Links to /about/how-these-docs-are-written. src/global.d.ts is a standard Docusaurus TS setup gap unrelated to the banner itself: tsc can't resolve @theme/* type imports without ambient declarations from @docusaurus/module-type-aliases and @docusaurus/theme-classic, and nothing in this repo had swizzled a component with a type-only import before now. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Standing style rule: no emoji anywhere. Found via a repo-wide scan (first-recording.md's two pointer emoji, install.md's celebration and troubleshooting emoji), removed with no other wording changes. Left about-us.md's skull-and-sparkles line alone, explicitly exempted. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
lastVersion is 'current' and no other version has been cut yet (1.x still isn't, on purpose, see HANDOFF), so the built-in 'unreleased' banner's "see the latest version" link resolved to the exact page already being read. Switched to banner: 'none' until 1.x actually exists as something distinct to point to; the "2.0 (alpha)" navbar label still communicates alpha status on its own. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…e background Both were diagnosed in an earlier session and left unfixed. The onBrokenAnchors check flags #beginner/#intermediate/#advanced as broken on every build even though they work correctly, a confirmed limitation with manually-added ids on custom React pages rather than MDX-generated heading anchors. Set onBrokenAnchors: 'ignore' for that specific check, onBrokenLinks stays at 'throw'. Build now produces zero warnings for the first time this project. Light mode rendered a transparent page background instead of white: @freemocap/skellydocs only defines --ifm-background-color for [data-theme='dark'], with no light-mode value anywhere including its own :root. Added the missing light-mode value to this site's own custom.css, which loads after the shared package's. #ffffff is Infima's own standard light default, not a new color decision. Verified with getComputedStyle rather than a screenshot, since transparent-over-a-white-page and actually-white are visually identical there. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
history: [{date, against}] replaces the single reviewed/reviewed_against
pair, newest entry first. Pages without the new array fall back to
reading their existing reviewed/reviewed_against as a one-entry history,
so none of the 75 already-shipped pages need migrating.
Also fixes a real bug hit while building this: gray-matter/js-yaml parses
bare YYYY-MM-DD frontmatter as a JS Date, not a string, which was
silently breaking the "Last reviewed" line sitewide (typeof !== 'string'
on every page). Normalizes Date values to ISO date strings instead of
silently dropping them.
…tructure the top nav Version picker: - Cut 1.x (legacy) as a real frozen version alongside 2.0 (alpha) - current stays on banner: 'none' permanently, not just until 1.x exists: 'unreleased' links to lastVersion, so as long as current IS lastVersion that banner is self-referential regardless of how many older versions exist. 1.x gets 'unmaintained' instead, which correctly points at a genuinely different, newer version. - Restyled the stock version badge (was stark white-on-black on its own row) onto the breadcrumb row, right-aligned, using Infima's own emphasis-200/800 tokens so it inverts correctly in light mode too - Restored Infima's own default caret for just the version dropdown, the one item in the bar with nothing else marking it as a switcher Developer Docs section (new): - /developers landing page with a polyrepo tree (SVG, generated from data/repos.yml's tier field, not hand-coded): Core alone on top, Pantheon connected by lines, Utility floating with no connectors - New repos-data Docusaurus plugin (usePluginData) exposes repos.yml to browser-bundled components; data/repos.ts is the shared Node-side loader used by both it and docusaurus.config.ts - Boxed "Developer Docs" navbar dropdown: Core/Pantheon/Utility/More, matching the tree's grouping and data source - Every repo gets a real destination now, not a muted/unavailable state: the 4 utility repos got real routes in repos.yml, and all 7 repos without docs of their own yet got a short stub page (src/pages/<id>/) instead of being greyed out - "Home > Developer Docs > ..." breadcrumb and a "Back to Developer Docs" sidebar link for /build/ and any repo instance with real docs (DocBreadcrumbs swizzle, driven by repos-data, not a hardcoded list) - Hero copy: homepage tagline is now "User documentation for the FreeMoCap project.", developers page is "Developer documentation..." - Footer: boxed "Developer Docs" link, right-aligned in the Get Started row Nav restructuring: - Concepts and Build no longer have their own top-level navbar dropdowns. Both are still separate Docusaurus instances under the hood (per- instance versioning for Concepts, Build standing in for a future fetched instance), but that's no reason for two more entry points. - "Key Concepts" now lives inside the About dropdown/sidebar category, with the concepts pages as real sub-items, and sidebars/docs.ts and sidebars/concepts.ts are both generated from one shared tree (sidebars/sharedDocsTree.ts) so the sidebar's shape, order, and expand state never change crossing the docs/concepts boundary - Build is reached through Developer Docs instead, its existing front door
Three short paragraphs plus two images between the tree and the closing links row: a labeled composite image introducing the analogy, a paragraph on independent-but-composed repos framed through it (without naming the reference directly in the copy), and a paragraph on how FreeMoCap tracks cross-repo compatibility in practice (data/repos.yml's own tag-pinning convention), grounded in two external polyrepo- architecture write-ups read directly rather than plagiarized. Closes with a third image, centered below both paragraphs.
…ion reference SkellyTracker, SkellyForge, SkellyBlender, SkellyLogs, SkellyPings, SkellyDocs, and SkellySync all had docs_path: null in data/repos.yml, no docs site of their own yet, so /developers pointed at short stub pages instead. Replaced each stub with real developer documentation grounded directly in that repo's own source (architecture, key modules/classes, how it's consumed by the rest of the polyrepo), not ported from anywhere since nothing existed to port. cli.md and configuration.md are the same move applied to two gaps in the core freemocap repo's own reference docs: no CLI beyond one console script, and deliberately minimal configuration surface, both verified against the actual source rather than assumed. Written by stealth/ox-alpha via OpenRouter, an experiment running a tool-calling agent loop (read/list/write against the cloned repos) instead of writing this content directly. See ../ox-alpha-docs-experiment/ASSESSMENT.md for the full methodology, task-by-task attribution, and a performance write-up covering both what worked and what needed correcting. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
roadmap.md pulls from the org's actual GitHub Projects boards (32 and 34), counts snapshotted with an explicit date since they're a live source, not a hand-maintained backlog. faq.md is the interim stand-in for the Discord #help-requests export this project's docs have been blocked on: sourced from real freemocap/freemocap GitHub Discussions Q&A, but not transcribed as-is, each answer was checked against the current source first and corrected or dropped where it described the pre-alpha release rather than the current one (multi-person tracking and realtime support both changed since the original answers were written). guides/index.md gets a new "Quick answers" section linking to it. Written by stealth/ox-alpha via OpenRouter; see ../ox-alpha-docs-experiment/ASSESSMENT.md for methodology and attribution. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Both pages were previously left as stubs on the reasoning that V2's data model was being replaced and hadn't landed, so a precise reference would describe something about to be thrown away. Revisited that call: rather than continue waiting, read the actual current code to document what's really there now, however messy, instead of guessing or staying silent. Found two real systems coexisting, not one: SkellyTracker's TrackerDefinition (what the frontend sees over the websocket handshake) and SkellyForge's skellymodels ModelInfo (what actually names the columns in output files), verified independently rather than assumed from a stale HANDOFF note that treated one as legacy. In the process, found a likely real bug worth a maintainer's attention (noted separately, not fixed here): for RTMPose recordings, the aspect order used to slice output arrays doesn't match the detector's actual emission order, so hand and face data in the output files doesn't match its own labels. Also documents a parquet filename that's declared canonical but never actually written, and a reprojection_error column that's currently always NaN. Written by stealth/ox-alpha via OpenRouter; see ../ox-alpha-docs-experiment/ASSESSMENT.md for methodology and attribution. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…real hits Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…nd move actions to Node 24 releases Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…deploy results in plain language in the run log Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…GitHub shows them whole Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…redirects.js with the settled targets, let rsync deploy .htaccess Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e paths itself. Document the nginx rules for Plesk instead Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…AQ pages Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…s that setting Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…onent, click-to-zoom plugin, media manifest Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…gle-camera tutorial Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…gineer callouts, document saved_data/ Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…a to the folder tree Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…n on phones Lazy loading left unsized images unloaded on phones, and an inline max-width overrode the 100% cap, so a 480px screenshot overflowed a 356px column. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
paulmatthis
had a problem deploying
to
production
October 20, 2026 23:01 — with 
GitHub Actions
Failure
GitHub Actions
Failure
… bundles, so 50 blocked every deploy Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…inux Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Smooth scrolling was left on for as long as Home was mounted, so leaving Home animated the scroll-to-top on the next page. It is now enabled only while a same-page hash link is followed, via a site-wide client module. Co-Authored-By: Claude Code <noreply@anthropic.com>
The site is going live, so deploy-on-push is no longer a docs-v2 pre-merge test mode. DEPLOY_ON_PUSH=true deploys on any push to main or docs-v2; unset means pushes only build. Co-Authored-By: Claude Code <noreply@anthropic.com>
…crets guard - Redirect old SkellyCam URLs (/docs/ layout, es/ar copies, download, roadmap, blog) and bare roots that returned 403 (/skellycam, /freemocap, /1.x, /freemocap/docs/*) - Generate nginx 301 rules from data/redirects.js - Add redirect-only github-pages-stub so freemocap.github.io keeps redirecting to docs.freemocap.org instead of being disabled - Add robots.txt with sitemap, fix stale github.io links in architecture - Ignore credential-looking files; update DEPLOY-PLAN Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Add the root CNAME (the merge would otherwise delete it from main and stop freemocap.github.io redirecting to docs.freemocap.org) and .nojekyll. Drop the github-pages-stub folder, which is no longer needed, and update DEPLOY-PLAN. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
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.
Summary
Full Docusaurus rebuild of the FreeMoCap documentation site, replacing the placeholder currently live at docs.freemocap.org.
concepts//tutorials//guides//reference//about/split and a frozen1.xlegacy version.ENGINEER-CALLOUTS.md.Deploy
Deploys by
rsyncover SSH to the Plesk VPS. The key is locked server-side withrrsyncto thedocs.freemocap.orgfolder only, so it cannot touch the mainfreemocap.orgsite. Each deploy dry-runs first and aborts if it would delete more than 50 files. Merging never deploys by itself: it takes a manual "Run workflow", or a push todocs-v2while thePREVIEW_DEPLOYrepo variable istrue.The full site has been deployed to the VPS and tested there through a hosts-file override. DNS still points at GitHub Pages, so nothing is live for anyone else.
Before merging
GitHub Pages on
mainis still a legacy build offmain's root. Merging with Pages on would try to Jekyll-build the Docusaurus source and break the live placeholder, so disable Pages first. The full go-live sequence is inDEPLOY-PLAN.md.Known issues
build-docs/and a few data-model pages carry an in-flux banner.Test plan
npm run typechecknpm run build:local🤖 Generated with Claude Code