joplin-plugin-html-blocks 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,307 +1,355 @@
1
- <img src="images/icon128.png" width="96" align="right" alt="HTML Blocks icon">
2
-
3
- # HTML Blocks - a Joplin plugin
4
-
5
- Write styled HTML sections in your notes with a simple markdown fence. No HTML,
6
- no inline CSS.
7
-
8
- ```
9
- !!! card_light_blue My card title
10
- Card contents, with the usual **markdown** you'd expect.
11
- !!!->
12
- ```
13
-
14
- ...renders as a light blue card in the note viewer, in exported HTML and in PDF
15
- exports. 371 block types are included, in 33 categories: cards in eleven styles,
16
- admonition-style callouts, twenty-two list styles, steps, timelines, stat tiles,
17
- progress bars, ratings, tables, pros and cons, FAQs, feature grids, chat
18
- transcripts, grids, banners, collapsible sections - plus charts (columns, bars,
19
- pie, donut, line, area, gauges), flow charts and trees, button rows, ASCII and
20
- big-text art, and a set of CSS animations.
21
-
22
- Charts and diagrams are drawn in plain CSS - no script, no images, no external
23
- libraries - so they render the same in the viewer, in the picker preview and in
24
- a PDF export, and they follow your Joplin theme like everything else.
25
-
26
- ## Screenshots
27
-
28
- ![The block picker](screenshots/01-block-picker.png)
29
-
30
- *The picker: filter 298 blocks by name, id, colour or theme, and insert one with
31
- a click.*
32
-
33
- ![Card blocks in the note viewer](screenshots/02-card-blocks.png)
34
-
35
- *Cards in the note viewer - solid, outline, tinted, gradient and elevated.*
36
-
37
- ![Checklists, stat tiles and grids](screenshots/03-lists-stats-grids.png)
38
-
39
- *Checklists, stat tiles, badge rows, grids and key/value tables.*
40
-
41
- ## Installation
42
-
43
- Search for **HTML Blocks** in *Tools &rarr; Options &rarr; Plugins*, or install
44
- `com.madusanka.htmlBlocks.jpl` with *Install from file*. Requires Joplin 3.0 or
45
- later on desktop.
46
-
47
- ## Documentation
48
-
49
- [**User manual (PDF)**](docs/HTML-Blocks-Manual.pdf) - 89 pages covering every
50
- block, with a rendered preview beside the markdown for each one. It is generated
51
- by the plugin's own renderer via `npm run manual`, so the previews always match
52
- what Joplin actually draws.
53
-
54
- ## The syntax
55
-
56
- ```
57
- !!! <type> <optional title>
58
- <contents>
59
- !!!->
60
- ```
61
-
62
- * The opening fence is `!!!` followed by a block type. A type always starts with
63
- a letter, which is what keeps it from being confused with a closing fence.
64
- * Anything after the type on the same line is the block **title**. It is
65
- optional, and inline markdown works in it.
66
- * The closing fence can be written `!!!->`, `!!!<-`, or just `!!!`.
67
- * Blocks **nest**. A card can contain a callout, which can contain a list.
68
- * An unclosed block runs to the end of the note rather than disappearing, so the
69
- preview stays useful while you are still typing.
70
- * An unrecognised type still renders (as a plain dashed box with the type shown
71
- in the corner) instead of silently vanishing.
72
-
73
- Most blocks treat their contents as ordinary markdown. The list-like ones
74
- (`list_*`, `steps`, `timeline`, `stats`, `progress`, `rating`, `keyvalue`,
75
- `table_*`, `pros_cons`, `faq_*`, `features_*`, `chat`, `badges`, `chart_*`,
76
- `flow*`, `tree*`, `buttons*`) treat **one line as one item** instead, and split
77
- fields on `::`:
78
-
79
- ```
80
- !!! steps How it works
81
- Install it :: Download and run the installer
82
- Configure it :: Open the settings screen
83
- Use it :: You are done
84
- !!!->
85
- ```
86
-
87
- Grids split their cells on a `---` line:
88
-
89
- ```
90
- !!! grid_2 Two things
91
- **Left**
92
-
93
- Left hand contents
94
- ---
95
- **Right**
96
-
97
- Right hand contents
98
- !!!->
99
- ```
100
-
101
- ## Inserting blocks
102
-
103
- Three ways, whichever suits you:
104
-
105
- * **Toolbar button** in the editor, or **Ctrl+Alt+H** - opens the picker. If you
106
- had text selected, it becomes the body of the new block.
107
- * **Tools → HTML Blocks** - every block, grouped by category.
108
- * **Command palette** - type "Insert block" and the block name.
109
-
110
- The picker shows each block as a **live preview** rather than a name: every tile
111
- is the real block, drawn by the same renderer the note viewer uses, so what you
112
- see in the dialog is what lands in the note. It opens on the blocks you reached
113
- for most recently, and the sidebar walks the categories. Typing filters across
114
- every category at once - by name, id, colour, mode or theme - the arrow keys walk
115
- the grid, and a double click inserts straight away.
116
-
117
- Previews can be turned off in *Tools → Options → HTML Blocks* if you would rather
118
- have a plain list of names.
119
-
120
- **Tools → HTML Blocks → Insert cheat sheet** drops one example of every single
121
- block type into the current note, which is the quickest way to see what they all
122
- look like.
123
-
124
- ## Block reference
125
-
126
- There are too many block types to list one by one here - the picker shows every
127
- one of them as a preview, and the [user manual](docs/HTML-Blocks-Manual.pdf)
128
- pairs each one with its markdown. The categories are:
129
-
130
- | Category | Blocks | For example |
131
- |---|---|---|
132
- | Cards | 21 | `card_light_blue`, `card_blue`, `card_indigo` |
133
- | Cards · Solid | 12 | `card_solid_blue`, `card_solid_indigo`, `card_solid_violet` |
134
- | Cards · Outline | 12 | `card_outline_blue`, `card_outline_indigo`, `card_outline_violet` |
135
- | Cards · Gradient | 12 | `card_gradient_blue`, `card_gradient_indigo`, `card_gradient_violet` |
136
- | Cards · Elevated | 12 | `card_elevated_blue`, `card_elevated_indigo`, `card_elevated_violet` |
137
- | Cards · Glass | 8 | `card_glass_blue`, `card_glass_violet`, `card_glass_pink` |
138
- | Cards · Neon | 8 | `card_neon_blue`, `card_neon_violet`, `card_neon_pink` |
139
- | Cards · Minimal | 8 | `card_minimal_blue`, `card_minimal_violet`, `card_minimal_pink` |
140
- | Cards · Ribbon | 8 | `card_ribbon_blue`, `card_ribbon_violet`, `card_ribbon_pink` |
141
- | Cards · Dashed | 8 | `card_dashed_blue`, `card_dashed_violet`, `card_dashed_pink` |
142
- | Cards · Underline | 8 | `card_underline_blue`, `card_underline_violet`, `card_underline_pink` |
143
- | Callouts | 28 | `callout_info`, `callout_tip`, `callout_warning` |
144
- | Callouts · Solid | 10 | `callout_info_solid`, `callout_tip_solid`, `callout_note_solid` |
145
- | Callouts · Outline | 10 | `callout_info_outline`, `callout_tip_outline`, `callout_note_outline` |
146
- | Callouts · Minimal | 10 | `callout_info_minimal`, `callout_tip_minimal`, `callout_note_minimal` |
147
- | Lists | 20 | `list_style1`, `list_pills`, `list_ranked` |
148
- | Lists · Themed | 9 | `list_style1_solid`, `list_style2_solid`, `list_style3_solid` |
149
- | Checklists | 4 | `list_check`, `checklist_outline`, `checklist_boxed` |
150
- | Steps | 5 | `steps`, `steps_solid`, `steps_outline` |
151
- | Timelines | 5 | `timeline`, `timeline_solid`, `timeline_outline` |
152
- | Numbers | 11 | `stats`, `progress`, `rating` |
153
- | Grids & columns | 13 | `grid_2`, `grid_3`, `columns_2` |
154
- | Boxes | 16 | `box_plain`, `box_terminal`, `note_paper` |
155
- | Banners & heroes | 12 | `banner`, `hero`, `section_title` |
156
- | Quotes | 5 | `quote_box`, `quote_pull`, `quote_card` |
157
- | Collapsible | 7 | `details`, `details_open`, `faq_list` |
158
- | Badges & tags | 5 | `badges`, `badges_tags`, `badges_square` |
159
- | Tables & data | 18 | `keyvalue`, `table`, `table_matrix` |
160
- | Charts | 18 | `chart_column`, `chart_pie`, `chart_line` |
161
- | Diagrams | 9 | `flow`, `flow_down`, `tree` |
162
- | Buttons & links | 7 | `buttons`, `buttons_pill`, `buttons_cta` |
163
- | ASCII & text art | 17 | `ascii_art`, `big_text`, `text_gradient` |
164
- | Animations | 15 | `anim_fade`, `anim_typewriter`, `anim_marquee` |
165
-
166
- Most ids read the way they look: `<family>_<theme>_<colour>`. The short,
167
- memorable ones are aliased - `info`, `tip`, `warning`, `note`, `quote`,
168
- `collapse`, `spoiler`, `kv`, `tags`, `terminal` and friends all work as types.
169
-
170
- **Line formats.** Blocks that take one line per item split their fields on `::`:
171
-
172
- | Type | Line format |
173
- |---|---|
174
- | `steps` | `title :: description` |
175
- | `timeline` | `when :: title :: description` |
176
- | `stats` | `value :: label` |
177
- | `progress` | `label :: 70` or `7/10` or `70%` |
178
- | `rating` | `label :: 4` (out of five) or `8/10` |
179
- | `keyvalue` | `key :: value` |
180
- | `table` | `cell :: cell :: cell` - the first line is the header row |
181
- | `pros_cons` | `+ a good thing` / `- a bad thing`, `:: Left :: Right` renames the columns |
182
- | `faq_list` | `question :: answer` |
183
- | `features_2` | `🚀 title :: description` |
184
- | `chat` | `who :: message`, a leading `>` forces the message right |
185
- | `badges` | split on commas and newlines |
186
- | `list_*` | one item per line; `[x]` / `[ ]` for checkboxes, two spaces to nest |
187
- | `grid_*`, `columns_*` | markdown cells split on a `---` line |
188
- | `chart_*` | `label :: value` - `1,200`, `1.2k`, `85%` and `7/10` all read as numbers |
189
- | `flow*` | `node :: caption` - one node per line, arrows drawn between them |
190
- | `tree*` | one entry per line, two spaces to nest, `name :: note` |
191
- | `buttons*` | `label :: https://... :: note`; a leading emoji becomes the icon |
192
- | `table_matrix` | `yes` / `no` / `partly` in a cell become a tick, a cross or a tilde |
193
- | `ascii_*` | kept exactly as typed - every space and blank line survives |
194
- | `big_text` | one line of text per banner, spelled out in block letters |
195
-
196
- ## Editor highlighting
197
-
198
- In the markdown editor the fences are coloured with the block's own colour, the
199
- lines inside get a tinted background and a coloured left bar, and nested blocks
200
- are indented. An unknown block type is underlined in red so typos are obvious
201
- before you switch to the viewer.
202
-
203
- Turn it off in **Tools → Options → HTML Blocks** if you'd rather not have it.
204
-
205
- ## Theming
206
-
207
- Every block derives all of its colours from one base colour, mixed against the
208
- current Joplin theme with `color-mix()`. That means the blocks follow your theme
209
- automatically - no separate dark mode stylesheet, and no hard-coded white
210
- backgrounds glaring at you in dark mode. On renderers without `color-mix()`
211
- support the blocks fall back to plain outlines.
212
-
213
- To restyle a block yourself, target it in your userstyle:
214
-
215
- ```css
216
- /* every block carries its type in a data attribute */
217
- .jhtml[data-jhtml-type="card_light_blue"] { --jh-color: #ff00aa; }
218
- ```
219
-
220
- ## Adding your own block types
221
-
222
- `tools/block-families.js` is the source of truth. It describes blocks by family -
223
- a family being one shape crossed with a set of colours and themes - and
224
- `npm run blocks` expands it into `src/blocks/blocks.json`, which is what ships.
225
- Edit the families, never the JSON: the JSON is regenerated (and your edits lost)
226
- on the next build.
227
-
228
- ```js
229
- { id: 'card_brown', label: 'Brown card', category: 'Cards', mode: 'card',
230
- color: 'brown', titleHint: 'Card title', bodyHint: 'Card contents' },
231
- ```
232
-
233
- ...then `npm run dist`. The new type is immediately available in the parser, the
234
- viewer stylesheet, the editor highlighter, the menus and the picker dialog -
235
- there is nowhere else to register it. The generator refuses to write a registry
236
- with a duplicate id or alias, an unknown mode or a missing colour, so a mistake
237
- in a family fails the build rather than shipping.
238
-
239
- A block is a **mode** (which renderer draws it) plus a **theme** (what the chrome
240
- around it looks like). The two are independent - any theme works on any mode:
241
-
242
- * `mode`: `card`, `callout`, `plain`, `quote`, `details`, `grid`, `list`,
243
- `steps`, `timeline`, `stats`, `progress`, `rating`, `badges`, `keyvalue`,
244
- `table`, `compare`, `faq`, `feature`, `chat`, `chart`, `flow`, `tree`,
245
- `buttons`, `art`, `bigtext`.
246
- * `theme`: `soft` (the default), `solid`, `outline`, `gradient`, `elevated`,
247
- `glass`, `neon`, `minimal`, `ribbon`, `dashed`, `underline`.
248
-
249
- The remaining fields (`icon`, `defaultTitle`, `variant`, `chart`, `animation`,
250
- `listStyle`, `ordered`, `columns`, `bare`, `open`, `aliases`) are documented in
251
- `src/blocks/types.ts`. `chart` picks which chart a `chart` block draws (`column`,
252
- `bar`, `pie`, `donut`, `line`, `area`, `gauge`, `stack`) and `animation` adds one
253
- of the motion presets - all of which switch themselves off again for readers with
254
- `prefers-reduced-motion` set.
255
-
256
- ## Building
257
-
258
- ```sh
259
- npm install
260
- npm run dist
261
- ```
262
-
263
- That regenerates the stylesheets, compiles everything and writes
264
- `publish/com.madusanka.htmlBlocks.jpl`.
265
-
266
- To install the built plugin: **Tools → Options → Plugins → the gear icon →
267
- Install from file**, and pick the `.jpl`.
268
-
269
- For development, point **Tools → Options → Plugins → Advanced → Development
270
- plugins** at this folder (`H:\Projects\joplin_html`) and restart Joplin. Joplin
271
- then loads `dist/` directly, so a `npm run dist` plus a restart picks up your
272
- changes.
273
-
274
- ## Layout
275
-
276
- ```
277
- src/
278
- index.ts main script: settings, commands, menus, picker dialog
279
- picker.ts builds the picker dialog's HTML
280
- blocks/
281
- blocks.json the registry - generated, every block type lives here
282
- types.ts registry types
283
- syntax.ts the fence grammar, shared by viewer and editor
284
- render.ts all HTML generation, shared by viewer and picker
285
- preview.ts the picker's thumbnails, on top of render.ts
286
- viewerCss.ts generated - the viewer stylesheet, as a string
287
- index.ts lookup helpers and the snippet builder
288
- markdownItPlugin/ markdown-it content script (the viewer)
289
- codeMirrorPlugin/ CodeMirror 6 content script (the editor)
290
- dialog/ assets for the block picker
291
- tools/
292
- block-families.js the block families - the source of truth
293
- generate-blocks.js expands the families into blocks.json
294
- generate-styles.js builds both stylesheets from the registry
295
- styles/ hand written CSS the generator wraps
296
- ```
297
-
298
- The picker's thumbnails go through `blocks/render.ts`, the same code the note
299
- viewer uses, so a preview cannot drift away from what Joplin actually draws. The
300
- generated viewer stylesheet is inlined into the dialog's HTML (as
301
- `blocks/viewerCss.ts`) for the same reason: Joplin replaces a dialog's content
302
- on every open, so the previews carry their own styling rather than depending on
303
- a second file resolving inside the dialog frame.
304
-
305
- `src/blocks/blocks.json`, `src/blocks/viewerCss.ts`,
306
- `src/markdownItPlugin/style.css` and `src/codeMirrorPlugin/style.css` are
307
- generated - edit `tools/block-families.js` and `tools/styles/*.css` instead.
1
+ <img src="images/icon128.png" width="96" align="right" alt="HTML Blocks icon">
2
+
3
+ # HTML Blocks - a Joplin plugin
4
+
5
+ Write styled HTML sections in your notes with a simple markdown fence. No HTML,
6
+ no inline CSS.
7
+
8
+ ```
9
+ !!! card_light_blue My card title
10
+ Card contents, with the usual **markdown** you'd expect.
11
+ !!!->
12
+ ```
13
+
14
+ ...renders as a light blue card in the note viewer, in exported HTML and in PDF
15
+ exports. 383 block types are included, in 34 categories: the twelve classic
16
+ admonitions, cards in eleven styles, callouts, twenty-two list styles, steps, timelines, stat tiles,
17
+ progress bars, ratings, tables, pros and cons, FAQs, feature grids, chat
18
+ transcripts, grids, banners, collapsible sections - plus charts (columns, bars,
19
+ pie, donut, line, area, gauges), flow charts and trees, button rows, ASCII and
20
+ big-text art, and a set of CSS animations.
21
+
22
+ Charts and diagrams are drawn in plain CSS - no script, no images, no external
23
+ libraries - so they render the same in the viewer, in the picker preview and in
24
+ a PDF export, and they follow your Joplin theme like everything else.
25
+
26
+ ## Screenshots
27
+
28
+ ![The twelve admonitions in the block picker](screenshots/01-admonitions.png)
29
+
30
+ *The twelve admonitions, styled to match the Admonition markdown extension so
31
+ existing notes migrate unchanged.*
32
+
33
+ ![The block picker](screenshots/02-block-picker.png)
34
+
35
+ *The picker: filter 383 blocks by name, id, colour or theme, and insert one with
36
+ a click. Every tile is a live preview, not a drawing.*
37
+
38
+ ![Charts drawn in plain CSS](screenshots/03-charts.png)
39
+
40
+ *Columns, bars, pie, donut, line, area and gauges - all plain CSS, no script and
41
+ no images.*
42
+
43
+ ![Big text and text art](screenshots/07-text-art.png)
44
+
45
+ *Big-text banners, gradient and neon headlines, outlines, 3D and rubber stamps.*
46
+
47
+ More of the picker: [stat tiles, progress bars and
48
+ ratings](screenshots/04-stats-progress-ratings.png), [tables and key/value
49
+ data](screenshots/05-tables-and-data.png), [collapsible sections and
50
+ FAQs](screenshots/06-collapsible-and-faq.png), and
51
+ [animations](screenshots/08-animations.png).
52
+
53
+ ## Installation
54
+
55
+ Search for **HTML Blocks** in *Tools &rarr; Options &rarr; Plugins*, or install
56
+ `com.madusanka.htmlBlocks.jpl` with *Install from file*. Requires Joplin 3.0 or
57
+ later on desktop.
58
+
59
+ ## Documentation
60
+
61
+ [**User manual (PDF)**](docs/HTML-Blocks-Manual.pdf) - 89 pages covering every
62
+ block, with a rendered preview beside the markdown for each one. It is generated
63
+ by the plugin's own renderer via `npm run manual`, so the previews always match
64
+ what Joplin actually draws.
65
+
66
+ ## The syntax
67
+
68
+ ```
69
+ !!! <type> <optional title>
70
+ <contents>
71
+ !!!->
72
+ ```
73
+
74
+ * The opening fence is `!!!` followed by a block type. A type always starts with
75
+ a letter, which is what keeps it from being confused with a closing fence.
76
+ * Anything after the type on the same line is the block **title**. It is
77
+ optional, and inline markdown works in it.
78
+ * The closing fence can be written `!!!->`, `!!!<-`, or just `!!!`.
79
+ * Blocks **nest**. A card can contain a callout, which can contain a list.
80
+ * An unclosed block runs to the end of the note rather than disappearing, so the
81
+ preview stays useful while you are still typing.
82
+ * An unrecognised type still renders (as a plain dashed box with the type shown
83
+ in the corner) instead of silently vanishing.
84
+
85
+ Most blocks treat their contents as ordinary markdown. The list-like ones
86
+ (`list_*`, `steps`, `timeline`, `stats`, `progress`, `rating`, `keyvalue`,
87
+ `table_*`, `pros_cons`, `faq_*`, `features_*`, `chat`, `badges`, `chart_*`,
88
+ `flow*`, `tree*`, `buttons*`) treat **one line as one item** instead, and split
89
+ fields on `::`:
90
+
91
+ ```
92
+ !!! steps How it works
93
+ Install it :: Download and run the installer
94
+ Configure it :: Open the settings screen
95
+ Use it :: You are done
96
+ !!!->
97
+ ```
98
+
99
+ Grids split their cells on a `---` line:
100
+
101
+ ```
102
+ !!! grid_2 Two things
103
+ **Left**
104
+
105
+ Left hand contents
106
+ ---
107
+ **Right**
108
+
109
+ Right hand contents
110
+ !!!->
111
+ ```
112
+
113
+ ## Inserting blocks
114
+
115
+ Three ways, whichever suits you:
116
+
117
+ * **Toolbar button** in the editor, or **Ctrl+Alt+H** - opens the picker. If you
118
+ had text selected, it becomes the body of the new block.
119
+ * **Tools → HTML Blocks** - every block, grouped by category.
120
+ * **Command palette** - type "Insert block" and the block name.
121
+
122
+ The picker shows each block as a **live preview** rather than a name: every tile
123
+ is the real block, drawn by the same renderer the note viewer uses, so what you
124
+ see in the dialog is what lands in the note. It opens on the blocks you reached
125
+ for most recently, and the sidebar walks the categories. Typing filters across
126
+ every category at once - by name, id, colour, mode or theme - the arrow keys walk
127
+ the grid, and a double click inserts straight away.
128
+
129
+ Previews can be turned off in *Tools → Options → HTML Blocks* if you would rather
130
+ have a plain list of names.
131
+
132
+ **Tools → HTML Blocks → Insert cheat sheet** drops one example of every single
133
+ block type into the current note, which is the quickest way to see what they all
134
+ look like.
135
+
136
+ ## Block reference
137
+
138
+ There are too many block types to list one by one here - the picker shows every
139
+ one of them as a preview, and the [user manual](docs/HTML-Blocks-Manual.pdf)
140
+ pairs each one with its markdown. The categories are:
141
+
142
+ | Category | Blocks | For example |
143
+ |---|---|---|
144
+ | Cards | 21 | `card_light_blue`, `card_blue`, `card_indigo` |
145
+ | Cards · Solid | 12 | `card_solid_blue`, `card_solid_indigo`, `card_solid_violet` |
146
+ | Cards · Outline | 12 | `card_outline_blue`, `card_outline_indigo`, `card_outline_violet` |
147
+ | Cards · Gradient | 12 | `card_gradient_blue`, `card_gradient_indigo`, `card_gradient_violet` |
148
+ | Cards · Elevated | 12 | `card_elevated_blue`, `card_elevated_indigo`, `card_elevated_violet` |
149
+ | Cards · Glass | 8 | `card_glass_blue`, `card_glass_violet`, `card_glass_pink` |
150
+ | Cards · Neon | 8 | `card_neon_blue`, `card_neon_violet`, `card_neon_pink` |
151
+ | Cards · Minimal | 8 | `card_minimal_blue`, `card_minimal_violet`, `card_minimal_pink` |
152
+ | Cards · Ribbon | 8 | `card_ribbon_blue`, `card_ribbon_violet`, `card_ribbon_pink` |
153
+ | Cards · Dashed | 8 | `card_dashed_blue`, `card_dashed_violet`, `card_dashed_pink` |
154
+ | Cards · Underline | 8 | `card_underline_blue`, `card_underline_violet`, `card_underline_pink` |
155
+ | Admonitions | 12 | `note`, `warning`, `danger` |
156
+ | Callouts | 28 | `callout_info`, `callout_tip`, `callout_warning` |
157
+ | Callouts · Solid | 10 | `callout_info_solid`, `callout_tip_solid`, `callout_note_solid` |
158
+ | Callouts · Outline | 10 | `callout_info_outline`, `callout_tip_outline`, `callout_note_outline` |
159
+ | Callouts · Minimal | 10 | `callout_info_minimal`, `callout_tip_minimal`, `callout_note_minimal` |
160
+ | Lists | 20 | `list_style1`, `list_pills`, `list_ranked` |
161
+ | Lists · Themed | 9 | `list_style1_solid`, `list_style2_solid`, `list_style3_solid` |
162
+ | Checklists | 4 | `list_check`, `checklist_outline`, `checklist_boxed` |
163
+ | Steps | 5 | `steps`, `steps_solid`, `steps_outline` |
164
+ | Timelines | 5 | `timeline`, `timeline_solid`, `timeline_outline` |
165
+ | Numbers | 11 | `stats`, `progress`, `rating` |
166
+ | Grids & columns | 13 | `grid_2`, `grid_3`, `columns_2` |
167
+ | Boxes | 16 | `box_plain`, `box_terminal`, `note_paper` |
168
+ | Banners & heroes | 12 | `banner`, `hero`, `section_title` |
169
+ | Quotes | 5 | `quote_box`, `quote_pull`, `quote_card` |
170
+ | Collapsible | 7 | `details`, `details_open`, `faq_list` |
171
+ | Badges & tags | 5 | `badges`, `badges_tags`, `badges_square` |
172
+ | Tables & data | 18 | `keyvalue`, `table`, `table_matrix` |
173
+ | Charts | 18 | `chart_column`, `chart_pie`, `chart_line` |
174
+ | Diagrams | 9 | `flow`, `flow_down`, `tree` |
175
+ | Buttons & links | 7 | `buttons`, `buttons_pill`, `buttons_cta` |
176
+ | ASCII & text art | 17 | `ascii_art`, `big_text`, `text_gradient` |
177
+ | Animations | 15 | `anim_fade`, `anim_typewriter`, `anim_marquee` |
178
+
179
+ Most ids read the way they look: `<family>_<theme>_<colour>`. The short,
180
+ memorable ones are aliased - `hint`, `caution`, `error`, `todo`, `summary`,
181
+ `collapse`, `spoiler`, `kv`, `tags`, `terminal` and friends all work as types.
182
+
183
+ **Line formats.** Blocks that take one line per item split their fields on `::`:
184
+
185
+ | Type | Line format |
186
+ |---|---|
187
+ | `steps` | `title :: description` |
188
+ | `timeline` | `when :: title :: description` |
189
+ | `stats` | `value :: label` |
190
+ | `progress` | `label :: 70` or `7/10` or `70%` |
191
+ | `rating` | `label :: 4` (out of five) or `8/10` |
192
+ | `keyvalue` | `key :: value` |
193
+ | `table` | `cell :: cell :: cell` - the first line is the header row |
194
+ | `pros_cons` | `+ a good thing` / `- a bad thing`, `:: Left :: Right` renames the columns |
195
+ | `faq_list` | `question :: answer` |
196
+ | `features_2` | `🚀 title :: description` |
197
+ | `chat` | `who :: message`, a leading `>` forces the message right |
198
+ | `badges` | split on commas and newlines |
199
+ | `list_*` | one item per line; `[x]` / `[ ]` for checkboxes, two spaces to nest |
200
+ | `grid_*`, `columns_*` | markdown cells split on a `---` line |
201
+ | `chart_*` | `label :: value` - `1,200`, `1.2k`, `85%` and `7/10` all read as numbers |
202
+ | `flow*` | `node :: caption` - one node per line, arrows drawn between them |
203
+ | `tree*` | one entry per line, two spaces to nest, `name :: note` |
204
+ | `buttons*` | `label :: https://... :: note`; a leading emoji becomes the icon |
205
+ | `table_matrix` | `yes` / `no` / `partly` in a cell become a tick, a cross or a tilde |
206
+ | `ascii_*` | kept exactly as typed - every space and blank line survives |
207
+ | `big_text` | one line of text per banner, spelled out in block letters |
208
+
209
+ ## Coming from the Admonition markdown extension
210
+
211
+ If your notes already use the [Admonition markdown
212
+ extension](https://joplinapp.org/plugins/plugin/org.joplinapp.plugins.admonition/),
213
+ they render here unchanged - no rewriting, and no need to keep both plugins
214
+ installed.
215
+
216
+ The fence syntax was already the same (`!!! type Optional title` ... `!!!`), and
217
+ its twelve types are first-class blocks here, styled to match: the
218
+ [mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
219
+ colours, the same title-bar emoji, the same accent rule down the left edge.
220
+
221
+ | | | | |
222
+ |---|---|---|---|
223
+ | `note` | `abstract` | `info` | `tip` |
224
+ | `success` | `question` | `warning` | `failure` |
225
+ | `danger` | `bug` | `example` | `quote` |
226
+
227
+ ```
228
+ !!! warning Watch out
229
+ Renders exactly as it did under the old plugin.
230
+ !!!
231
+ ```
232
+
233
+ Two small differences, both cosmetic:
234
+
235
+ * The title band uses your Joplin background rather than a fixed white, so the
236
+ blocks stay readable in a dark theme.
237
+ * A block with no title of its own is headed `Note` rather than `note`.
238
+
239
+ These twelve are separate from this plugin's own `callout_*` family, which keeps
240
+ its rounded, tinted look and its own set of types - use either, or both. Two ids
241
+ moved to make room: `!!! quote` is now the admonition, and the plugin's original
242
+ quote block is `quote_box` (or `blockquote`).
243
+
244
+ ## Editor highlighting
245
+
246
+ In the markdown editor the fences are coloured with the block's own colour, the
247
+ lines inside get a tinted background and a coloured left bar, and nested blocks
248
+ are indented. An unknown block type is underlined in red so typos are obvious
249
+ before you switch to the viewer.
250
+
251
+ Turn it off in **Tools → Options → HTML Blocks** if you'd rather not have it.
252
+
253
+ ## Theming
254
+
255
+ Every block derives all of its colours from one base colour, mixed against the
256
+ current Joplin theme with `color-mix()`. That means the blocks follow your theme
257
+ automatically - no separate dark mode stylesheet, and no hard-coded white
258
+ backgrounds glaring at you in dark mode. On renderers without `color-mix()`
259
+ support the blocks fall back to plain outlines.
260
+
261
+ To restyle a block yourself, target it in your userstyle:
262
+
263
+ ```css
264
+ /* every block carries its type in a data attribute */
265
+ .jhtml[data-jhtml-type="card_light_blue"] { --jh-color: #ff00aa; }
266
+ ```
267
+
268
+ ## Adding your own block types
269
+
270
+ `tools/block-families.js` is the source of truth. It describes blocks by family -
271
+ a family being one shape crossed with a set of colours and themes - and
272
+ `npm run blocks` expands it into `src/blocks/blocks.json`, which is what ships.
273
+ Edit the families, never the JSON: the JSON is regenerated (and your edits lost)
274
+ on the next build.
275
+
276
+ ```js
277
+ { id: 'card_brown', label: 'Brown card', category: 'Cards', mode: 'card',
278
+ color: 'brown', titleHint: 'Card title', bodyHint: 'Card contents' },
279
+ ```
280
+
281
+ ...then `npm run dist`. The new type is immediately available in the parser, the
282
+ viewer stylesheet, the editor highlighter, the menus and the picker dialog -
283
+ there is nowhere else to register it. The generator refuses to write a registry
284
+ with a duplicate id or alias, an unknown mode or a missing colour, so a mistake
285
+ in a family fails the build rather than shipping.
286
+
287
+ A block is a **mode** (which renderer draws it) plus a **theme** (what the chrome
288
+ around it looks like). The two are independent - any theme works on any mode:
289
+
290
+ * `mode`: `card`, `callout`, `plain`, `quote`, `details`, `grid`, `list`,
291
+ `steps`, `timeline`, `stats`, `progress`, `rating`, `badges`, `keyvalue`,
292
+ `table`, `compare`, `faq`, `feature`, `chat`, `chart`, `flow`, `tree`,
293
+ `buttons`, `art`, `bigtext`.
294
+ * `theme`: `soft` (the default), `solid`, `outline`, `gradient`, `elevated`,
295
+ `glass`, `neon`, `minimal`, `ribbon`, `dashed`, `underline`, `admonition`.
296
+
297
+ The remaining fields (`icon`, `defaultTitle`, `variant`, `chart`, `animation`,
298
+ `listStyle`, `ordered`, `columns`, `bare`, `open`, `aliases`) are documented in
299
+ `src/blocks/types.ts`. `chart` picks which chart a `chart` block draws (`column`,
300
+ `bar`, `pie`, `donut`, `line`, `area`, `gauge`, `stack`) and `animation` adds one
301
+ of the motion presets - all of which switch themselves off again for readers with
302
+ `prefers-reduced-motion` set.
303
+
304
+ ## Building
305
+
306
+ ```sh
307
+ npm install
308
+ npm run dist
309
+ ```
310
+
311
+ That regenerates the stylesheets, compiles everything and writes
312
+ `publish/com.madusanka.htmlBlocks.jpl`.
313
+
314
+ To install the built plugin: **Tools → Options → Plugins → the gear icon →
315
+ Install from file**, and pick the `.jpl`.
316
+
317
+ For development, point **Tools → Options → Plugins → Advanced → Development
318
+ plugins** at this folder (`H:\Projects\joplin_html`) and restart Joplin. Joplin
319
+ then loads `dist/` directly, so a `npm run dist` plus a restart picks up your
320
+ changes.
321
+
322
+ ## Layout
323
+
324
+ ```
325
+ src/
326
+ index.ts main script: settings, commands, menus, picker dialog
327
+ picker.ts builds the picker dialog's HTML
328
+ blocks/
329
+ blocks.json the registry - generated, every block type lives here
330
+ types.ts registry types
331
+ syntax.ts the fence grammar, shared by viewer and editor
332
+ render.ts all HTML generation, shared by viewer and picker
333
+ preview.ts the picker's thumbnails, on top of render.ts
334
+ viewerCss.ts generated - the viewer stylesheet, as a string
335
+ index.ts lookup helpers and the snippet builder
336
+ markdownItPlugin/ markdown-it content script (the viewer)
337
+ codeMirrorPlugin/ CodeMirror 6 content script (the editor)
338
+ dialog/ assets for the block picker
339
+ tools/
340
+ block-families.js the block families - the source of truth
341
+ generate-blocks.js expands the families into blocks.json
342
+ generate-styles.js builds both stylesheets from the registry
343
+ styles/ hand written CSS the generator wraps
344
+ ```
345
+
346
+ The picker's thumbnails go through `blocks/render.ts`, the same code the note
347
+ viewer uses, so a preview cannot drift away from what Joplin actually draws. The
348
+ generated viewer stylesheet is inlined into the dialog's HTML (as
349
+ `blocks/viewerCss.ts`) for the same reason: Joplin replaces a dialog's content
350
+ on every open, so the previews carry their own styling rather than depending on
351
+ a second file resolving inside the dialog frame.
352
+
353
+ `src/blocks/blocks.json`, `src/blocks/viewerCss.ts`,
354
+ `src/markdownItPlugin/style.css` and `src/codeMirrorPlugin/style.css` are
355
+ generated - edit `tools/block-families.js` and `tools/styles/*.css` instead.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "joplin-plugin-html-blocks",
3
- "version": "1.2.0",
3
+ "version": "1.3.0",
4
4
  "description": "Write styled HTML sections - cards, callouts, fancy lists, steps, timelines, grids and more - using a simple `!!! type` ... `!!!->` markdown fence.",
5
5
  "author": "madusanka",
6
6
  "scripts": {
@@ -7,7 +7,7 @@
7
7
  "desktop",
8
8
  "mobile"
9
9
  ],
10
- "version": "1.2.0",
10
+ "version": "1.3.0",
11
11
  "name": "HTML Blocks",
12
12
  "description": "Write styled HTML sections - cards, callouts, fancy lists, steps, timelines, grids and more - using a simple `!!! type` ... `!!!->` markdown fence.",
13
13
  "author": "madusanka",
@@ -27,16 +27,36 @@
27
27
  ],
