ep_markdown 11.0.20 → 12.0.2

package/.github/workflows/backend-tests.yml

@@ -33,7 +33,7 @@ jobs:
       - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
-          version: 10
+          package_json_file: ./etherpad-lite/package.json
           run_install: false
       - name: Get pnpm store directory
         shell: bash

package/.github/workflows/frontend-tests.yml

@@ -23,7 +23,7 @@ jobs:
       - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
-          version: 10
+          package_json_file: ./etherpad-lite/package.json
           run_install: false
       - name: Get pnpm store directory
         shell: bash

package/.github/workflows/npmpublish.yml

@@ -34,7 +34,6 @@ jobs:
       - uses: pnpm/action-setup@v6
         name: Install pnpm
         with:
-          version: 10
           run_install: false
       - name: Get pnpm store directory
         shell: bash

package/AGENTS.md

@@ -0,0 +1,75 @@
+# Agent Guide — ep_markdown
+
+Edit and Export as Markdown in Etherpad.
+
+## Tech stack
+
+* Etherpad plugin framework (hooks declared in `ep.json`)
+* EJS templates rendered server-side via `eejsBlock_*` hooks
+* html10n for i18n (`locales/<lang>.json`, `data-l10n-id` in templates)
+* `ep_plugin_helpers` for shared boilerplate
+
+## Project structure
+
+```
+ep_markdown/
+├── AGENTS.md
+├── CONTRIBUTING.md
+├── ep.json
+├── exportMarkdown.ts
+├── express.ts
+├── index.ts
+├── locales/
+│   ├── ar.json
+│   ├── bn.json
+│   ├── ca.json
+│   ├── cs.json
+│   ├── de.json
+│   ├── diq.json
+│   └── ...
+├── package.json
+├── static/
+│   ├── css/
+│   ├── js/
+│   ├── tests/
+├── templates/
+│   ├── exportcolumn.html
+```
+
+## Helpers used
+
+* `pad-toggle` from `ep_plugin_helpers`
+
+
+## Helpers NOT used
+
+_To be audited in the helpers-adoption sweep (Phase 4)._
+
+
+## Running tests locally
+
+`ep_markdown` runs inside Etherpad's test harness. From an etherpad checkout that has installed this plugin via `pnpm run plugins i --path ../ep_markdown`:
+
+```bash
+# Backend (Mocha) — harness boots its own server
+pnpm --filter ep_etherpad-lite run test
+
+# Playwright — needs `pnpm run dev` in a second terminal
+pnpm --filter ep_etherpad-lite run test-ui
+```
+
+## Standing rules for agent edits
+
+* PRs target `main`. Linear commits, no merge commits.
+* Every bug fix includes a regression test in the same commit.
+* All user-facing strings in `locales/`. No hardcoded English in templates.
+* No hardcoded `aria-label` on icon-only controls — etherpad's html10n auto-populates `aria-label` from the localized string when (a) the element has a `data-l10n-id` and (b) no author-supplied `aria-label` is present. Adding a hardcoded English `aria-label` blocks that and leaves it untranslated. (See `etherpad-lite/src/static/js/vendors/html10n.ts:665-678`.)
+* No nested interactive elements (no `<button>` inside `<a>`).
+* LLM/Agent contributions are explicitly welcomed by maintainers.
+
+## Quick reference: hooks declared in `ep.json`
+
+* Server: `expressCreateServer`, `loadSettings`, `clientVars`, `eejsBlock_exportColumn`, `eejsBlock_mySettings`, `eejsBlock_padSettings`, `import`
+* Client: `aceEditorCSS`, `postAceInit`, `handleClientMessage_CLIENT_MESSAGE`
+
+When adding a hook, register it in both `ep.json` *and* the matching `exports.<hook> = ...` in the JS file.

package/CONTRIBUTING.md

