The complete documentation, manuals, and troubleshooting library for Playtronica — the small Berlin/Lisbon studio that builds MIDI devices for turning plants, bodies, fruit, and everyday objects into musical instruments.
This is the source code and the source of truth for help.playtronica.com. Every page on the live help center is one Markdown file in this repository.
Why open-source? Because the help center is more useful when AI tools, search engines, makers, educators, and integrators can read it, link it, fork it, and translate it. The content is licensed CC-BY-4.0 so anyone can quote, remix, and republish it with attribution.
- 40+ Markdown articles covering every Playtronica device — TouchMe, Playtron, Biotron, Orbita, Scales — plus connecting to DAWs, online synths, mobile apps, and grounding physics.
- A brutalist, mobile-first Next.js site with sub-50 ms search via Pagefind, no client-side JavaScript bloat, and a documented design system (
docs/DESIGN-TOKENS.md). - A documented writing process: voice specification, quality-review rubric, and a monthly refresh loop — see
docs/. - Optional AI-search surfaces:
llms.txt, JSON-LD structured data, OpenGraph metadata, sitemap, robots.txt — built for ChatGPT, Claude, Perplexity, and Google.
git clone https://github.com/Playtronica/help.git
cd help
npm install
npm run dev # http://localhost:3001That is the whole setup. No database, no CMS, no API keys required.
To build the production bundle (static HTML + Pagefind index + AI-search files):
npm run build:export # writes everything to out/
npx serve outCloudflare Pages runs this command on every push to main and deploys the out/ directory.
.
├── app/ Next.js App Router pages
│ ├── layout.tsx Header + sidebar shell, JSON-LD injection
│ ├── page.tsx Homepage (bento grid)
│ └── [section]/[slug]/ Dynamic article route
├── components/ SearchBar, Sidebar, FeedbackWidget, Analytics, …
├── content/en/ Source of truth — every public page as Markdown
│ ├── getting-started/
│ ├── devices/
│ ├── software/
│ ├── troubleshooting/
│ ├── orders/
│ ├── sound/
│ ├── professionals/
│ └── site/
├── lib/ content loader, whatsapp-feedback helper, …
├── public/ _headers, _redirects, illustrations, llms.txt
├── scripts/ build-search-index.mjs, audit-cross-references.py
├── docs/ Voice spec, design tokens, AI-SEO, process
└── .github/ Issue + PR templates, CI workflow
Every page is plain Markdown with YAML frontmatter:
---
title: "Track your order"
slug: track-your-order
section: orders
summary: "One-line description used for SEO meta and search snippets."
order: 1
status: edited-2026-05
emoji: 🔍
---
Real content starts here. Use H2 (`##`) for sections, blockquotes for callouts.Drop the file into content/en/<section>/<slug>.md, run npm run dev, the sidebar picks it up. Run npm run audit before committing to validate every internal link and anchor.
Conventions and the voice we write in: see docs/VOICE.md. Style scoring rubric: docs/REVIEW-PROMPT.md.
Pagefind indexes the built HTML at deploy time. data-pagefind-body wraps article content; data-pagefind-meta="title" marks each title. The SearchBar component fetches /_pagefind/pagefind.js lazily on first input.
In dev mode (npm run dev) we use a lightweight JSON index generated by scripts/build-search-index.mjs so search-in-body works without running a production build.
We treat AI search (ChatGPT, Claude, Perplexity, You.com, Brave Leo, Arc Max…) as a first-class traffic source equal to Google. Every page ships with:
- A short
summaryin frontmatter that becomes<meta name="description">and Open Graph description. - JSON-LD structured data —
Articleschema on articles,FAQPageon pages with collapsible FAQ blocks. - OpenGraph + Twitter card metadata.
- A site-wide
llms.txt(emerging standard) andllms-full.txtfor LLM crawlers. - A
robots.txtthat explicitly allows GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Bytespider, and other major AI crawlers.
Full rationale and configuration: docs/AI-SEO.md.
Every tracker is optional. Set the env var, the tracker activates. Leave it unset, it is a no-op.
| Tracker | Env var | What for |
|---|---|---|
| Google Analytics 4 | NEXT_PUBLIC_GA4_ID |
Funnel, source/medium, Shopify cross-domain attribution |
| Microsoft Clarity | NEXT_PUBLIC_CLARITY_ID |
Heatmaps and session recordings |
| Cloudflare Web Analytics | NEXT_PUBLIC_CF_WEB_ANALYTICS_TOKEN |
Cookieless real-user performance |
| WhatsApp feedback | NEXT_PUBLIC_WHATSAPP_FEEDBACK_NUMBER |
Direct-to-team feedback channel (optional) |
Copy .env.example to .env.local for local dev. Set the same vars in Cloudflare Pages → Settings → Environment Variables for production.
Spotted a typo, a broken link, a wrong instruction? Open an issue or send a pull request — we read every one.
- Quick fixes (typos, broken links, factual errors): use the GitHub web editor to edit a Markdown file directly. Submit as a pull request.
- New pages or larger changes: read CONTRIBUTING.md first. The voice we write in is unusual on purpose and worth a look before you write.
- Community discussion: open a thread in GitHub Discussions.
- Security issues: see SECURITY.md.
All contributors agree to our Code of Conduct.
- Code (everything in
app/,components/,lib/,scripts/,public/_*, config files) — MIT License. - Content (everything in
content/,docs/, illustrations and screenshots authored by Playtronica) — Creative Commons Attribution 4.0 International (CC-BY-4.0).
Quote, fork, translate, redistribute. Just attribute "Playtronica Help Center" with a link back to help.playtronica.com.
Some third-party assets — product photos, YouTube embeds, app icons — are owned by their respective creators and used under fair-use for documentation purposes.
Built with Next.js, Tailwind CSS, Pagefind, remark, and a lot of feedback from the Playtronica Friends community on Facebook. The voice and structure were shaped over a hundred sessions of Claude reading every support thread we ever sent.
The hardware itself is dreamed up and assembled by Andrey Manirko and the Playtronica team in Berlin and Lisbon.
Last meaningful update: 2026-05-20. See CHANGELOG.md for the version history.