28
28
  "screenshots": [
29
29
  {
30
- "src": "screenshots/01-block-picker.png",
31
- "label": "The block picker: filter 298 blocks by name, id, colour or theme and insert one with a click"
30
+ "src": "screenshots/01-admonitions.png",
31
+ "label": "The twelve admonitions, styled to match the Admonition markdown extension so existing notes migrate unchanged"
32
32
  },
33
33
  {
34
- "src": "screenshots/02-card-blocks.png",
35
- "label": "Card blocks in the note viewer - solid, outline, tinted, gradient and elevated styles"
34
+ "src": "screenshots/02-block-picker.png",
35
+ "label": "The block picker: filter 383 blocks by name, id, colour or theme and insert one with a click"
36
36
  },
37
37
  {
38
- "src": "screenshots/03-lists-stats-grids.png",
39
- "label": "Checklists, stat tiles, badge rows, grids and key/value tables"
38
+ "src": "screenshots/03-charts.png",
39
+ "label": "Charts drawn in plain CSS - columns, bars, pie, donut, line, area and gauges"
40
+ },
41
+ {
42
+ "src": "screenshots/04-stats-progress-ratings.png",
43
+ "label": "Stat tiles, progress bars and star ratings"
44
+ },
45
+ {
46
+ "src": "screenshots/05-tables-and-data.png",
47
+ "label": "Tables and key/value data, in striped, bordered, compact and minimal styles"
48
+ },
49
+ {
50
+ "src": "screenshots/06-collapsible-and-faq.png",
51
+ "label": "Collapsible sections and FAQ lists"
52
+ },
53
+ {
54
+ "src": "screenshots/07-text-art.png",
55
+ "label": "Big-text banners, gradient and neon headlines, outlines, 3D and rubber stamps"
56
+ },
57
+ {
58
+ "src": "screenshots/08-animations.png",
59
+ "label": "Fifteen CSS animations, all disabled again under prefers-reduced-motion"
40
60
  }
41
61
  ],
42
62
  "icons": {
@@ -49,6 +69,6 @@
49
69
  "src": "images/promo_tile.png",
50
70
  "label": "HTML Blocks - styled cards, callouts and lists from a simple markdown fence"
51
71
  },
52
- "_publish_hash": "sha256:e630df4c140770d24725da9006a03add9f1970f06ab8bddef7d24a7cff5c493b",
53
- "_publish_commit": "main:955360b5ed8bfe364d1a5939ee58ed4e0c7b2911"
72
+ "_publish_hash": "sha256:9166723936b229542fcb5f38625d2bf49687e29c1b98aec640f1fef3d4a42f00",
73
+ "_publish_commit": "main:58718729848b6ad578f6b4b876b771335fd42d44"
54
74
  }