jaamd 0.1.10 → 0.1.11
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 +30 -37
- package/index.ts +21 -2
- package/package.json +3 -1
- package/src/scripts/enhancements.ts +1 -1
- package/src/styles/markdown.css +2 -0
- package/src/styles/variables.css +198 -0
package/README.md
CHANGED
|
@@ -25,8 +25,6 @@ npm install jaamd
|
|
|
25
25
|
npx astro add jaamd
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
---
|
|
29
|
-
|
|
30
28
|
## Setup
|
|
31
29
|
|
|
32
30
|
Add the integration to your Astro config:
|
|
@@ -55,30 +53,29 @@ import { MarkdownContent } from "jaamd/components";
|
|
|
55
53
|
|
|
56
54
|
The integration registers all remark plugins and injects the stylesheet automatically. No other configuration is required.
|
|
57
55
|
|
|
58
|
-
---
|
|
59
|
-
|
|
60
56
|
## View Transitions (FOUC fix)
|
|
61
57
|
|
|
62
|
-
If you are using Astro's `ClientRouter` (View Transitions), you may notice a **flash of unstyled content** when navigating between pages. This happens because the integration injects the stylesheet via `injectScript("page", ...)
|
|
58
|
+
If you are using Astro's `ClientRouter` (View Transitions), you may notice a **flash of unstyled content** when navigating between pages. This happens because the integration injects the stylesheet via `injectScript("page", ...)`, a JS module that runs *after* the new page content has already been swapped into the DOM.
|
|
63
59
|
|
|
64
60
|
To fix it, import the stylesheet **statically** in your layout's frontmatter alongside your other CSS. Astro will bundle it as a `<link>` in `<head>`, which persists across navigations and is applied before any render:
|
|
65
61
|
|
|
66
62
|
```astro
|
|
67
63
|
---
|
|
68
64
|
// In any layout that uses MarkdownContent
|
|
65
|
+
import "jaamd/default.css"; // variable fallbacks
|
|
69
66
|
import "jaamd/styles.css";
|
|
70
67
|
---
|
|
71
68
|
```
|
|
72
69
|
|
|
73
|
-
The duplicate import from `injectScript` is automatically deduplicated by the browser
|
|
74
|
-
|
|
75
|
-
---
|
|
70
|
+
The duplicate import from `injectScript` is automatically deduplicated by the browser. No extra weight, no side effects.
|
|
76
71
|
|
|
77
72
|
## Integration Options
|
|
78
73
|
|
|
79
74
|
```ts
|
|
80
75
|
jaamd({
|
|
81
|
-
selector:
|
|
76
|
+
selector: ".jaamd-content", // CSS selector for the JS enhancements (see below)
|
|
77
|
+
theme: "light", // "light" → github-light | "dark" → github-dark Shiki theme
|
|
78
|
+
noDefault: false, // set true to skip injecting jaamd/default variable fallbacks
|
|
82
79
|
plugins: {
|
|
83
80
|
codeTabs: true, // :::code-tabs directive blocks
|
|
84
81
|
alerts: true, // > [!NOTE] / [!WARNING] blockquote alerts
|
|
@@ -91,18 +88,16 @@ jaamd({
|
|
|
91
88
|
|
|
92
89
|
`selector` only controls which element the **client-side JS enhancements** target at runtime. It does **not** affect the CSS file, which always uses `.jaamd-content`.
|
|
93
90
|
|
|
94
|
-
- **When using `<MarkdownContent>`**
|
|
95
|
-
- **When doing [manual usage](#manual--advanced-usage)
|
|
96
|
-
|
|
97
|
-
---
|
|
91
|
+
- **When using `<MarkdownContent>`** leave `selector` at its default. The component always adds `jaamd-content` to the wrapper, the CSS targets it, and so does the JS.
|
|
92
|
+
- **When doing [manual usage](#manual--advanced-usage)**, if you write a completely custom wrapper (e.g. `<div data-md>`), set `selector` to match it. You will also need to provide your own CSS, since the bundled stylesheet is hardcoded to `.jaamd-content`.
|
|
98
93
|
|
|
99
94
|
## MarkdownContent Component
|
|
100
95
|
|
|
101
96
|
`MarkdownContent` is a polymorphic component. It renders as `<div>` by default and accepts any valid HTML tag via the `as` prop.
|
|
102
97
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
98
|
+
```ts
|
|
99
|
+
import { MarkdownContent } from "jaamd/components";
|
|
100
|
+
```
|
|
106
101
|
|
|
107
102
|
### Props
|
|
108
103
|
|
|
@@ -112,7 +107,7 @@ jaamd({
|
|
|
112
107
|
| `class` | `string` | — | Extra CSS classes appended to the wrapper. |
|
|
113
108
|
| *...rest* | — | — | All standard HTML attributes for the chosen `as` element (e.g. `id`, `data-*`, `aria-*`). |
|
|
114
109
|
|
|
115
|
-
The `jaamd-content` class is always present on the wrapper element
|
|
110
|
+
The `jaamd-content` class is always present on the wrapper element. It is the selector used by the JS enhancements and must not be removed.
|
|
116
111
|
|
|
117
112
|
### Examples
|
|
118
113
|
|
|
@@ -137,40 +132,36 @@ import { MarkdownContent } from "jaamd/components";
|
|
|
137
132
|
</MarkdownContent>
|
|
138
133
|
```
|
|
139
134
|
|
|
140
|
-
---
|
|
141
|
-
|
|
142
135
|
## Theming
|
|
143
136
|
|
|
144
|
-
All styles
|
|
137
|
+
All styles are driven by CSS custom properties. By default, `jaamd/default` is automatically injected before the main stylesheet so every variable has a sensible fallback value.
|
|
138
|
+
|
|
139
|
+
Override any variable on `:root` or `.jaamd-content` in your own stylesheet:
|
|
145
140
|
|
|
146
141
|
```css
|
|
147
142
|
:root {
|
|
148
|
-
/*
|
|
143
|
+
/* core colors */
|
|
149
144
|
--jaamd-color-fg: #334155;
|
|
150
145
|
--jaamd-color-fg-bright: #0f172a;
|
|
151
146
|
--jaamd-color-primary: #6366f1;
|
|
152
147
|
--jaamd-color-primary-light: #818cf8;
|
|
153
148
|
|
|
154
|
-
/* background / border */
|
|
155
|
-
--jaamd-color-bg-secondary: #f8fafc;
|
|
156
|
-
--jaamd-color-border: #e2e8f0;
|
|
157
|
-
|
|
158
|
-
/* code blocks */
|
|
159
|
-
--jaamd-pre-bg: #0f172a;
|
|
160
|
-
--jaamd-pre-fg: #e2e8f0;
|
|
161
|
-
--jaamd-code-bg: #f1f5f9;
|
|
162
|
-
--jaamd-code-fg: #0f172a;
|
|
163
|
-
|
|
164
149
|
/* typography */
|
|
165
|
-
--jaamd-font-sans:
|
|
166
|
-
--jaamd-font-mono:
|
|
167
|
-
--jaamd-font-size:
|
|
150
|
+
--jaamd-font-sans: ui-sans-serif, system-ui, sans-serif;
|
|
151
|
+
--jaamd-font-mono: ui-monospace, monospace;
|
|
152
|
+
--jaamd-font-size: 1rem;
|
|
168
153
|
}
|
|
169
154
|
```
|
|
170
155
|
|
|
171
|
-
|
|
156
|
+
For the complete list of every available variable with its default value, see [`src/styles/variables.css`](src/styles/variables.css).
|
|
172
157
|
|
|
173
|
-
|
|
158
|
+
### Skipping the defaults
|
|
159
|
+
|
|
160
|
+
If you supply your own full variable set and don't want jaamd to inject its defaults, set `noDefault: true`:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
jaamd({ noDefault: true })
|
|
164
|
+
```
|
|
174
165
|
|
|
175
166
|
## Manual / Advanced Usage
|
|
176
167
|
|
|
@@ -189,6 +180,7 @@ export default defineConfig({
|
|
|
189
180
|
|
|
190
181
|
```astro
|
|
191
182
|
---
|
|
183
|
+
import "jaamd/default"; // variable fallbacks — omit if you provide your own
|
|
192
184
|
import "jaamd/styles";
|
|
193
185
|
---
|
|
194
186
|
<div class="jaamd-content">
|
|
@@ -202,8 +194,9 @@ import "jaamd/styles";
|
|
|
202
194
|
</script>
|
|
203
195
|
```
|
|
204
196
|
|
|
205
|
-
You can also import the CSS
|
|
197
|
+
You can also import the CSS files directly from `.css` files or frameworks that prefer bare CSS imports:
|
|
206
198
|
|
|
207
199
|
```css
|
|
200
|
+
@import "jaamd/default.css";
|
|
208
201
|
@import "jaamd/styles.css";
|
|
209
202
|
```
|
package/index.ts
CHANGED
|
@@ -11,6 +11,22 @@ export interface JaamdOptions {
|
|
|
11
11
|
*/
|
|
12
12
|
selector?: string;
|
|
13
13
|
|
|
14
|
+
/**
|
|
15
|
+
* Shiki syntax-highlighting theme family.
|
|
16
|
+
* Selects between `github-light` and `github-dark`.
|
|
17
|
+
* @default "light"
|
|
18
|
+
*/
|
|
19
|
+
theme?: "light" | "dark";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Skip injecting the default CSS variable fallbacks (`jaamd/default`).
|
|
23
|
+
* When `false` (default), the built-in light-theme variable set is always
|
|
24
|
+
* loaded before the main stylesheet so unstyled pages never occur.
|
|
25
|
+
* Set to `true` only when you supply your own full variable set.
|
|
26
|
+
* @default false
|
|
27
|
+
*/
|
|
28
|
+
noDefault?: boolean;
|
|
29
|
+
|
|
14
30
|
/**
|
|
15
31
|
* Granular control over which remark plugins are registered.
|
|
16
32
|
* All enabled by default.
|
|
@@ -32,7 +48,7 @@ export interface JaamdOptions {
|
|
|
32
48
|
* Supports `astro add jaamd`.
|
|
33
49
|
*/
|
|
34
50
|
export default function jaamd(options: JaamdOptions = {}): AstroIntegration {
|
|
35
|
-
const { selector = ".jaamd-content", plugins = {} } = options;
|
|
51
|
+
const { selector = ".jaamd-content", theme = "light", noDefault = false, plugins = {} } = options;
|
|
36
52
|
const { codeTabs = true, alerts = true, directive = true } = plugins;
|
|
37
53
|
|
|
38
54
|
return {
|
|
@@ -53,7 +69,8 @@ export default function jaamd(options: JaamdOptions = {}): AstroIntegration {
|
|
|
53
69
|
|
|
54
70
|
// Apply sensible defaults for shikiConfig only when the user hasn't
|
|
55
71
|
// already set those specific keys.
|
|
56
|
-
const
|
|
72
|
+
const shikiTheme = theme === "dark" ? "github-dark" : "github-light";
|
|
73
|
+
const shikiDefaults: any = { theme: shikiTheme, wrap: true };
|
|
57
74
|
const mergedShikiConfig = { ...shikiDefaults, ...existingShikiConfig };
|
|
58
75
|
|
|
59
76
|
updateConfig({
|
|
@@ -74,6 +91,8 @@ export default function jaamd(options: JaamdOptions = {}): AstroIntegration {
|
|
|
74
91
|
// "page" stage: bundled by Vite, tree-shaken, no duplicate injection
|
|
75
92
|
injectScript(
|
|
76
93
|
"page",
|
|
94
|
+
(!noDefault ? `import "jaamd/default";
|
|
95
|
+
` : "") +
|
|
77
96
|
`import "jaamd/styles";
|
|
78
97
|
` +
|
|
79
98
|
`import { initMarkdownEnhancements } from "jaamd/client";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "jaamd",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.11",
|
|
4
4
|
"description": "Just Another Astro Markdown",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -21,6 +21,8 @@
|
|
|
21
21
|
".": "./index.ts",
|
|
22
22
|
"./components": "./src/components/MarkdownContent.astro",
|
|
23
23
|
"./client": "./src/scripts/enhancements.ts",
|
|
24
|
+
"./default": "./src/styles/variables.css",
|
|
25
|
+
"./default.css": "./src/styles/variables.css",
|
|
24
26
|
"./styles": "./src/styles/markdown.css",
|
|
25
27
|
"./styles.css": "./src/styles/markdown.css"
|
|
26
28
|
},
|
|
@@ -47,7 +47,7 @@ export function initMarkdownEnhancements(
|
|
|
47
47
|
// ─── Heading anchor links ─────────────────────────────────────────────────────
|
|
48
48
|
|
|
49
49
|
function addHeadingLinks(selector: string): void {
|
|
50
|
-
qsa<HTMLElement>(document, `${selector} h2, ${selector} h3`).forEach(
|
|
50
|
+
qsa<HTMLElement>(document, `${selector} h1, ${selector} h2, ${selector} h3`).forEach(
|
|
51
51
|
(header) => {
|
|
52
52
|
if (!header.id) header.id = slugify(header.textContent ?? "");
|
|
53
53
|
if (qs(header, ".jaamd-heading-link")) return;
|
package/src/styles/markdown.css
CHANGED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
/* ============================================================
|
|
2
|
+
* JAAMD — Default Variables & Full CSS Variable Reference
|
|
3
|
+
* ============================================================
|
|
4
|
+
*
|
|
5
|
+
* This file serves a dual purpose:
|
|
6
|
+
*
|
|
7
|
+
* 1. FALLBACK THEME — it is automatically imported by the
|
|
8
|
+
* integration (before markdown.css) so all --jaamd-* vars
|
|
9
|
+
* have sensible values even if you never set any yourself.
|
|
10
|
+
* You can opt out with `noDefault: true` in jaamd({…}).
|
|
11
|
+
*
|
|
12
|
+
* 2. DOCUMENTATION — every --jaamd-* property is listed here
|
|
13
|
+
* with a comment describing its role. Copy any variable
|
|
14
|
+
* you want to override into your own :root block.
|
|
15
|
+
*
|
|
16
|
+
* Importable as: import "jaamd/default";
|
|
17
|
+
* @import "jaamd/default.css";
|
|
18
|
+
* ============================================================ */
|
|
19
|
+
|
|
20
|
+
:root {
|
|
21
|
+
/* ── Typography ─────────────────────────────────────────── */
|
|
22
|
+
|
|
23
|
+
/** Sans-serif font stack for body text */
|
|
24
|
+
--jaamd-font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
|
|
25
|
+
|
|
26
|
+
/** Serif font stack (used when --jaamd-font-sans is overridden to a serif) */
|
|
27
|
+
--jaamd-font-serif: Georgia, "Times New Roman", Times, serif;
|
|
28
|
+
|
|
29
|
+
/** Monospace font stack for code */
|
|
30
|
+
--jaamd-font-mono: "SF Mono", Consolas, "Liberation Mono", Menlo, Courier, monospace;
|
|
31
|
+
|
|
32
|
+
/** Base font size for all scaled elements */
|
|
33
|
+
--jaamd-font-size: 1.125rem;
|
|
34
|
+
|
|
35
|
+
/** Line height for body text, lists and code blocks */
|
|
36
|
+
--jaamd-line-height: 1.6;
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
/* ── Core colors ────────────────────────────────────────── */
|
|
40
|
+
|
|
41
|
+
/** Default body/paragraph text color */
|
|
42
|
+
--jaamd-color-fg: #3a3a3a;
|
|
43
|
+
|
|
44
|
+
/** Headings, strong, table headers, summary — brighter than fg */
|
|
45
|
+
--jaamd-color-fg-bright: #1a1a1a;
|
|
46
|
+
|
|
47
|
+
/** Accent / primary color (links, active tab label, summary arrow) */
|
|
48
|
+
--jaamd-color-primary: #2d2d2d;
|
|
49
|
+
|
|
50
|
+
/** Slightly lighter accent (link :hover, blockquote text) */
|
|
51
|
+
--jaamd-color-primary-light: #4a4a4a;
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
/* ── Headings ───────────────────────────────────────────── */
|
|
55
|
+
|
|
56
|
+
/** Border-bottom color of h2 */
|
|
57
|
+
--jaamd-heading-border-color: rgb(from var(--jaamd-color-primary) r g b / 0.4);
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
/* ── Inline code (<code> outside a <pre>) ───────────────── */
|
|
61
|
+
|
|
62
|
+
/** Background of inline code */
|
|
63
|
+
--jaamd-code-bg: #e8e4df;
|
|
64
|
+
|
|
65
|
+
/** Border of inline code */
|
|
66
|
+
--jaamd-code-border: #d0cbc6;
|
|
67
|
+
|
|
68
|
+
/** Text color of inline code */
|
|
69
|
+
--jaamd-code-fg: #1a1a1a;
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
/* ── Fenced code blocks (<pre>) ─────────────────────────── */
|
|
73
|
+
|
|
74
|
+
/** Background of code blocks (overrides Shiki when not using a Shiki theme) */
|
|
75
|
+
--jaamd-pre-bg: #eeeae5;
|
|
76
|
+
|
|
77
|
+
/** Border of code blocks */
|
|
78
|
+
--jaamd-pre-border: #c8c4bf;
|
|
79
|
+
|
|
80
|
+
/** Fallback text color inside code blocks */
|
|
81
|
+
--jaamd-pre-fg: #2d2d2d;
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
/* ── Copy-to-clipboard button ───────────────────────────── */
|
|
85
|
+
|
|
86
|
+
/** Copy button background (idle) */
|
|
87
|
+
--jaamd-copy-btn-bg: #d8d4cf;
|
|
88
|
+
|
|
89
|
+
/** Copy button border (idle) */
|
|
90
|
+
--jaamd-copy-btn-border: #a8a39e;
|
|
91
|
+
|
|
92
|
+
/** Copy button icon color (idle) */
|
|
93
|
+
--jaamd-copy-btn-fg: #2d2d2d;
|
|
94
|
+
|
|
95
|
+
/** Copy button background on hover */
|
|
96
|
+
--jaamd-copy-btn-hover-bg: #c8c4bf;
|
|
97
|
+
|
|
98
|
+
/** Copy button border on hover */
|
|
99
|
+
--jaamd-copy-btn-hover-border: #9a958f;
|
|
100
|
+
|
|
101
|
+
/** Copy button icon color on hover */
|
|
102
|
+
--jaamd-copy-btn-hover-fg: #1a1a1a;
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
/* ── Blockquote ─────────────────────────────────────────── */
|
|
106
|
+
|
|
107
|
+
/** Blockquote background fill */
|
|
108
|
+
--jaamd-blockquote-bg: #eeeae5;
|
|
109
|
+
|
|
110
|
+
/** Blockquote left-border accent color */
|
|
111
|
+
--jaamd-blockquote-border: #5a5a5a;
|
|
112
|
+
|
|
113
|
+
/** Blockquote paragraph text color */
|
|
114
|
+
--jaamd-blockquote-fg: #4a4a4a;
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
/* ── Emphasis ───────────────────────────────────────────── */
|
|
118
|
+
|
|
119
|
+
/** Color of <em> / italic text */
|
|
120
|
+
--jaamd-em-fg: #4a4a4a;
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
/* ── Horizontal rule (<hr>) ─────────────────────────────── */
|
|
124
|
+
|
|
125
|
+
/** Color of the hr border line */
|
|
126
|
+
--jaamd-hr-color: rgb(from var(--jaamd-color-primary) r g b / 0.4);
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
/* ── Tables ─────────────────────────────────────────────── */
|
|
130
|
+
|
|
131
|
+
/** Table cell border color (also used for box-shadow outline) */
|
|
132
|
+
--jaamd-table-border: #b8b3ae;
|
|
133
|
+
|
|
134
|
+
/** <th> header row background */
|
|
135
|
+
--jaamd-table-header-bg: #eeeae5;
|
|
136
|
+
|
|
137
|
+
/** <tr>:hover background */
|
|
138
|
+
--jaamd-table-hover-bg: #e0dcd7;
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
/* ── Code tabs (.code-tabs) ───────────────────────────────── */
|
|
142
|
+
|
|
143
|
+
/** Outer border and tab-strip bottom border */
|
|
144
|
+
--jaamd-tabs-border: #c8c4bf;
|
|
145
|
+
|
|
146
|
+
/** Tab strip header background */
|
|
147
|
+
--jaamd-tabs-header-bg: #e0dcd7;
|
|
148
|
+
|
|
149
|
+
/** Inactive tab button :hover background */
|
|
150
|
+
--jaamd-tabs-btn-hover-bg: #d0cbc6;
|
|
151
|
+
|
|
152
|
+
/** Active tab button background (matches the panel below it) */
|
|
153
|
+
--jaamd-tabs-btn-active-bg: #eeeae5;
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
/* ── Details / Summary ───────────────────────────────────── */
|
|
157
|
+
|
|
158
|
+
/** <details> block background */
|
|
159
|
+
--jaamd-details-bg: #eeeae5;
|
|
160
|
+
|
|
161
|
+
/** <details> block border */
|
|
162
|
+
--jaamd-details-border: #c8c4bf;
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
/* ── Spoiler ─────────────────────────────────────────────── */
|
|
166
|
+
|
|
167
|
+
/** Hidden spoiler text+background color (same value hides text) */
|
|
168
|
+
--jaamd-spoiler-hidden-color: #1a1a1a;
|
|
169
|
+
|
|
170
|
+
/** Revealed spoiler background */
|
|
171
|
+
--jaamd-spoiler-revealed-bg: #eeeae5;
|
|
172
|
+
|
|
173
|
+
/** Revealed spoiler text color */
|
|
174
|
+
--jaamd-spoiler-revealed-fg: #3a3a3a;
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
/* ── Alert blocks (.markdown-alert) ────────────────────── */
|
|
178
|
+
|
|
179
|
+
/* Note */
|
|
180
|
+
--jaamd-alert-note-color: #0969da;
|
|
181
|
+
--jaamd-alert-note-bg: #dff0fd;
|
|
182
|
+
|
|
183
|
+
/* Tip */
|
|
184
|
+
--jaamd-alert-tip-color: #1a7f37;
|
|
185
|
+
--jaamd-alert-tip-bg: #dafbe1;
|
|
186
|
+
|
|
187
|
+
/* Important */
|
|
188
|
+
--jaamd-alert-important-color: #8250df;
|
|
189
|
+
--jaamd-alert-important-bg: #fbefff;
|
|
190
|
+
|
|
191
|
+
/* Warning */
|
|
192
|
+
--jaamd-alert-warning-color: #9a6700;
|
|
193
|
+
--jaamd-alert-warning-bg: #fff8c5;
|
|
194
|
+
|
|
195
|
+
/* Caution */
|
|
196
|
+
--jaamd-alert-caution-color: #cf222e;
|
|
197
|
+
--jaamd-alert-caution-bg: #ffebe9;
|
|
198
|
+
}
|