nodebb-plugin-katex2 1.0.0

package/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[{*.js, *.css, *.tpl, *.json}]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = false

package/.eslintrc.json

@@ -0,0 +1,8 @@
+{
+  "extends": "airbnb-base",
+  "env": {
+    "node": true,
+    "browser": true,
+    "es6": true
+  }
+}

package/LICENSE

@@ -0,0 +1,26 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Benjamin Abel.
+
+This software also uses portions of the katex auto-render extension from the
+Katex project, which is MIT licensed with the following copyright:
+
+Copyright (c) 2015 Khan Academy
+
+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.md

@@ -0,0 +1,277 @@
+# KaTeX Math Renderer for NodeBB
+
+[English](#english) | [Русский](#russian)
+
+---
+
+<a name="english"></a>
+## English
+
+Modern KaTeX math rendering plugin for NodeBB 4+.
+
+### Features
+
+- ✨ **Lazy loading** - KaTeX loads only when math expressions are detected on the page
+- 📐 **Display mode syntax** - Currently supports `$$...$$` delimiters
+- 🎨 **Server-side ready** - Minimal server logic, client-side rendering
+- 🌐 **CDN delivery** - Uses bundled KaTeX for fast delivery
+- 🚀 **Parser hook integration** - Seamlessly integrates with NodeBB's parser
+- 📱 **Responsive design** - Works on mobile and desktop devices
+- 🌙 **Dark theme support** - Automatically adapts to color schemes
+
+### Installation
+
+#### Via npm (recommended)
+
+```bash
+cd /path/to/nodebb
+npm install nodebb-plugin-katex2
+```
+
+#### Manual installation
+
+1. Clone the plugin into `/nodebb/node_modules/`
+2. Activate the plugin in NodeBB admin panel
+3. Restart NodeBB
+
+```bash
+cd /path/to/nodebb/node_modules
+git clone https://github.com/mysteren/nodebb-plugin-katex.git
+cd ../..
+npm install ./node_modules/nodebb-plugin-katex
+./nodebb restart
+```
+
+### Usage
+
+#### Display mode (separate line)
+
+Currently, only the `$$...$$` syntax is fully supported and tested:
+
+```
+$$
+\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
+$$
+```
+
+Example with integrals:
+
+```
+$$
+\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
+$$
+```
+
+**Note:** While the code includes support for `\[...\]` (display) and `\(...\)` (inline) delimiters, these modes are not currently guaranteed to work correctly. Use `$$...$$` for reliable math rendering.
+
+### Architecture
+
+#### `lib/index.js`
+Main plugin module with hooks:
+- `init()` - Plugin initialization on load
+
+#### `static/js/render.js`
+Client-side script for:
+- Loading KaTeX CSS and JS from bundled assets
+- Lazy initialization (only when expressions are present)
+- Dynamic content support (AJAX navigation)
+- Cleaning HTML tags inside math expressions
+
+#### `static/css/katex.css`
+Additional styles for:
+- Proper inline expression spacing
+- Display expression alignment
+- Dark theme support
+
+### Technical Details
+
+#### Server-side
+- Minimal server-side logic
+- Plugin initialization hook only
+- No server-side parsing overhead
+
+#### Client-side Loading
+- KaTeX CSS loads only when math expressions are detected
+- KaTeX JS loads from bundled assets
+- Auto-render extension for automatic detection
+- Support for dynamic content via AJAX
+- HTML tag cleanup inside math expressions
+
+### Compatibility
+
+- **NodeBB**: 4.0+
+- **Node.js**: 18+
+- **Browsers**: All modern browsers (Chrome, Firefox, Safari, Edge)
+
+### Dependencies
+
+- **katex** (^0.16.27) - KaTeX math typesetting library
+
+### Development Dependencies
+
+- **eslint** (^9.35.0) - Code linting
+
+### Performance
+
+- Fast client-side rendering
+- Lazy resource loading
+- Minimal page load impact
+- Caching support
+- No server-side parsing overhead
+
+### Scripts
+
+```bash
+npm run lint    # Check code style
+npm run fix     # Auto-fix linting issues
+```
+
+### License
+
+MIT
+
+### Author
+
+Timofey (mysteren)
+
+### Acknowledgments
+
+- Original plugin by [Benjamin Abel](https://github.com/benabel/nodebb-plugin-katex)
+- [KaTeX](https://katex.org/) - Fast math typesetting library by Khan Academy
+
+---
+
+<a name="russian"></a>
+## Русский
+
+Современный плагин для поддержки математических выражений KaTeX в NodeBB 4+.
+
+### Возможности
+
+- ✨ **Ленивая загрузка** - KaTeX подгружается только когда на странице есть математические выражения
+- 📐 **Режим отображения** - В настоящее время поддерживается синтаксис `$$...$$`
+- 🎨 **Готов к серверу** - Минимальная серверная логика, рендеринг на клиенте
+- 🌐 **CDN доставка** - Использует встроенный KaTeX для быстрой доставки
+- 🚀 **Интеграция с парсером** - Бесшовно интегрируется с парсером NodeBB
+- 📱 **Адаптивный дизайн** - Работает на мобильных и десктопных устройствах
+- 🌙 **Поддержка тёмной темы** - Автоматически адаптируется к схеме цветов
+
+### Установка
+
+#### Через npm (рекомендуется)
+
+```bash
+cd /путь/к/nodebb
+npm install nodebb-plugin-katex2
+```
+
+#### Ручная установка
+
+1. Клонируйте плагин в `/nodebb/node_modules/`
+2. Активируйте плагин в панели администратора NodeBB
+3. Перезапустите NodeBB
+
+```bash
+cd /путь/к/nodebb/node_modules
+git clone https://github.com/mysteren/nodebb-plugin-katex.git
+cd ../..
+npm install ./node_modules/nodebb-plugin-katex
+./nodebb restart
+```
+
+### Использование
+
+#### Display режим (отдельной строкой)
+
+В настоящее время полностью поддерживается и протестирован только синтаксис `$$...$$`:
+
+```
+$$
+\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
+$$
+```
+
+Пример с интегралами:
+
+```
+$$
+\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
+$$
+```
+
+**Примечание:** Хотя в коде присутствует поддержка разделителей `\[...\]` (отображаемый режим) и `\(...\)` (встроенный режим), корректная работа этих режимов в настоящее время не гарантируется. Используйте `$$...$$` для надёжного отображения формул.
+
+### Архитектура
+
+#### `lib/index.js`
+Основной модуль плагина с хуками:
+- `init()` - Инициализация плагина при загрузке
+
+#### `static/js/render.js`
+Клиентский скрипт для:
+- Загрузки KaTeX CSS и JS из встроенных ресурсов
+- Ленивой инициализации (только при наличии выражений)
+- Поддержки динамического контента (AJAX навигация)
+- Очистки HTML-тегов внутри математических выражений
+
+#### `static/css/katex.css`
+Дополнительные стили для:
+- Правильного отступа inline выражений
+- Выравнивания display выражений
+- Поддержки тёмной темы
+
+### Технические детали
+
+#### Серверная часть
+- Минимальная логика на сервере
+- Только хук инициализации плагина
+- Отсутствие нагрузки на парсинг на сервере
+
+#### Загрузка на клиенте
+- KaTeX CSS загружается только при обнаружении математических выражений
+- KaTeX JS загружается из встроенных ресурсов
+- Расширение auto-render для автоматического обнаружения
+- Поддержка динамического контента через AJAX
+- Очистка HTML-тегов внутри математических выражений
+
+### Совместимость
+
+- **NodeBB**: 4.0+
+- **Node.js**: 18+
+- **Браузеры**: Все современные браузеры (Chrome, Firefox, Safari, Edge)
+
+### Зависимости
+
+- **katex** (^0.16.27) - Библиотека математической вёрстки KaTeX
+
+### Зависимости для разработки
+
+- **eslint** (^9.35.0) - Проверка стиля кода
+
+### Производительность
+
+- Быстрый рендеринг на клиенте
+- Ленивая загрузка ресурсов
+- Минимальное влияние на загрузку страницы
+- Поддержка кэширования
+- Отсутствие нагрузки на парсинг на сервере
+
+### Скрипты
+
+```bash
+npm run lint    # Проверка стиля кода
+npm run fix     # Автоматическое исправление ошибок стиля
+```
+
+### Лицензия
+
+MIT
+
+### Автор
+
+Timofey (mysteren)
+
+### Благодарности
+
+- Оригинальный плагин от [Benjamin Abel](https://github.com/benabel/nodebb-plugin-katex)
+- [KaTeX](https://katex.org/) - Быстрая библиотека математической вёрстки от Khan Academy

package/lib/index.js

@@ -0,0 +1,18 @@
+/**
+ * Серверная часть плагина
+ * Минимальная логика - вся работа на клиенте
+ */
+
+"use strict";
+
+/**
+ * Инициализация плагина при загрузке приложения
+ */
+function init(_params, callback) {
+	console.log("[KaTeX] Plugin initialized");
+	callback();
+}
+
+module.exports = {
+	init,
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "nodebb-plugin-katex2",
+  "version": "1.0.0",
+  "description": "KaTeX math rendering plugin for NodeBB",
+  "main": "lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mysteren/nodebb-plugin-katex"
+  },
+  "keywords": [
+    "nodebb",
+    "plugin",
+    "katex",
+    "latex",
+    "math",
+    "tex"
+  ],
+  "author": "Timofey",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mysteren/nodebb-plugin-katex/issues"
+  },
+  "dependencies": {
+    "katex": "^0.16.27"
+  },
+  "devDependencies": {
+    "eslint": "^9.35.0"
+  },
+  "scripts": {
+    "lint": "eslint lib/ static/js/",
+    "fix": "eslint --fix lib/ static/js/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "nbbpm": {
+    "compatibility": "^4.0.0"
+  }
+}

package/plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "nodebb-plugin-katex2",
+  "name": "KaTeX Math Renderer",
+  "description": "Render LaTeX math expressions with KaTeX in NodeBB posts",
+  "url": "https://github.com/mysteren/nodebb-plugin-katex",
+  "library": "lib/index.js",
+  "hooks": [
+    {
+      "hook": "static:app.load",
+      "method": "init"
+    }
+  ],
+  "scripts": ["static/js/render.js"],
+  "stylesheets": ["static/css/katex.css"],
+  "staticDirs": {
+    "katex": "./node_modules/katex/dist"
+  }
+}

package/static/js/render.js

@@ -0,0 +1,312 @@
+/**
+ * Ленивая загрузка и рендеринг KaTeX
+ * Библиотека загружается только если на странице есть формулы
+ */
+
+(function () {
+	"use strict";
+
+	console.log("Katex render");
+
+	// Флаги загрузки
+	let katexLoaded = false;
+	let katexLoading = false;
+	let loadCallbacks = [];
+
+	/**
+	 * Регулярное выражение для поиска формул
+	 * Ищем разделители: $$, \[, \(
+	 */
+	const MATH_PATTERN = /\$\$|\\\[|\\\(/;
+
+	/**
+	 * Проверка наличия формул на странице
+	 * @returns {boolean}
+	 */
+	function hasMathContent() {
+		// Проверяем в постах
+		const posts = document.querySelectorAll('[component="post/content"]');
+
+		for (let i = 0; i < posts.length; i++) {
+			if (MATH_PATTERN.test(posts[i].textContent)) {
+				return true;
+			}
+		}
+
+		// Проверяем в превью редактора
+		const preview = document.querySelector(".preview-container");
+		if (preview && MATH_PATTERN.test(preview.textContent)) {
+			return true;
+		}
+
+		// Проверяем в заголовках
+		const titles = document.querySelectorAll('[component="topic/title"]');
+		for (let i = 0; i < titles.length; i++) {
+			if (MATH_PATTERN.test(titles[i].textContent)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Динамическая загрузка CSS файла
+	 * @param {string} href - Путь к CSS файлу
+	 * @returns {Promise}
+	 */
+	function loadCSS(href) {
+		return new Promise(function (resolve, reject) {
+			// Проверяем, не загружен ли уже
+			const existing = document.querySelector('link[href="' + href + '"]');
+			if (existing) {
+				resolve();
+				return;
+			}
+
+			const link = document.createElement("link");
+			link.rel = "stylesheet";
+			link.href = href;
+			link.onload = resolve;
+			link.onerror = reject;
+			document.head.appendChild(link);
+		});
+	}
+
+	/**
+	 * Динамическая загрузка JavaScript файла
+	 * @param {string} src - Путь к JS файлу
+	 * @returns {Promise}
+	 */
+	function loadScript(src) {
+		return new Promise(function (resolve, reject) {
+			// Проверяем, не загружен ли уже
+			const existing = document.querySelector('script[src="' + src + '"]');
+			if (existing) {
+				resolve();
+				return;
+			}
+
+			const script = document.createElement("script");
+			script.src = src;
+			script.onload = resolve;
+			script.onerror = reject;
+			document.body.appendChild(script);
+		});
+	}
+
+	/**
+	 * Загрузка библиотеки KaTeX (с async/await и параллельной загрузкой)
+	 * @returns {Promise}
+	 */
+	async function loadKaTeX() {
+		// Если уже загружено
+		if (katexLoaded) {
+			return;
+		}
+
+		// Если загружается сейчас - ждем
+		if (katexLoading) {
+			return new Promise(function (resolve) {
+				loadCallbacks.push(resolve);
+			});
+		}
+
+		console.log("[KaTeX] Loading library...");
+		katexLoading = true;
+
+		try {
+			// Путь к библиотеке в node_modules
+			// const basePath = "/plugins/nodebb-plugin-katex/node_modules/katex/dist/";
+			// Находим правильный путь
+			// Путь к файлам через modules
+			const basePath = "/assets/plugins/nodebb-plugin-katex/katex/";
+
+			// Параллельная загрузка всех файлов
+			await Promise.all([
+				loadCSS(basePath + "katex.min.css"),
+				loadScript(basePath + "katex.min.js"),
+				loadScript(basePath + "contrib/auto-render.min.js"),
+			]);
+
+			katexLoaded = true;
+			katexLoading = false;
+			console.log("[KaTeX] Library loaded successfully");
+
+			// Вызываем все ожидающие колбэки
+			loadCallbacks.forEach(function (callback) {
+				callback();
+			});
+			loadCallbacks = [];
+		} catch (err) {
+			katexLoading = false;
+			console.error("[KaTeX] Failed to load library:", err);
+			throw err;
+		}
+	}
+
+	/**
+	 * Конфигурация KaTeX
+	 */
+	const KATEX_CONFIG = {
+		delimiters: [
+			{ left: "$$", right: "$$", display: true },
+			{ left: "\\[", right: "\\]", display: true },
+			{ left: "\\(", right: "\\)", display: false },
+		],
+		throwOnError: false,
+		errorColor: "#cc0000",
+		strict: false,
+		trust: false,
+	};
+
+	/**
+	 * Очистка HTML-тегов внутри формул
+	 * Markdown может добавить <br>, <p> и другие теги
+	 * @param {HTMLElement} element
+	 */
+	function cleanMathElements(element) {
+		const walker = document.createTreeWalker(
+			element,
+			NodeFilter.SHOW_TEXT,
+			null,
+			false,
+		);
+
+		const nodesToProcess = [];
+		let node;
+
+		// Собираем все текстовые узлы с формулами
+		while ((node = walker.nextNode())) {
+			const text = node.textContent;
+			if (MATH_PATTERN.test(text)) {
+				nodesToProcess.push(node);
+			}
+		}
+
+		// Очищаем найденные узлы от HTML
+		nodesToProcess.forEach(function (textNode) {
+			let parent = textNode.parentNode;
+
+			if (
+				parent &&
+				(parent.innerHTML.includes("<br") || parent.innerHTML.includes("<p"))
+			) {
+				const cleanText = parent.textContent;
+
+				if (MATH_PATTERN.test(cleanText)) {
+					parent.textContent = cleanText;
+				}
+			}
+		});
+	}
+
+	/**
+	 * Рендеринг формул в элементе
+	 * @param {HTMLElement} element
+	 */
+	function renderMath(element) {
+		if (!element) return;
+
+		try {
+			// Сначала очищаем от HTML-тегов
+			cleanMathElements(element);
+
+			// Затем рендерим формулы
+			renderMathInElement(element, KATEX_CONFIG);
+		} catch (err) {
+			console.error("[KaTeX] Render error:", err);
+		}
+	}
+
+	/**
+	 * Рендеринг всех постов (async)
+	 */
+	async function renderAllPosts() {
+		// Проверяем наличие формул
+		if (!hasMathContent()) {
+			console.log("[KaTeX] No math content found, skipping");
+			return;
+		}
+
+		try {
+			// Загружаем KaTeX если нужно
+			await loadKaTeX();
+
+			// Рендерим посты
+			const posts = document.querySelectorAll('[component="post/content"]');
+			posts.forEach(function (post) {
+				renderMath(post);
+			});
+
+			// Рендерим превью
+			const preview = document.querySelector(".preview-container");
+			if (preview) {
+				renderMath(preview);
+			}
+
+			// Рендерим заголовки
+			const titles = document.querySelectorAll('[component="topic/title"]');
+			titles.forEach(function (title) {
+				renderMath(title);
+			});
+
+			console.log("[KaTeX] Rendered " + posts.length + " posts");
+		} catch (err) {
+			console.error("[KaTeX] Failed to render:", err);
+		}
+	}
+
+	/**
+	 * Инициализация
+	 */
+	function init() {
+		// Первый рендеринг
+		renderAllPosts();
+
+		// События NodeBB для динамического контента
+
+		// Когда загружаются новые посты (скролл, пагинация)
+		window.addEventListener("action:posts.loaded", function () {
+			setTimeout(function () {
+				renderAllPosts();
+			}, 50);
+		});
+
+		// Когда открывается тема
+		window.addEventListener("action:topic.loaded", function () {
+			setTimeout(function () {
+				renderAllPosts();
+			}, 50);
+		});
+
+		// Когда происходит навигация
+		window.addEventListener("action:ajaxify.end", function () {
+			setTimeout(function () {
+				renderAllPosts();
+			}, 100);
+		});
+
+		// Когда обновляется превью в редакторе
+		window.addEventListener("action:composer.preview", async function () {
+			if (hasMathContent()) {
+				try {
+					await loadKaTeX();
+					const preview = document.querySelector(".preview-container");
+					if (preview) {
+						renderMath(preview);
+					}
+				} catch (err) {
+					console.error("[KaTeX] Preview render error:", err);
+				}
+			}
+		});
+	}
+
+	// Запуск после загрузки DOM
+	if (document.readyState === "loading") {
+		document.addEventListener("DOMContentLoaded", init);
+	} else {
+		init();
+	}
+})();