PlynxDoc format
PlynxDoc is the house format for docs and forum articles on plynx.cc. It stays plain-text friendly for AI, version control and quick edits, but supports richer blocks when you need tables, charts, collapses, diagrams, live widget canvases or multi-language code.
Core blocks
| Block | Syntax | Notes | |||||
|---|---|---|---|---|---|---|---|
| Heading | #, ##, ### | Standard markdown headings | |||||
| Paragraph | plain text | Inline links and inline code supported | |||||
| Lists | - item or 1. item | Flat ordered or unordered lists | |||||
| Code fence | ```lang file | Optional filename in the opening fence | |||||
| Code tabs | :::codegroup + @@tab | Multi-language side-by-side snippets | |||||
| Callout | `:::callout note | Title` | Rich note box | ||||
| Step | `:::step 1 | Title` | Numbered process card | ||||
| Media | :::image, :::video | SVG, PNG, MP4, poster frames | |||||
| Collapse | `:::collapse open | Title` | Titled or untitled collapse block | ||||
| Table | Markdown table or :::table compact | Default, compact, spec, matrix | |||||
| Chart | `:::chart line | Title | url.csv | x | y | large` | CSV-backed interactive chart |
| Canvas | :::canvas + item: rows | Live dashboard showcase blocks with widgets | |||||
| Diagram | :::diagram ... ::: | Logic / step flow | |||||
| Venn | `:::venn A | B | Overlap` | 2-set comparison | |||
| Latex | :::latex c = \sqrt{a^2+b^2} | Rendered with KaTeX |
| Suffix | Meaning |
|---|---|
default | Comfortable article table |
compact | Tight vertical rhythm |
spec | Property/value docs |
matrix | Dense comparison grid |
Inline formatting
- Use
inline codefor pins, commands and tokens. - Use links for cross-references.
- Keep prose compact: PlynxDoc prefers dense documentation over oversized markdown walls.
Code tabs
BLYNK_WRITE(V0) { digitalWrite(RELAY_PIN, param.asInt());}Collapsible sections
toggleWhy use a collapse block
Use collapses for verbose packet dumps, optional derivations, legal caveats or raw debug logs.
You can omit the title if you want a silent expandable body.
Charts from CSV
CSV chart behavior
Hover or touch inside the chart to inspect the nearest sample. PlynxDoc charts render a guide line, a point marker, and a live value chip in the top-right corner of the chart box.
chart
Humidity over time
| Size | Syntax suffix | Typical use | |
|---|---|---|---|
| Small | ` | small` | Side note or compact KPI |
| Medium | ` | medium` | Default article chart |
| Large | ` | large` | Main chart using full horizontal room |
Canvas blocks
Use canvas blocks when a plain screenshot is not enough and you want a docs or forum article to show a real widget arrangement.
Canvas behavior
Canvas blocks are rendered with the same website dashboard canvas component used elsewhere in the site. In docs and forum preview, sliders and buttons can be interacted with locally without turning the article into a live backend control surface.
:::canvastitle: greenhouse slider demotheme: autosize: 8x3item: slider|label=Fan speed|col=0|row=0|w=5|h=1|value=68|tone=tealitem: value|label=PWM|col=5|row=0|w=3|h=1|value=68|tone=violet:::| Canvas key | Meaning | ||
|---|---|---|---|
title: | Label shown in the canvas bezel | ||
theme: | auto, app-dark, app-light, pastel | ||
size: | Grid footprint, used here as cols x rows | ||
item: | One widget entry with `type | key=value | ...` |
col,row,w,h | Widget position and size on the 8-column grid | ||
value | Preview value shown locally in the article | ||
tone | teal, blue, amber, violet |
The forum editor toolbar inserts this exact slider-oriented canvas template with ⌘⌥V, so makers can drop a working showcase block into support threads or build logs without starting from scratch.
Tables
| Property | Value |
|---|---|
| Default size | 2 × 2 |
| Min size | 1 × 1 |
| Resize | both axes |
| Syntax | Good for | Why |
|---|---|---|
| markdown table | quick docs | shortest authoring path |
:::table compact | key/value lists | tighter vertical rhythm |
:::table spec | widget contracts | stronger first column emphasis |
:::table matrix | comparisons | equal-width dense cells |
| Key | Meaning |
|---|---|
⌘B | Toggle dashboard sidebar |
⌘E | Toggle forum editor preview |
⌘S | Save draft |
Media
Best practices
- Put the important answer above the fold.
- Split dense sections with callouts, steps or collapses.
- When documenting widgets, include sizing, resize rules and firmware contract.
- Prefer local media files for long-term durability.
- If a block has a shortcut in the editor, expose it in the tooltip so users learn it.
- Prefer
spectables for widgets, because they keep property labels readable on wide screens and mobile. - Use canvas blocks for widget behavior demos, not giant screenshots with annotations baked into pixels.