RTM is a documentation site for Elektron machine manuals, built with Next.js, MDX, and Contentlayer.
- Node.js 18+
- npm
git clone <repo-url>
cd rtm
npm installnpm run devnpm run buildThis generates a static site in out/ and runs Pagefind for search indexing.
rtm/
├── app/ # Next.js app directory
│ ├── page.tsx # Home page with search
│ ├── machines/[...slug]/ # Dynamic manual pages
│ ├── layout.tsx # Root layout
│ └── globals.css # Global styles
├── components/
│ ├── mdx/ # MDX component overrides
│ │ ├── MDXComponents.tsx # Component registry
│ │ └── ClickableTableRow.tsx
│ ├── Header.tsx # Site header
│ ├── TableOfContents.tsx # Floating TOC modal
│ └── ...
├── content/
│ └── machines/ # MDX manual content
│ └── <machine-name>/
│ └── manual.mdx
├── public/
│ └── machines/ # Manual images
│ └── <machine-name>/
│ └── images/
├── scripts/ # Import/conversion scripts
├── docs/ # Development documentation
└── contentlayer.config.ts # Content schema
See docs/import-checklist.md for the full process.
Quick overview:
- Convert PDF with Marker
- Run
./import-manual.sh <name> <source> "<title>" - Run
python3 scripts/convert-manual-conventions.py - Classify Tip/Warning icons
- Verify with
npm run build
- Components live in
components/ - MDX-specific components in
components/mdx/ - Use TypeScript for all components
- Prefer function components with explicit prop types
- Use Tailwind CSS for styling
- Custom prose styles in
globals.css - Dark mode support required (use
dark:variants)
Custom components available in MDX files:
| Component | Usage |
|---|---|
<Key> |
Physical keys: <Key>FUNC</Key> |
<Knob> |
Rotary encoders: <Knob>LEVEL</Knob> |
<LED> |
LED indicators: <LED>PATTERN</LED> |
<Param> |
Parameters: <Param>VOL</Param> |
<Tip> |
Helpful hints |
<Warning> |
Important notices |
<Footnotes> |
Legal disclaimer wrapper |
<Footnote> |
Individual collapsible footnote |
| Script | Purpose |
|---|---|
npm run dev |
Start development server |
npm run build |
Production build + Pagefind |
npm run lint |
Run ESLint |
npm run storybook |
Start Storybook development server |
npm run build-storybook |
Build static Storybook site |
./import-manual.sh |
Import converted PDF |
scripts/convert-manual-conventions.py |
Convert formatting to components |
Storybook provides an isolated environment for developing and testing UI components.
npm run storybookOpen http://localhost:6006 to view components in isolation.
Stories are co-located with components:
components/*.stories.tsx- Component storiescomponents/mdx/**/*.stories.tsx- MDX component stories
Use the theme toggle in Storybook's toolbar to switch between light and dark modes. The toggle applies the dark class to the <html> element, matching the app's behavior.
- Header - Navigation header with title display
- TableOfContents - Floating TOC modal
- MDX Components - Key, Knob, Tip, and other MDX-specific components
Storybook can open files in your editor (Cursor) when you click on story file links. To enable this:
-
Quick setup (automatic): The
npm run storybookscript automatically adds Cursor to PATH. -
Permanent setup (recommended): Add Cursor to your PATH permanently:
# Run the setup script source .storybook/setup-cursor.sh # Add to your shell profile (~/.zshrc or ~/.bash_profile) echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
After this, Storybook will be able to open files in Cursor without any PATH modifications.
- Run
npm run devfor live preview - Run
npm run storybookto test components in isolation - Run
npm run buildto catch MDX errors - Test search after build (requires full build)
- Check both light and dark themes
- Test on mobile viewport
- Unescaped
<or>- escape or use component - Missing
/on self-closing tags - Component not in MDXComponents registry
Search requires a production build. Run npm run build first.
Check that image paths match public/machines/<name>/images/.