@@ -1,2 +1,74 @@
-# Auto publishing
-To publish a new version of this plugin to NPM just bump the version number in package.json and travis will auto publish for you.
+# Contributing to ep_markdown
+
+Thanks for helping improve `ep_markdown` — a plugin for [Etherpad](https://etherpad.org/). LLM/Agent contributions are explicitly welcome, provided they follow the rules below.
+
+For shared rules that apply to all Etherpad code (linear commits, deprecation policy, feature flags, stability guarantees), please read [ether/etherpad's CONTRIBUTING.md](https://github.com/ether/etherpad/blob/develop/CONTRIBUTING.md). This document only covers what's specific to plugin work.
+
+## Plugin-specific rules
+
+* **Target branch:** PRs go to `main` on this repo. Plugin repos do not use git-flow's `develop` branch.
+* **Linear commits, no merge commits.** Rebase if needed.
+* **Every bug fix must include a regression test in the same commit.**
+* **Internationalization (i18n):** every user-facing string lives in `locales/<lang>.json` and is referenced via `data-l10n-id` in templates or `html10n.get(key)` in code. No hardcoded English in markup.
+* **Accessibility (a11y):** no nested interactive elements (no `<button>` inside `<a>`); every interactive control has an accessible name; keyboard focus order matches visual order. Note that on icon-only controls you should rely on Etherpad's html10n to populate `aria-label` from the `data-l10n-id` translation — adding a hardcoded English `aria-label` blocks that and leaves the control untranslated.
+
+## Local development
+
+`ep_markdown` is a plugin, so you develop it inside a checkout of [ether/etherpad](https://github.com/ether/etherpad).
+
+```bash
+# Once: clone etherpad alongside this repo
+git clone https://github.com/ether/etherpad.git
+cd etherpad
+pnpm install
+
+# Install ep_markdown from your local clone
+pnpm run plugins i --path ../ep_markdown
+
+# Start the dev server (port 9001)
+pnpm --filter ep_etherpad-lite run dev
+```
+
+Edits in `../ep_markdown/` are picked up after a server restart.
+
+## Tests
+
+Tests live inside this repo and are executed by Etherpad's test harness:
+
+* Backend (Mocha): `static/tests/backend/specs/`
+* Playwright (frontend E2E): `static/tests/frontend-new/specs/`
+
+Run them from the etherpad checkout:
+
+```bash
+# Backend (no separate server needed, harness boots one)
+pnpm --filter ep_etherpad-lite run test
+
+# Playwright (requires `pnpm run dev` in another terminal)
+pnpm --filter ep_etherpad-lite run test-ui
+```
+
+Lint locally before pushing:
+
+```bash
+pnpm run lint
+```
+
+## Coding style
+
+* JS/CSS/HTML: 2 spaces, no tabs.
+* `pnpm run lint` must pass (configured via `eslint-config-etherpad`).
+* Avoid breaking changes to public hooks, the line-attribute storage shape, or HTML export output. The backend export spec enforces a stable shape.
+
+## Bug reports
+
+Please include:
+
+* Etherpad version, ep_markdown version, browser + OS
+* Steps to reproduce
+* What you expected, what actually happened
+* Server log excerpt (set `"loglevel": "DEBUG"` in `settings.json` for verbose output)
+
+## AI agents
+
+If you are an LLM/agent contributor, also read [`AGENTS.md`](AGENTS.md) — it documents the file layout, helper usage, and standing rules for autonomous edits.

package/ep.json

@@ -4,13 +4,17 @@
       "name": "markdown",
       "hooks":{
         "expressCreateServer": "ep_markdown/express",
+        "loadSettings": "ep_markdown/index",
+        "clientVars": "ep_markdown/index",
         "eejsBlock_exportColumn": "ep_markdown/index",
         "eejsBlock_mySettings": "ep_markdown/index",
+        "eejsBlock_padSettings": "ep_markdown/index",
         "import": "ep_markdown/index"
       },
       "client_hooks": {
         "aceEditorCSS": "ep_markdown/static/js/markdown",
-        "postAceInit": "ep_markdown/static/js/markdown"
+        "postAceInit": "ep_markdown/static/js/markdown",
+        "handleClientMessage_CLIENT_MESSAGE": "ep_markdown/static/js/markdown:handleClientMessage_CLIENT_MESSAGE"
       }
     }
   ]

package/index.ts

@@ -1,10 +1,25 @@
 'use strict';
 
 const eejs = require('ep_etherpad-lite/node/eejs');
-import settings from 'ep_etherpad-lite/node/utils/Settings';
+const {padToggle} = require('ep_plugin_helpers/pad-toggle-server');
 import {promises} from 'fs';
 const fsp = promises
 
+// Parallel User Settings + Pad Wide Settings checkboxes for "Show Markdown".
+// Helper owns storage, broadcast, enforce, and i18n wiring.
+const markdownToggle = padToggle({
+  pluginName: 'ep_markdown',
+  settingId: 'markdown',
+  l10nId: 'ep_markdown.showMarkdown',
+  defaultLabel: 'Show Markdown',
+  defaultEnabled: false,
+});
+
+exports.loadSettings = markdownToggle.loadSettings;
+exports.clientVars = markdownToggle.clientVars;
+exports.eejsBlock_mySettings = markdownToggle.eejsBlock_mySettings;
+exports.eejsBlock_padSettings = markdownToggle.eejsBlock_padSettings;
+
 exports.eejsBlock_exportColumn = (hookName, context) => {
   context.content += eejs.require('./templates/exportcolumn.html', {}, module);
 };
@@ -13,17 +28,6 @@ exports.eejsBlock_styles = (hookName, context) => {
   context.content += eejs.require('./templates/styles.html', {}, module);
 };
 
-exports.eejsBlock_mySettings = (hookName, context) => {
-  let checkedState = 'unchecked';
-  if (!settings.ep_markdown_default) {
-    checkedState = 'unchecked';
-  } else if (settings.ep_markdown_default === true) {
-    checkedState = 'checked';
-  }
-  context.content +=
-      eejs.require('./templates/markdown_entry.ejs', {checked: checkedState}, module);
-};
-
 exports.import = async (hookName, {destFile, fileEnding, srcFile}) => {
   if (fileEnding !== '.md') return;
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ep_markdown",
   "description": "Edit and Export as Markdown in Etherpad",
-  "version": "11.0.20",
+  "version": "12.0.2",
   "author": {
     "name": "John McLear",
     "email": "john@mclear.co.uk",
@@ -12,6 +12,7 @@
     "url": "https://github.com/ether/ep_markdown.git"
   },
   "dependencies": {
+    "ep_plugin_helpers": "^0.3.2",
     "showdown": "^2.1.0"
   },
   "contributors": [],
@@ -22,7 +23,7 @@
   },
   "devDependencies": {
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.6.2",
     "eslint": "^8.57.1",
     "eslint-config-etherpad": "^4.0.5",
     "typescript": "^6.0.3"

package/static/js/markdown.js

@@ -1,5 +1,26 @@
 'use strict';
 
+// Sub-path import keeps the client bundle clean. Importing the top-level
+// `ep_plugin_helpers` index pulls in every helper's getters; `settings` and
+// `toggle` reach server-only modules (eejs, Settings) which esbuild can't
+// resolve for the browser.
+const {padToggle} = require('ep_plugin_helpers/pad-toggle');
+
+// Same config as the server-side instance — must agree on pluginName,
+// settingId, l10nId, and defaultLabel for the checkbox ids and clientVars
+// lookup to line up.
+const markdownToggle = padToggle({
+  pluginName: 'ep_markdown',
+  settingId: 'markdown',
+  l10nId: 'ep_markdown.showMarkdown',
+  defaultLabel: 'Show Markdown',
+  defaultEnabled: false,
+});
+
+// Re-export so the helper sees pad-wide broadcasts and refreshes our state
+// when another user toggles the pad-wide checkbox.
+exports.handleClientMessage_CLIENT_MESSAGE = markdownToggle.handleClientMessage_CLIENT_MESSAGE;
+
 exports.postAceInit = (hookName, context) => {
   const padRootPath = new RegExp(/.*\/p\/[^/]+/)
       .exec(document.location.pathname) || clientVars.padId;
@@ -20,19 +41,8 @@ exports.postAceInit = (hookName, context) => {
     $('#strikethrough').removeAttr('style');
   };
 
-  /* init */
-  if ($('#options-markdown').is(':checked')) {
-    enable();
-  } else {
-    disable();
-  }
-  /* on click */
-  $('#options-markdown').on('click', () => {
-    if ($('#options-markdown').is(':checked')) {
-      enable();
-    } else {
-      disable();
-    }
+  markdownToggle.init({
+    onChange: (enabled) => { enabled ? enable() : disable(); },
   });
 };
 

package/templates/markdown_entry.ejs

@@ -1,4 +0,0 @@
-<p>
-  <input type="checkbox" id="options-markdown" <%= checked %>></input> 
-  <label for="options-markdown" data-l10n-id="ep_markdown.showMarkdown">Show markdown</label>
-</p>