npm - @ampless/plugin-highlight - Versions diffs - 0.1.0-beta.0 - Mend

@ampless/plugin-highlight 0.1.0-beta.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.

Files changed (6) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 ampless contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md ADDED Viewed

@@ -0,0 +1,87 @@
+> English: [README.md](./README.md)
+# @ampless/plugin-highlight
+[ampless](https://github.com/heavymoons/ampless) 向けシンタックスハイライトプラグイン。CDN から遅延ロードした [highlight.js](https://highlightjs.org/) で、公開サイト上のコードブロックをハイライトします。
+> **プレリリース / ベータ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+`publicHead` capability 経由でインラインスクリプトを 1 本だけ `<head>` に注入します。公開ページ側でスクリプトが `<pre><code class="language-xxx">`（`language-mermaid` は除外）を走査し、**1 つでも存在する場合のみ** テーマ用スタイルシートを注入したうえで jsDelivr から highlight.js を動的 import して各ブロックをハイライトします。コードブロックの無いページではライブラリもスタイルシートも一切ダウンロードしません。
+AWS のデータ権限は不要です。ディスクリプタの生成は公開 Next.js プロセスのリクエスト時に行われ、ハイライトはブラウザ上で行われます。`trust_level` は `untrusted`。
+## インストール
+```bash
+pnpm add @ampless/plugin-highlight@beta
+```
+## 設定
+`cms.config.ts` に記述します:
+```ts
+import { defineConfig } from 'ampless'
+import highlightPlugin from '@ampless/plugin-highlight'
+export default defineConfig({
+  // ...
+  plugins: [highlightPlugin()],
+})
+```
+## オプション
+```ts
+highlightPlugin({
+  version: '11.11.1', // 既定値（固定 x.y.z）
+  theme: 'github', // highlight.js のスタイルシート名
+})
+```
+| オプション | デフォルト  | 備考                                                                                                                                                                                                                                                                                                                                                    |
+| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`  | `'11.11.1'` | jsDelivr から読み込む highlight.js のバージョン。`x` / `x.y` / `x.y.z` に一致する必要あり。不正値は `console.warn` してデフォルトにフォールバック。                                                                                                                                                                                                     |
+| `theme`    | `'github'`  | highlight.js のスタイルシート名（例: `github` / `github-dark` / `atom-one-dark` / `monokai`）。`/^[a-z0-9][a-z0-9-]{0,40}$/` に一致する必要あり。それ以外は `github` にフォールバック。対応する `styles/<theme>.min.css` を CDN から読み込みます。[highlight.js のスタイル一覧](https://github.com/highlightjs/highlight.js/tree/main/src/styles)参照。 |
+## コードブロックの検出方法
+描画後の投稿 HTML から `<pre><code class="language-xxx">` を探し、`language-mermaid` は除外します。ampless のツールバーにあるコードブロック単位の **言語エディタ**が `language-*` クラスを付与し、どの本文フォーマットでも同じ形に着地します:
+| `post.format` | クラスの付き方                                                            |
+| ------------- | ------------------------------------------------------------------------- |
+| `tiptap`      | コードブロックノードの `language` 属性 → 描画時に `class="language-ts"`。 |
+| `markdown`    | フェンスドブロック ` ```ts ` → `class="language-ts"`。                    |
+| `html`        | 記述された `<pre><code class="language-ts">` はそのまま保持。             |
+ハイライトしたい言語をフェンスドブロックに指定します:
+````markdown
+```ts
+const greet = (name: string) => `Hello, ${name}!`
+```
+````
+`language-*` クラスの無いブロック（言語指定なしの素の ` ``` ` フェンス）はそのまま残します。
+## @ampless/plugin-mermaid との共存
+両プラグインは順序非依存で同時に動作するよう設計されています。本プラグインのセレクタは `code.language-mermaid` を明示的に除外（`:not(.language-mermaid)`）するため、Mermaid の図ソースがシンタックスハイライトされることはありません。`@ampless/plugin-mermaid` はそれらの `<pre>` を描画済み SVG に置換します。ハイライト済みブロックは `:not(.hljs)` で守られるため、二重ハイライトされません。
+## クライアント側の堅牢性
+- **冪等な再スキャン** — highlight.js は処理済みブロックに `hljs` クラスを付与し、セレクタは `:not(.hljs)` で守るため、再ハイライトしません。
+- **SPA / App Router 遷移** — head スクリプトは一度だけ実行されますが、`document.body` に張ったデバウンス付き `MutationObserver` が、クライアント遷移で後から挿入された投稿コンテンツを再スキャンします。
+- **失敗時の復旧** — 動的 import が失敗した場合はキャッシュした import Promise を破棄するため次回スキャンで再試行されます。失敗は握り潰さず `console.warn` で報告します。
+- **テーマ用スタイルシート** — ハイライト対象のブロックがある場合のみ、id `ampless-hljs-theme` で一度だけ注入されます。
+## セキュリティ / CDN に関する注意
+- **既定バージョンは固定。** 供給網の攻撃面を最小化するため `version` の既定値は厳密な `x.y.z` です。floating な major/minor タグ（例: `'11'`）も指定できますが、その供給網リスクは利用者の責任です。
+- **動的 `import()` には SRI（Subresource Integrity）が効きません。** ライブラリは実行時に jsDelivr から取得され、integrity 固定はできません。ライブラリ / スタイルシートの自前ホスティングは将来のオプションとして検討します。
+- highlight.js はコードブロックのテキスト内容を読み取って再マークアップするだけで、ハイライト対象のソースを実行することはありません。
+## v1 で対応しないこと
+- **ビルド時 / サーバサイドハイライトは非対応** — ハイライトはブラウザで行われるため、JS 無効クライアントや初回描画時には未スタイル（ただし可読）のコードが見えます。
+- **ラベル無しブロックの言語自動判定は行いません** — `language-*` クラスのあるブロックのみハイライトします。

package/README.md ADDED Viewed

@@ -0,0 +1,87 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+# @ampless/plugin-highlight
+Syntax-highlighting plugin for [ampless](https://github.com/heavymoons/ampless). Highlights fenced code blocks on the public site using [highlight.js](https://highlightjs.org/) loaded lazily from a CDN.
+> **Pre-release / beta.** Breaking changes possible in any minor version until v1.0.
+The plugin injects a single inline script into `<head>` via the `publicHead` capability. On the public page the script scans for `<pre><code class="language-xxx">` blocks (excluding `language-mermaid`) and, **only if at least one exists**, injects the theme stylesheet and dynamically imports highlight.js from jsDelivr to highlight each block. Pages without a code block never download the library or the stylesheet.
+No AWS data permissions are required — the descriptor is produced at request time in the public Next.js process and the highlighting happens in the browser. The plugin's `trust_level` is `untrusted`.
+## Install
+```bash
+pnpm add @ampless/plugin-highlight@beta
+```
+## Configure
+In `cms.config.ts`:
+```ts
+import { defineConfig } from 'ampless'
+import highlightPlugin from '@ampless/plugin-highlight'
+export default defineConfig({
+  // ...
+  plugins: [highlightPlugin()],
+})
+```
+## Options
+```ts
+highlightPlugin({
+  version: '11.11.1', // pinned default
+  theme: 'github', // any highlight.js stylesheet name
+})
+```
+| Option    | Default     | Notes                                                                                                                                                                                                                                                                                                                                               |
+| --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version` | `'11.11.1'` | highlight.js version loaded from jsDelivr. Must match `x` / `x.y` / `x.y.z`. Invalid values fall back to the default with a `console.warn`.                                                                                                                                                                                                         |
+| `theme`   | `'github'`  | A highlight.js stylesheet name (e.g. `github`, `github-dark`, `atom-one-dark`, `monokai`). Must match `/^[a-z0-9][a-z0-9-]{0,40}$/`; anything else falls back to `github`. The corresponding `styles/<theme>.min.css` is loaded from the CDN. See the [highlight.js styles list](https://github.com/highlightjs/highlight.js/tree/main/src/styles). |
+## How code blocks are detected
+The plugin looks for `<pre><code class="language-xxx">` in the rendered post HTML and skips `language-mermaid`. The ampless toolbar's per-code-block **language editor** writes the `language-*` class, and all body formats land on the same shape:
+| `post.format` | How the class appears                                                                 |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `tiptap`      | The code-block node carries a `language` attribute → `class="language-ts"` on render. |
+| `markdown`    | A fenced block ` ```ts ` → `class="language-ts"`.                                     |
+| `html`        | Authored `<pre><code class="language-ts">` is preserved literally.                    |
+Tag a fenced block with the language to highlight:
+````markdown
+```ts
+const greet = (name: string) => `Hello, ${name}!`
+```
+````
+A block with no `language-*` class (a plain ` ``` ` fence with no language) is left untouched.
+## Coexistence with @ampless/plugin-mermaid
+The two plugins are designed to run together in any order. This plugin's selector explicitly excludes `code.language-mermaid` (`:not(.language-mermaid)`), so a Mermaid diagram source is never syntax-highlighted; `@ampless/plugin-mermaid` replaces those `<pre>` blocks with rendered SVG. Already-highlighted blocks are guarded with `:not(.hljs)` so nothing is highlighted twice.
+## Client-side robustness
+- **Idempotent re-scan** — highlight.js adds the `hljs` class to processed blocks, and the selector guards on `:not(.hljs)`, so the scan never re-highlights.
+- **SPA / App Router navigation** — the head script runs once, but a debounced `MutationObserver` on `document.body` re-scans when client navigation injects new post content.
+- **Failure recovery** — if the dynamic import fails, the cached import promise is cleared so a later scan retries; failures are reported via `console.warn` rather than swallowed.
+- **Theme stylesheet** — injected once with id `ampless-hljs-theme`, only when a highlightable block is present.
+## Security / CDN notes
+- **Pinned default version.** The default `version` is an exact `x.y.z` to minimize supply-chain surface. You may pass a floating major/minor tag (e.g. `'11'`), but the supply-chain risk of a floating tag is your responsibility.
+- **Dynamic `import()` cannot use Subresource Integrity (SRI).** The library is fetched from jsDelivr at runtime; there is no integrity pin. Self-hosting the library / stylesheet is a possible future option.
+- highlight.js only reads and re-marks the text content of code blocks; it does not execute the highlighted source.
+## What it does not do (v1)
+- **No build-time / server-side highlighting** — highlighting happens in the browser, so a no-JS client or the first paint shows unstyled (but readable) code.
+- **No automatic language detection for unlabelled blocks** — only blocks with a `language-*` class are highlighted.

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { AmplessPlugin } from 'ampless';
+interface HighlightPluginOptions {
+    /**
+     * highlight.js version to load from jsDelivr. Must be an exact or
+     * partial `x` / `x.y` / `x.y.z` version string. Invalid values fall
+     * back to the pinned default with a `console.warn`. Floating
+     * major/minor tags are accepted but their supply-chain risk is the
+     * site author's responsibility.
+     */
+    version?: string;
+    /**
+     * highlight.js stylesheet theme name (e.g. `'github'`,
+     * `'github-dark'`, `'atom-one-dark'`). Must match
+     * `/^[a-z0-9][a-z0-9-]{0,40}$/`; invalid values fall back to
+     * `'github'` with a `console.warn`. The corresponding
+     * `styles/<theme>.min.css` is loaded from the CDN.
+     */
+    theme?: string;
+}
+/**
+ * Factory for the syntax-highlighting plugin. Usage in `cms.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from 'ampless'
+ * import highlightPlugin from '@ampless/plugin-highlight'
+ *
+ * export default defineConfig({
+ *   plugins: [highlightPlugin()],
+ * })
+ * ```
+ */
+declare function highlightPlugin(opts?: HighlightPluginOptions): AmplessPlugin;
+export { type HighlightPluginOptions, highlightPlugin as default };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,95 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+var DEFAULT_VERSION = "11.11.1";
+var DEFAULT_THEME = "github";
+var VERSION_RE = /^[0-9]+(\.[0-9]+){0,2}$/;
+var THEME_RE = /^[a-z0-9][a-z0-9-]{0,40}$/;
+function pickVersion(value) {
+  if (value === void 0) return DEFAULT_VERSION;
+  if (VERSION_RE.test(value)) return value;
+  console.warn(
+    `[ampless-highlight] ignoring invalid version "${value}"; falling back to "${DEFAULT_VERSION}".`
+  );
+  return DEFAULT_VERSION;
+}
+function pickTheme(value) {
+  if (value === void 0) return DEFAULT_THEME;
+  if (THEME_RE.test(value)) return value;
+  console.warn(
+    `[ampless-highlight] ignoring invalid theme "${value}"; falling back to "${DEFAULT_THEME}".`
+  );
+  return DEFAULT_THEME;
+}
+function buildBody(version, theme) {
+  const CSS = JSON.stringify(
+    `https://cdn.jsdelivr.net/npm/highlight.js@${version}/styles/${theme}.min.css`
+  );
+  const SRC = JSON.stringify(`https://cdn.jsdelivr.net/npm/highlight.js@${version}/+esm`);
+  return `(function () {
+  var modPromise;
+  function scan() {
+    var blocks = Array.prototype.slice.call(
+      document.querySelectorAll('pre > code[class*="language-"]:not(.language-mermaid):not(.hljs)')
+    );
+    if (!blocks.length) return;
+    // Inject the theme stylesheet once, only when something needs it.
+    if (!document.getElementById('ampless-hljs-theme')) {
+      var link = document.createElement('link');
+      link.id = 'ampless-hljs-theme';
+      link.rel = 'stylesheet';
+      link.href = ${CSS};
+      document.head.appendChild(link);
+    }
+    if (!modPromise) modPromise = import(${SRC});
+    modPromise.then(function (mod) {
+      var hljs = mod.default;
+      blocks.forEach(function (code) {
+        // Guard again at apply time \u2014 a concurrent scan may have already
+        // highlighted this block.
+        if (!code.classList.contains('hljs')) hljs.highlightElement(code);
+      });
+    }).catch(function (e) {
+      // Drop the cached import so a later scan re-attempts the load.
+      modPromise = undefined;
+      console.warn('[ampless-highlight] load failed', e);
+    });
+  }
+  function init() {
+    scan();
+    // SPA / App Router client navigation: the head script runs once but new
+    // post content arrives later. Re-scan (debounced) when the body mutates.
+    if (typeof MutationObserver === 'function') {
+      var t;
+      var obs = new MutationObserver(function () {
+        clearTimeout(t);
+        t = setTimeout(scan, 100);
+      });
+      obs.observe(document.body, { childList: true, subtree: true });
+    }
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();`;
+}
+function highlightPlugin(opts = {}) {
+  const version = pickVersion(opts.version);
+  const theme = pickTheme(opts.theme);
+  const body = buildBody(version, theme);
+  return definePlugin({
+    name: "highlight",
+    apiVersion: 1,
+    packageName: "@ampless/plugin-highlight",
+    trust_level: "untrusted",
+    capabilities: ["publicHead"],
+    displayName: { en: "Syntax highlighting", ja: "\u30B7\u30F3\u30BF\u30C3\u30AF\u30B9\u30CF\u30A4\u30E9\u30A4\u30C8" },
+    publicHead() {
+      return [{ type: "inlineScript", id: "ampless-highlight", body }];
+    }
+  });
+}
+export {
+  highlightPlugin as default
+};

package/package.json ADDED Viewed

@@ -0,0 +1,58 @@
+{
+  "name": "@ampless/plugin-highlight",
+  "version": "0.1.0-beta.0",
+  "description": "Syntax highlighting plugin for ampless — highlights `code.language-*` blocks on the public site via a lazily CDN-loaded highlight.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-highlight"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-highlight#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "1.0.0-beta.52"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "ampless-plugin",
+    "highlight",
+    "highlight.js",
+    "syntax-highlighting",
+    "cms"
+  ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "highlight",
+    "trustLevel": "untrusted",
+    "capabilities": [
+      "publicHead"
+    ],
+    "displayName": {
+      "en": "Syntax highlighting",
+      "ja": "シンタックスハイライト"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}