mirror of https://github.com/software-mansion/argent.git synced 2026-09-14 19:27:14 +08:00

Files

T

Kacper Kapuściak 36aa14a5fc docs: add Argent documentation (#814 )

Adds the Argent documentation site, published to
[docs.swmansion.com/argent](https://docs.swmansion.com/argent): a
branded Docusaurus project under `packages/docs/`, the full first set of
pages, and the CI that checks and deploys it.

<img width="1512" height="945" alt="Screenshot 2026-08-21 at 13 05 04"
src="https://github.com/user-attachments/assets/4607e143-4359-49a8-93a2-aaa3af4c9534"
/>

## Site

A standalone Docusaurus 3.9 project, built on the shared Software
Mansion docs theme
([`@swmansion/t-rex-ui`](https://www.npmjs.com/package/@swmansion/t-rex-ui))
and restyled for Argent:

- **Palette** from [argent.swmansion.com](https://argent.swmansion.com):
dark `#0D0F26`, blue `#99DAFF`, lavender `#E4E1FF`, light `#FEFEFE`,
mist `#F1F1F1`. The `--swm-*` token names stay, since the shared theme
resolves against them.
- **Typography**: DM Sans and DM Mono, matching the landing page.
- **Sidebar** with lucide icons on every page entry
(`sidebar_custom_props.icon` in the front matter, registered in
`src/theme/SidebarIcon`), the logo kept on the page background and the
panel inset from the edge.
- **Video component** for embedded screen recordings, with
`scripts/encode-video.sh` producing a web-sized MP4 and a poster frame
for each clip in `static/video/`.
- **Copy page button** and a few theme fixes: inline code badges in
tables, paginator hover.
- **No landing page.** That stays at argent.swmansion.com. The root
route redirects to Getting started.

## Content

Three sections in `docs/`:

- **Fundamentals**: getting started, installation, supported platforms.
- **Features**: interacting with apps, flows, network, screen recording,
lens, visual regression, profiling, debugging. Conceptual overviews with
recordings, each linking to the tools reference.
- **Reference**: tools, CLI, configuration, flow YAML, editors,
telemetry.

Prose follows Simplified Technical English. The conventions (style,
front matter, icons, checks) are written down in
`packages/docs/CLAUDE.md`, and a root `CLAUDE.md` adds a checklist so
that code changes to tools, CLI, configuration or flows update the
matching docs page in the same pull request.

## CI and deploy

- `Docs build` runs `format:check`, `lint`, `typecheck` and `build` on
every pull request that touches `packages/docs/`. The build has
`onBrokenLinks: "throw"`, so it catches links left dangling by a moved
page.
- `Docs publish` deploys `packages/docs/build` through the GitHub
Actions Pages source on every push to `main` that touches the docs. The
repository Pages source needs to be set to **GitHub Actions** for the
first run.

## Notes for review

- The site is excluded from the root `packages/*` workspaces
(`!packages/docs`) and keeps its own `package.json` and
`package-lock.json`, so its dependency tree stays out of the toolkit's
lockfile. Root Prettier, ESLint and knip ignore it; it formats and lints
itself with the repo `.prettierrc` and its own `eslint.config.mjs`.
`check-workspace-versions.mjs` skips it so its `0.0.0` version is not
read as drift.
- `webpack` is pinned to `5.105.4` and `@docusaurus/plugin-content-docs`
/ `theme-common` to `3.9.2` via `overrides`. Newer webpack fails
Docusaurus 3.9's ProgressPlugin option validation, and a hoisted
`plugin-content-docs@3.10.2` produced a duplicate React context that
crashed SSR.
- **Search is not wired up yet.** The shared theme always mounts a
DocSearch bar, so an `algolia` block has to be present. It reads
`ALGOLIA_APP_ID` / `ALGOLIA_API_KEY` / `ALGOLIA_INDEX_NAME` from the
environment and the bar stays hidden until Argent has its own DocSearch
application. Follow-up PR.

## Testing

- `npm run format:check`, `npm run lint`, `npm run typecheck` and `npm
run build` pass in `packages/docs/`.
- Root `prettier --check`, `eslint` and `npm run knip` pass.
- Walked the served production build in the browser in light and dark
themes while iterating: root redirect, docs pages, sidebar icons,
videos, TOC, footer.

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-21 16:03:35 +02:00

2.3 KiB

Raw Permalink Blame History

static/video

Every file here is served as-is at /argent/video/<name>.mp4. Do not commit a raw screen recording into this directory: run it through the encode pipeline first, and make sure it has a poster frame.

Adding a video

Keep the source recording OUTSIDE this directory (the script cannot read and write the same path). Encode from wherever it was recorded:
```
npm run encode:video -- ~/Desktop/my-recording.mov
```
This writes static/video/my-recording.mp4 (H.264, +faststart, yuv420p, audio stripped) and static/video/my-recording.jpg, the poster frame taken a quarter of the way in.
For text-heavy captures such as terminal sessions, keep the native height and lower the CRF so the type stays sharp:
```
npm run encode:video -- -h 1080 -c 24 ~/Desktop/wizard.mov
```
Flags: -h output height (default 900), -c CRF (default 28, lower is sharper and larger), -p poster timestamp in seconds, -o output dir.
Check the poster with ffprobe/an image viewer. The first frames of a demo are often an empty terminal or a splash screen; if the default frame is blank, re-run with -p <seconds> pointing at a representative moment.
Embed it. <Video> is global in MDX, so no import line is needed. Pass the real pixel dimensions so the page reserves the right box before the file loads (ffprobe -v error -show_entries stream=width,height -of csv=p=0 file.mp4):
```
<Video
  src="/video/my-recording.mp4"
  width={1618}
  height={1080}
  caption="What the reader is looking at"
/>
```
Add portrait for simulator and emulator captures, which are capped at 480px tall instead of filling the content column.

Rules

Never commit a GIF. The same ten second capture is roughly thirty times larger as a GIF than as H.264.
Never commit an unencoded recording. A raw QuickTime capture is several megabytes; the pipeline typically cuts that by 4-5x with no visible loss.
Every .mp4 here has a matching .jpg. The component derives the poster path from the video path, so a missing poster is a broken image.
Once this directory passes a few tens of megabytes, move the files behind a CDN and pass absolute URLs to src rather than growing the git history.

The component lives in src/components/Video/, the script in scripts/encode-video.sh.

2.3 KiB Raw Permalink Blame History

static/video

Adding a video

Rules

2.3 KiB

Raw Permalink Blame History