joplin-plugin-html-blocks 1.0.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/LICENSE +21 -0
- package/README.md +255 -0
- package/package.json +45 -0
- package/publish/com.madusanka.htmlBlocks.jpl +0 -0
- package/publish/com.madusanka.htmlBlocks.json +28 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 madusanka
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
# HTML Blocks - a Joplin plugin
|
|
2
|
+
|
|
3
|
+
Write styled HTML sections in your notes with a simple markdown fence. No HTML,
|
|
4
|
+
no inline CSS.
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
!!! card_light_blue My card title
|
|
8
|
+
Card contents, with the usual **markdown** you'd expect.
|
|
9
|
+
!!!->
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
...renders as a light blue card in the note viewer, in exported HTML and in PDF
|
|
13
|
+
exports. 47 block types are included: cards, admonition-style callouts, six list
|
|
14
|
+
styles, steps, timelines, stat tiles, grids, banners, collapsible sections and
|
|
15
|
+
more.
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
Search for **HTML Blocks** in *Tools → Options → Plugins*, or install
|
|
20
|
+
`com.madusanka.htmlBlocks.jpl` with *Install from file*. Requires Joplin 3.0 or
|
|
21
|
+
later on desktop.
|
|
22
|
+
|
|
23
|
+
## Documentation
|
|
24
|
+
|
|
25
|
+
[**User manual (PDF)**](docs/HTML-Blocks-Manual.pdf) - 20 pages covering every
|
|
26
|
+
block, with a rendered preview beside the markdown for each one. It is generated
|
|
27
|
+
by the plugin's own renderer via `npm run manual`, so the previews always match
|
|
28
|
+
what Joplin actually draws.
|
|
29
|
+
|
|
30
|
+
## The syntax
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
!!! <type> <optional title>
|
|
34
|
+
<contents>
|
|
35
|
+
!!!->
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
* The opening fence is `!!!` followed by a block type. A type always starts with
|
|
39
|
+
a letter, which is what keeps it from being confused with a closing fence.
|
|
40
|
+
* Anything after the type on the same line is the block **title**. It is
|
|
41
|
+
optional, and inline markdown works in it.
|
|
42
|
+
* The closing fence can be written `!!!->`, `!!!<-`, or just `!!!`.
|
|
43
|
+
* Blocks **nest**. A card can contain a callout, which can contain a list.
|
|
44
|
+
* An unclosed block runs to the end of the note rather than disappearing, so the
|
|
45
|
+
preview stays useful while you are still typing.
|
|
46
|
+
* An unrecognised type still renders (as a plain dashed box with the type shown
|
|
47
|
+
in the corner) instead of silently vanishing.
|
|
48
|
+
|
|
49
|
+
Most blocks treat their contents as ordinary markdown. The list-like ones
|
|
50
|
+
(`list_*`, `steps`, `timeline`, `stats`, `keyvalue`, `badges`) treat **one line
|
|
51
|
+
as one item** instead, and split fields on `::`:
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
!!! steps How it works
|
|
55
|
+
Install it :: Download and run the installer
|
|
56
|
+
Configure it :: Open the settings screen
|
|
57
|
+
Use it :: You are done
|
|
58
|
+
!!!->
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Grids split their cells on a `---` line:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
!!! grid_2 Two things
|
|
65
|
+
**Left**
|
|
66
|
+
|
|
67
|
+
Left hand contents
|
|
68
|
+
---
|
|
69
|
+
**Right**
|
|
70
|
+
|
|
71
|
+
Right hand contents
|
|
72
|
+
!!!->
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Inserting blocks
|
|
76
|
+
|
|
77
|
+
Three ways, whichever suits you:
|
|
78
|
+
|
|
79
|
+
* **Toolbar button** in the editor, or **Ctrl+Alt+H** - opens a searchable
|
|
80
|
+
picker. If you had text selected, it becomes the body of the new block.
|
|
81
|
+
* **Tools → HTML Blocks** - every block, grouped by category.
|
|
82
|
+
* **Command palette** - type "Insert block" and the block name.
|
|
83
|
+
|
|
84
|
+
**Tools → HTML Blocks → Insert cheat sheet** drops one example of every single
|
|
85
|
+
block type into the current note, which is the quickest way to see what they all
|
|
86
|
+
look like.
|
|
87
|
+
|
|
88
|
+
## Block reference
|
|
89
|
+
|
|
90
|
+
**Cards** - a titled, tinted box with a coloured left edge.
|
|
91
|
+
|
|
92
|
+
| Type | Renders | Aliases |
|
|
93
|
+
|---|---|---|
|
|
94
|
+
| `card_light_blue` | Light blue card | `card_lightblue`, `card_sky` |
|
|
95
|
+
| `card_blue` | Blue card | |
|
|
96
|
+
| `card_indigo` | Indigo card | |
|
|
97
|
+
| `card_teal` | Teal card | |
|
|
98
|
+
| `card_green` | Green card | |
|
|
99
|
+
| `card_light_green` | Light green card | `card_lightgreen`, `card_lime` |
|
|
100
|
+
| `card_yellow` | Yellow card | |
|
|
101
|
+
| `card_orange` | Orange card | |
|
|
102
|
+
| `card_red` | Red card | |
|
|
103
|
+
| `card_pink` | Pink card | |
|
|
104
|
+
| `card_purple` | Purple card | |
|
|
105
|
+
| `card_gray` | Gray card | `card_grey` |
|
|
106
|
+
| `card_dark` | Dark card | |
|
|
107
|
+
|
|
108
|
+
**Callouts** - like cards, but with an icon and a default title, in the style of
|
|
109
|
+
the admonition plugin.
|
|
110
|
+
|
|
111
|
+
| Type | Renders | Aliases |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| `callout_info` | ℹ️ Info | `info` |
|
|
114
|
+
| `callout_tip` | 💡 Tip | `tip`, `hint` |
|
|
115
|
+
| `callout_note` | 📝 Note | `note` |
|
|
116
|
+
| `callout_success` | ✅ Success | `success`, `done` |
|
|
117
|
+
| `callout_warning` | ⚠️ Warning | `warning`, `caution` |
|
|
118
|
+
| `callout_danger` | ⛔ Danger | `danger`, `error` |
|
|
119
|
+
| `callout_question` | ❓ Question | `question`, `faq` |
|
|
120
|
+
| `callout_example` | 🧪 Example | `example` |
|
|
121
|
+
| `callout_bug` | 🐛 Bug | `bug` |
|
|
122
|
+
| `callout_todo` | 📌 To do | `todo` |
|
|
123
|
+
|
|
124
|
+
**Lists** - one line per item. A leading `-` is optional, and two spaces of
|
|
125
|
+
indentation nests an item one level (up to three).
|
|
126
|
+
|
|
127
|
+
| Type | Renders |
|
|
128
|
+
|---|---|
|
|
129
|
+
| `list_style1` | Coloured dot bullets |
|
|
130
|
+
| `list_style2` | Numbered circles |
|
|
131
|
+
| `list_style3` | Check marks |
|
|
132
|
+
| `list_style4` | Arrows |
|
|
133
|
+
| `list_style5` | Boxed rows |
|
|
134
|
+
| `list_style6` | Rows separated by rules |
|
|
135
|
+
| `list_check` | Checkboxes - prefix a line with `[x]` or `[ ]` |
|
|
136
|
+
|
|
137
|
+
**Layout**
|
|
138
|
+
|
|
139
|
+
| Type | Renders | Line format |
|
|
140
|
+
|---|---|---|
|
|
141
|
+
| `steps` | Numbered steps joined by a rail | `title :: description` |
|
|
142
|
+
| `timeline` | Vertical timeline | `when :: title :: description` |
|
|
143
|
+
| `stats` | Row of big-number tiles | `value :: label` |
|
|
144
|
+
| `grid_2` | Two column grid of cards | cells split on `---` |
|
|
145
|
+
| `grid_3` | Three column grid of cards | cells split on `---` |
|
|
146
|
+
| `columns_2` | Two plain columns, no card chrome | cells split on `---` |
|
|
147
|
+
|
|
148
|
+
**Boxes**
|
|
149
|
+
|
|
150
|
+
| Type | Renders | Aliases |
|
|
151
|
+
|---|---|---|
|
|
152
|
+
| `box_plain` | Neutral box | |
|
|
153
|
+
| `box_dashed` | Dashed outline box | |
|
|
154
|
+
| `box_shadow` | Box with a drop shadow | |
|
|
155
|
+
| `banner` | Gradient banner, white text | |
|
|
156
|
+
| `hero` | Large centred hero section | |
|
|
157
|
+
| `highlight` | Thick coloured left strip | `highlight_box` |
|
|
158
|
+
|
|
159
|
+
**Special**
|
|
160
|
+
|
|
161
|
+
| Type | Renders | Aliases |
|
|
162
|
+
|---|---|---|
|
|
163
|
+
| `quote_box` | Pull quote; the title becomes the attribution | `quote` |
|
|
164
|
+
| `details` | Collapsible `<details>` section | `collapse`, `spoiler` |
|
|
165
|
+
| `details_open` | Collapsible, expanded by default | |
|
|
166
|
+
| `badges` | Row of pill badges, split on commas and newlines | |
|
|
167
|
+
| `keyvalue` | Two column key/value table (`key :: value`) | `kv`, `fields` |
|
|
168
|
+
|
|
169
|
+
## Editor highlighting
|
|
170
|
+
|
|
171
|
+
In the markdown editor the fences are coloured with the block's own colour, the
|
|
172
|
+
lines inside get a tinted background and a coloured left bar, and nested blocks
|
|
173
|
+
are indented. An unknown block type is underlined in red so typos are obvious
|
|
174
|
+
before you switch to the viewer.
|
|
175
|
+
|
|
176
|
+
Turn it off in **Tools → Options → HTML Blocks** if you'd rather not have it.
|
|
177
|
+
|
|
178
|
+
## Theming
|
|
179
|
+
|
|
180
|
+
Every block derives all of its colours from one base colour, mixed against the
|
|
181
|
+
current Joplin theme with `color-mix()`. That means the blocks follow your theme
|
|
182
|
+
automatically - no separate dark mode stylesheet, and no hard-coded white
|
|
183
|
+
backgrounds glaring at you in dark mode. On renderers without `color-mix()`
|
|
184
|
+
support the blocks fall back to plain outlines.
|
|
185
|
+
|
|
186
|
+
To restyle a block yourself, target it in your userstyle:
|
|
187
|
+
|
|
188
|
+
```css
|
|
189
|
+
/* every block carries its type in a data attribute */
|
|
190
|
+
.jhtml[data-jhtml-type="card_light_blue"] { --jh-color: #ff00aa; }
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
## Adding your own block types
|
|
194
|
+
|
|
195
|
+
`src/blocks/blocks.json` is the single source of truth. Add an entry:
|
|
196
|
+
|
|
197
|
+
```json
|
|
198
|
+
{
|
|
199
|
+
"id": "card_brown",
|
|
200
|
+
"label": "Brown card",
|
|
201
|
+
"category": "Cards",
|
|
202
|
+
"mode": "card",
|
|
203
|
+
"color": "#92400e",
|
|
204
|
+
"titleHint": "Card title",
|
|
205
|
+
"bodyHint": "Card contents"
|
|
206
|
+
}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
...then `npm run dist`. The new type is immediately available in the parser, the
|
|
210
|
+
viewer stylesheet, the editor highlighter, the menus and the picker dialog -
|
|
211
|
+
there is nowhere else to register it.
|
|
212
|
+
|
|
213
|
+
`mode` picks the renderer: `card`, `callout`, `plain`, `quote`, `details`,
|
|
214
|
+
`grid`, `list`, `steps`, `timeline`, `stats`, `badges` or `keyvalue`. The
|
|
215
|
+
remaining fields (`icon`, `defaultTitle`, `variant`, `listStyle`, `ordered`,
|
|
216
|
+
`columns`, `bare`, `open`, `aliases`) are documented in `src/blocks/types.ts`.
|
|
217
|
+
|
|
218
|
+
## Building
|
|
219
|
+
|
|
220
|
+
```sh
|
|
221
|
+
npm install
|
|
222
|
+
npm run dist
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
That regenerates the stylesheets, compiles everything and writes
|
|
226
|
+
`publish/com.madusanka.htmlBlocks.jpl`.
|
|
227
|
+
|
|
228
|
+
To install the built plugin: **Tools → Options → Plugins → the gear icon →
|
|
229
|
+
Install from file**, and pick the `.jpl`.
|
|
230
|
+
|
|
231
|
+
For development, point **Tools → Options → Plugins → Advanced → Development
|
|
232
|
+
plugins** at this folder (`H:\Projects\joplin_html`) and restart Joplin. Joplin
|
|
233
|
+
then loads `dist/` directly, so a `npm run dist` plus a restart picks up your
|
|
234
|
+
changes.
|
|
235
|
+
|
|
236
|
+
## Layout
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
src/
|
|
240
|
+
index.ts main script: settings, commands, menus, picker dialog
|
|
241
|
+
blocks/
|
|
242
|
+
blocks.json the registry - every block type lives here
|
|
243
|
+
types.ts registry types
|
|
244
|
+
syntax.ts the fence grammar, shared by viewer and editor
|
|
245
|
+
index.ts lookup helpers and the snippet builder
|
|
246
|
+
markdownItPlugin/ markdown-it content script (the viewer)
|
|
247
|
+
codeMirrorPlugin/ CodeMirror 6 content script (the editor)
|
|
248
|
+
dialog/ assets for the block picker
|
|
249
|
+
tools/
|
|
250
|
+
generate-styles.js builds both stylesheets from the registry
|
|
251
|
+
styles/ hand written CSS the generator wraps
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
`src/markdownItPlugin/style.css` and `src/codeMirrorPlugin/style.css` are
|
|
255
|
+
generated - edit `tools/styles/*.css` instead.
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "joplin-plugin-html-blocks",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Write styled HTML sections - cards, callouts, fancy lists, steps, timelines, grids and more - using a simple `!!! type` ... `!!!->` markdown fence.",
|
|
5
|
+
"author": "madusanka",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"styles": "node tools/generate-styles.js",
|
|
8
|
+
"manual": "node tools/generate-manual.js",
|
|
9
|
+
"dist": "npm run styles && webpack --env joplin-plugin-config=buildMain && webpack --env joplin-plugin-config=buildExtraScripts && webpack --env joplin-plugin-config=createArchive",
|
|
10
|
+
"prepare": "npm run dist",
|
|
11
|
+
"updateVersion": "webpack --env joplin-plugin-config=updateVersion",
|
|
12
|
+
"update": "npm install -g generator-joplin && yo joplin --node-package-manager npm --update --force"
|
|
13
|
+
},
|
|
14
|
+
"license": "MIT",
|
|
15
|
+
"homepage": "https://github.com/madusankabibile/joplin-plugin-html-blocks#readme",
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/madusankabibile/joplin-plugin-html-blocks.git"
|
|
19
|
+
},
|
|
20
|
+
"bugs": {
|
|
21
|
+
"url": "https://github.com/madusankabibile/joplin-plugin-html-blocks/issues"
|
|
22
|
+
},
|
|
23
|
+
"keywords": [
|
|
24
|
+
"joplin-plugin"
|
|
25
|
+
],
|
|
26
|
+
"files": [
|
|
27
|
+
"publish"
|
|
28
|
+
],
|
|
29
|
+
"devDependencies": {
|
|
30
|
+
"@codemirror/language": "^6.10.2",
|
|
31
|
+
"@codemirror/state": "^6.4.1",
|
|
32
|
+
"@codemirror/view": "^6.28.0",
|
|
33
|
+
"@types/node": "^18.7.13",
|
|
34
|
+
"chalk": "^4.1.0",
|
|
35
|
+
"copy-webpack-plugin": "^11.0.0",
|
|
36
|
+
"fs-extra": "^10.1.0",
|
|
37
|
+
"glob": "^8.0.3",
|
|
38
|
+
"markdown-it": "^13.0.2",
|
|
39
|
+
"tar": "^6.1.11",
|
|
40
|
+
"ts-loader": "^9.3.1",
|
|
41
|
+
"typescript": "^4.8.2",
|
|
42
|
+
"webpack": "^5.74.0",
|
|
43
|
+
"webpack-cli": "^4.10.0"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"manifest_version": 1,
|
|
3
|
+
"id": "com.madusanka.htmlBlocks",
|
|
4
|
+
"app_min_version": "3.0.0",
|
|
5
|
+
"version": "1.0.0",
|
|
6
|
+
"name": "HTML Blocks",
|
|
7
|
+
"description": "Write styled HTML sections - cards, callouts, fancy lists, steps, timelines, grids and more - using a simple `!!! type` ... `!!!->` markdown fence.",
|
|
8
|
+
"author": "madusanka",
|
|
9
|
+
"homepage_url": "https://github.com/madusankabibile/joplin-plugin-html-blocks",
|
|
10
|
+
"repository_url": "https://github.com/madusankabibile/joplin-plugin-html-blocks",
|
|
11
|
+
"keywords": [
|
|
12
|
+
"card",
|
|
13
|
+
"callout",
|
|
14
|
+
"admonition",
|
|
15
|
+
"html",
|
|
16
|
+
"list"
|
|
17
|
+
],
|
|
18
|
+
"categories": [
|
|
19
|
+
"editor",
|
|
20
|
+
"viewer",
|
|
21
|
+
"appearance"
|
|
22
|
+
],
|
|
23
|
+
"screenshots": [],
|
|
24
|
+
"icons": {},
|
|
25
|
+
"promo_tile": {},
|
|
26
|
+
"_publish_hash": "sha256:4a7d5821dc88eb0042ade43b331412dcf301dba14c18e6036a784d7a289d6035",
|
|
27
|
+
"_publish_commit": "main:75d9bcdcf009c66e40a3b5855ae141dbc8426cd5"
|
|
28
|
+
}
|