Write a guide
Every guide on Jolts was written by someone who built the thing.
The visual editor shows the page as it will ship.
How it works
- Write in the browser (photos drop right in), or fork the repo and copy
content/TEMPLATE.mdxintocontent/guides/your-slug/index.mdx(or concepts/tools). Take plenty of photos while you build. - Write with the block registry below. Plain markdown for prose, blocks for structure - no arbitrary JSX.
- Hit Save changes and the editor opens a pull request for you. A reviewer goes through it with you before it ships.
- Once it merges, your guide is live with your name and GitHub avatar on it.
The bar for guides
A guide has to be clear, easy to follow, and structured well enough that someone can build the thing from it without getting lost. Concepts and tools are held to the same bar.
The block registry
These blocks are the whole vocabulary. Anything else fails CI.
| <Step> | one photo, one action |
| <PartsList> | renders the frontmatter parts table |
| <Tool> | chip linking to a tool page - never teach a tool inline |
| <ConceptLink> | inline link to a concept - never explain one inline |
| <Warning> | anything they shouldn't learn the hard way |
| <Checkpoint> | what they should have before building further |
| <Schematic> | wiring diagram or figure with a caption |
| <PinTable> | pin → signal → why |
| <Video> | embedded YouTube, for technique that reads badly |
| <Difficulty> | inline difficulty chip |
| <ExternalGuide> | link out to Codex, Adafruit, datasheets |
| <ReadMore> | wraps guide-end ExternalGuides into a further-reading section |
| <ShipIt> | the end-of-guide banner |
Linking discipline
Link to a concept page instead of explaining the concept inline, and to a tool page instead of teaching the tool. Guides stay short that way, and each idea is written once, where people go looking for it. For anything outside what Jolts covers, link out with <ExternalGuide>.
Licensing
By submitting a pull request you agree that your guide text, images, and design files (KiCad, STLs) are licensed CC BY-SA 4.0 and code snippets are MIT. Your name stays on the guide.
If you’ve built something that isn’t in the guides yet, write it up.