mirror of
https://github.com/software-mansion/argent.git
synced 2026-09-14 19:27:14 +08:00
Kacper Kapuściak
36aa14a5fc
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>
68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# Argent documentation
|
|
|
|
The Argent documentation site, published at [docs.swmansion.com/argent](https://docs.swmansion.com/argent).
|
|
|
|
Built with [Docusaurus](https://docusaurus.io/) and the shared Software Mansion docs theme, [@swmansion/t-rex-ui](https://www.npmjs.com/package/@swmansion/t-rex-ui).
|
|
|
|
The site has no landing page of its own. That is [argent.swmansion.com](https://argent.swmansion.com); the root route here redirects to the getting started page.
|
|
|
|
## Development
|
|
|
|
This site lives at `packages/docs` but is a standalone npm project with its own lockfile, excluded from the root `packages/*` workspace glob so its dependencies stay out of the toolkit's lockfile. ESLint still runs from the repo root (`npm run lint`) with the shared `eslint.config.mjs`; install this package's dependencies first so the type-aware rules can load `tsconfig.json`.
|
|
|
|
```bash
|
|
cd packages/docs
|
|
npm install
|
|
npm start # dev server on http://localhost:3000/argent/
|
|
npm run build # production build into packages/docs/build
|
|
npm run serve # serve the production build
|
|
```
|
|
|
|
## Layout
|
|
|
|
| Path | Contents |
|
|
| ----------------- | --------------------------------------------------------------------- |
|
|
| `docs/` | Documentation pages (MDX), grouped into sidebar categories |
|
|
| `src/pages/` | The root route, which redirects into the docs |
|
|
| `src/css/` | Argent color palette, typography and theme overrides |
|
|
| `src/components/` | Components used from MDX, registered in `src/theme/MDXComponents.tsx` |
|
|
| `static/img/` | Logos, favicon and other static assets |
|
|
| `static/video/` | Encoded screen recordings, see [Videos](#videos) |
|
|
|
|
Colors in `src/css/colors.css` are derived from the Argent brand palette used on
|
|
[argent.swmansion.com](https://argent.swmansion.com).
|
|
|
|
## Videos
|
|
|
|
Screen recordings go through `scripts/encode-video.sh`, which produces a
|
|
web-sized MP4 and a poster frame in `static/video/`:
|
|
|
|
```bash
|
|
npm run encode:video -- ~/Desktop/tap-flow.mov
|
|
```
|
|
|
|
Record in the simulator or with QuickTime, then encode. Never commit a GIF: the
|
|
same ten second capture is around thirty times larger as a GIF than as H.264.
|
|
|
|
Embed the result with the `<Video>` component, which is global in MDX and needs
|
|
no import:
|
|
|
|
```mdx
|
|
<Video src="/video/tap-flow.mp4" portrait caption="Tapping through the sign-in flow" />
|
|
```
|
|
|
|
| Prop | Meaning |
|
|
| ------------------ | --------------------------------------------------------------------- |
|
|
| `src` | Site-relative path to the MP4 |
|
|
| `portrait` | Caps the height at 480px, for simulator and emulator captures |
|
|
| `poster` | Poster frame; defaults to the sibling `.jpg` the encode script writes |
|
|
| `caption` | Optional caption rendered below the clip |
|
|
| `width` / `height` | Intrinsic pixel size, reserves space so the page does not reflow |
|
|
|
|
Clips are muted and loop on their own. Nothing downloads until the player nears
|
|
the viewport, playback pauses while it is off screen, and readers who ask for
|
|
reduced motion get a paused player with controls instead of a loop.
|
|
|
|
Once `static/video/` grows past a few tens of megabytes, move the files behind a
|
|
CDN and pass absolute URLs to `src` rather than growing the git history.
|