Одностраничный просмотрщик Markdown (.md) и JSON (.json) файлов по URL или из локального файла. Поддерживает подсветку синтаксиса, переключение светлой/тёмной темы, компактный режим, а также рендеринг диаграмм Mermaid, PlantUML, Pikchr и внешних SVG (draw.io).
Открывается по адресу вида:
https://<viewer-domain>/?url=https://<any-host>/path/file.md
- Markdown (через
marked) с таблицами GFM, якорями заголовков и кнопкой «копировать» у блоков кода. - LaTeX-формулы (через KaTeX): блочные
$$...$$и\[...\], инлайн$...$и\(...\). - JSON-viewer с фильтром, сворачиванием узлов и подсчётом ключей.
- Диаграммы из fenced code blocks (у Mermaid — кнопка копирования диаграммы как PNG при наведении):
- Mermaid —
```mermaid/```mmd - PlantUML —
```plantuml/```puml - Pikchr —
```pikchr
- Mermaid —
- Изображения (включая draw.io SVG) — через обычный
, с автоматическим резолвингом относительных URL относительно источника Markdown. - Декодирование URL GitHub/GitLab
blob/→raw/для прямой загрузки. - Подсветка синтаксиса кода через highlight.js с переключением тем.
- Light/Dark тема с сохранением через
prefers-color-scheme, плюс ручной переключатель. - Компактный режим для широкого контента (таблиц, длинных листингов).
- Шэринг файлов: загрузка
.md/.jsonчерез страницу/upload(SSO-авторизация) в S3-хранилище с получением публичной ссылки для просмотра (см. соответствующий раздел).
Все библиотеки самохостятся в каталоге vendor/ — приложение не зависит от внешних CDN и продолжает работать, даже если CDN заблокирован.
| Файл | Назначение | Версия | Источник |
|---|---|---|---|
marked.min.js |
Парсинг Markdown | 12 | https://cdn.jsdelivr.net/npm/marked@12/marked.min.js |
highlight.min.js |
Подсветка кода | 11.9.0 | https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/ |
hljs-dark.css |
Тема highlight.js (тёмная) | 11.9.0 | …/styles/github-dark.min.css |
hljs-light.css |
Тема highlight.js (светлая) | 11.9.0 | …/styles/github.min.css |
mermaid.min.js |
Рендеринг Mermaid-диаграмм | 11 | https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js |
pikchr.js |
Рендеринг Pikchr-диаграмм (WASM) | 0.1.4 | https://cdn.jsdelivr.net/npm/pikchr-js/pikchr.js |
purify.min.js |
Санитайзер HTML (DOMPurify) | 3.2.4 | https://cdn.jsdelivr.net/npm/dompurify@3.2.4/dist/purify.min.js |
katex/ |
Рендеринг LaTeX-формул (js+css+woff2) | 0.16.11 | https://registry.npmjs.org/katex/-/katex-0.16.11.tgz |
Обновление любой библиотеки:
curl -sL "<URL из таблицы выше>" -o vendor/<file>
# задеплоить vendor/ на сервер (см. ниже)Ленивая загрузка рендереров диаграмм: mermaid.min.js (3.2 МБ) и pikchr.js не подключаются тегом <script> при старте страницы — они вставляются динамически при первом блоке mermaid/pikchr в документе (см. initMermaid() / loadPikchrOnce() в index.html). Документы без диаграмм экономят ~3.3 МБ загрузки и парсинга; страница с диаграммами грузит их по требованию.
Шрифты Satoshi и JetBrains Mono подключаются через <link> с fontshare.com и fonts.googleapis.com. Если эти домены недоступны, браузер автоматически откатывается на системные шрифты — функциональность не страдает.
Браузер по умолчанию блокирует fetch() к доменам, которые не отдают Access-Control-Allow-Origin. Чтобы просмотрщик работал с любыми http(s)-источниками (объектные storages, внутренние HTTP-серверы, GitHub/GitLab raw, произвольные сайты без настроенного CORS), на бэкенде работает SSRF-safe прокси-эндпоинт GET /api/fetch?url=<encoded>.
Фронтенд всегда идёт через /api/fetch (single source of truth) — больше никаких внешних публичных проксей (cors.eu.org, allorigins.win), никакой захардкоженной привязки к конкретному storage-домену.
- Frontend (
index.html): все запросы к внешним URL идут через единственный proxy'/api/fetch?url=' + encodeURIComponent(url)в массивеPROXIES. Изображения в Markdown () грузятся браузером напрямую — для них нуженimg-srcв CSP. - Backend (
backend/server.js, тот же процесс, что и DOCX-экспорт): endpointGET /api/fetchрезолвит upstream, проверяет IP, делает запрос и отдаёт тело сAccess-Control-Allow-Origin: *. - Nginx:
location /api/проксирует на127.0.0.1:3001(см.nginx.ssl.conf_export_docx).
Прокси не является open-relay — он отвергает запросы к внутренним/приватным адресам, чтобы предотвратить SSRF-атаки на хостинг-инфраструктуру:
| Проверка | Реализация |
|---|---|
| Протокол | Только http: / https:. file:, ftp:, data: и пр. → 400. |
| Приватные/зарезервированные IP | net.BlockList покрывает RFC1918 (10/8, 172.16/12, 192.168/16), loopback 127/8, link-local 169.254/16 (включая cloud-metadata 169.254.169.254), CGNAT 100.64/10, TEST-NET, multicast, reserved, IPv6 ::1, fc00::/7, fe80::/10. |
| DNS-резолв | Все A/AAAA записи проверяются до соединения. Если хоть одна запись приватная → 400. |
| IP literal в URL | Проверяется напрямую через net.isIP (Node обходит lookup для numeric hostname). |
| Redirects | До 3 редиректов, каждый пере-валидируется (URL + DNS + IP). |
| Размер ответа | До 10 MB (FETCH_MAX_BYTES), сверх — 413. |
| Таймаут | 10 с на upstream-запрос (FETCH_TIMEOUT_MS). |
| Rate limit | 30 запросов/мин на клиентский IP (X-Real-IP или socket), in-memory bucket. |
Код сосредоточен в функциях resolveAndCheck, validateFetchUrl, fetchUpstream в backend/server.js.
- Прокси обязателен. Без backend-сервиса просмотрщик не сможет загружать никакие внешние файлы (только локальные через «Открыть»).
- Backend один на все
/api/*-эндпоинты:/api/fetch,/api/export-docx,/api/auth/*,/api/upload,/api/s/:id. Systemd-юнитmdviewer-export.service. - Менять лимиты — константы
FETCH_MAX_BYTES,FETCH_TIMEOUT_MS,FETCH_MAX_REDIRECTS,RATE_LIMIT_WINDOW_MS,RATE_LIMIT_MAXв начале файла. - Расширить blocklist — объект
ipBlockList(например, добавить публичные DNS-серверы провайдера, если они в приватном диапазоне). - Разрешить конкретный приватный хост (например, внутренний storage за VPN): добавьте bypass-проверку в
resolveAndCheckпо whitelist имён хостов. - CSP:
connect-srcдолжен включать'self'(запросы на/api/fetchsame-origin). Для изображений:img-srcдолжен явно перечислять разрешённые источники картинок. - После правок бэкенда:
systemctl restart mdviewer-export, для nginx —nginx -t && systemctl reload nginx.
См. раздел «Экспорт в DOCX» ниже — это тот же Node.js-сервис на 127.0.0.1:3001. Обновление кода:
sudo cp backend/server.js /home/<user>/web/<domain>/private/backend/server.js
sudo systemctl restart mdviewer-export
curl -sI "https://<viewer-domain>/api/fetch?url=https://example.com/" | head -1 # HTTP/2 200Загрузка .md/.json в S3-совместимое хранилище (MinIO или любое S3) с авторизацией через OIDC SSO и получение публичной ссылки вида https://<viewer-domain>/?url=….
upload.html(отдаётся как/upload): гейт через/api/auth/me, drag'n'drop, результат — ссылки для просмотра и прямая на файл + кнопки копирования/удаления; локальная история загрузок в localStorage. Переход со страницы viewer'а — иконка загрузки в шапке.- Backend (
backend/server.js):GET /api/auth/login|callback|me|logout— OIDC Authorization Code + PKCE (S256), confidential-клиент (Zitadel или другой IdP). ID-token валидируется по JWKS (RS256, builtincrypto), сессия — in-memory Map + cookiemdv_session(HttpOnly, Secure, SameSite=Lax, 12 ч).POST /api/upload— только с сессией; валидация (ext.md/.markdown/.json, ≤5 МБ, strict UTF-8, JSON парсится), ID = 22 симв. base64url (неперечислим), PUT в бакет через самописный SigV4 (zero-dep), audit JSONL.GET /api/s/:id— публичный стрим объекта:Access-Control-Allow-Origin: *,X-Robots-Tag: noindex, кеш 5 мин. HEAD поддерживается.DELETE /api/s/:id— сессия + совпадениеx-amz-meta-sub(владелец может удалить свою загрузку).
- S3: приватный бакет, lifecycle expire 30 дней (
mc ilm rule add <alias>/<bucket> --expire-days 30). Бакет не должен быть публично читаемым — чтение идёт только через backend, креды не покидают сервер. - Внешний вид ссылки:
https://<viewer-domain>/?url=<encoded https://<viewer-domain>/api/s/<id>>. Viewer фетчит own-origin/api/s/напрямую (без двойного хопа через/api/fetch).
Задаются в env-файле (рекомендуется /etc/mdviewer-upload.env, chmod 600), подключённом в systemd-юните через EnvironmentFile=-:
| Переменная | Назначение | По умолчанию |
|---|---|---|
ZITADEL_DOMAIN |
домен OIDC-провайдера | — (обязательно) |
ZITADEL_CLIENT_ID / ZITADEL_CLIENT_SECRET |
confidential-клиент | — (обязательно) |
ZITADEL_REDIRECT_URI |
https://<viewer-domain>/api/auth/callback |
— (обязательно) |
S3_ENDPOINT / S3_BUCKET |
доступ к S3 | http://127.0.0.1:9000 / mdviewer |
S3_ACCESS_KEY / S3_SECRET_KEY / S3_REGION |
креды и регион S3 | — / — / ru-msk |
SESSION_TTL_MS |
время жизни сессии | 12 ч |
UPLOAD_MAX_BYTES |
макс. размер файла | 5 МБ |
UPLOAD_USER_DAILY / UPLOAD_RATE_MAX |
квоты: файлов/день на юзера, загрузок/час на IP | 200 / 30 |
SERVE_RATE_MAX |
GET /api/s/ в минуту на IP |
120 |
AUDIT_LOG_PATH |
JSONL audit-лог | /var/log/mdviewer/uploads.log |
- OIDC-клиент: создать Web-приложение (Authorization Code, confidential), redirect URI
https://<viewer-domain>/api/auth/callback. ClientID/Secret → в env-файл. Один клиент на домен: при нескольких доменах вход с любого из них редиректит на домен из redirect URI. - S3-бакет: создать приватный бакет, включить lifecycle
--expire-days 30, креды → в env-файл. - Nginx: проксирование
/api/+location = /upload { rewrite ^ /upload.html last; }(обе location — вnginx.ssl.conf_export_docx). - Каталог для audit-лога:
mkdir -p /var/log/mdviewer && chown <service-user> /var/log/mdviewer.
| Мера | Значение |
|---|---|
| Авторизация | OIDC SSO; email/sub пишется в audit |
| TTL файла | 30 дней (lifecycle S3, авто) |
| Размер / типы | ≤5 МБ; только текст .md/.markdown/.json |
| Rate-limit | 30 загрузок/час на IP; 200/день на юзера; 120 GET/мин на IP |
| Индексация | X-Robots-Tag: noindex + robots.txt: Disallow: /api/s/ |
| Audit | JSONL: ts, ip, sub, email, id, name, size, sha256 |
| XSS | вывод marked.parse() санитайзится DOMPurify |
- Смена ClientSecret: правка env-файла →
systemctl restart mdviewer-export. Существующие файлы и ссылки не затрагиваются. - Рестарт сервиса сбрасывает in-memory сессии → пользователи перелогиниваются одним кликом SSO.
- IdP недоступен → загрузка невозможна, просмотр
/api/s/работает.
В шапку добавлена кнопка «.docx» (рядом с переключателем темы). Она активна только когда:
- загружен Markdown-файл,
- настроен и запущен backend-эндпоинт
/api/export-docx.
- Frontend (
index.html): перед отправкой исходный Markdown проходит front-end препроцессинг:- относительные URL изображений резолвятся в абсолютные,
- блоки
\`\`\`mermaidи\`\`\`pikchrзаменяются на встроенные SVG в Base64, - блоки
\`\`\`plantumlзаменяются на.
- Backend (
backend/server.js): лёгкий Node.js HTTP-сервер (zero-зависимостей). Принимает JSON{ markdown, filename }, запускаетpandoc -f gfm -t docx --wrap=none, обрабатываетdata:URI изображений (пишет во временные файлы) и отдаёт готовый.docx. - Nginx (
nginx.ssl.conf_export_docx): location/api/проксируется на127.0.0.1:3001.
pandoc>= 3.x (или 2.9.2+). Рекомендуется свежий.debс GitHub Releases.node>= 18.- systemd (для запуска backend-как-сервиса).
# 1. Установить pandoc
wget https://github.com/jgm/pandoc/releases/download/3.10/pandoc-3.10-1-amd64.deb
sudo dpkg -i pandoc-3.10-1-amd64.deb
# 2. Скопировать backend
sudo mkdir -p /home/<user>/web/<domain>/private/backend
sudo cp backend/server.js /home/<user>/web/<domain>/private/backend/
# 3. Systemd
sudo cp mdviewer-export.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now mdviewer-export
# 4. Nginx: подключить location из nginx.ssl.conf_export_docx в server-блок домена
sudo nginx -t && sudo systemctl reload nginxПриложение — статика: index.html, upload.html, robots.txt, каталог vendor/. Раздаётся nginx напрямую из document root каждого домена:
# пример: несколько доменов на одном сервере
for d in <viewer-domain-1> <viewer-domain-2>; do
cp index.html upload.html robots.txt /path/to/web/$d/public_html/
rsync -a --delete vendor/ /path/to/web/$d/public_html/vendor/
chown -R <web-user>:<web-user> /path/to/web/$d/public_html
done
# проверка
curl -sI "https://<viewer-domain>/" | head -1 # HTTP/2 200
curl -sI "https://<viewer-domain>/upload" | head -1 # HTTP/2 200Backend (/api/) проксируется nginx'ом на 127.0.0.1:3001 — см. «Деплой backend» выше и nginx.ssl.conf_export_docx.
Если используете HestiaCP — не редактируйте автогенерируемые конфиги доменов (
/home/<user>/conf/web/..., перезаписываются при rebuild домена): создавайте самостоятельные server-блоки в/etc/nginx/conf.d/*.conf.
Приложение — это статический index.html + каталог vendor/:
# 1. Создать document root и скопировать статику
sudo mkdir -p /var/www/file-viewer
sudo cp index.html vendor -t /var/www/file-viewer/
sudo chown -R <web-server-user>:<web-server-user> /var/www/file-viewer
# 2. Настроить server block (см. раздел для вашей системы выше)
# 3. Проверить и перезагрузить веб-сервер
sudo <web-server> -t && sudo systemctl reload <web-server>
# 4. Проверить, что index.html и vendor/ отдаются
curl -sI "https://<viewer-domain>/index.html" | head -1 # HTTP/2 200
curl -sI "https://<viewer-domain>/vendor/marked.min.js" | head -1 # HTTP/2 200Особенности для LLM-агента:
- Не кладите
index.htmlв подкаталог — приложение использует относительные пути кvendor/. - Проверьте, что MIME-тип для
.jsотдаётся какapplication/javascript(илиtext/javascript), иначе браузер заблокирует исполнение. - Если страница грузится пустой — откройте DevTools → Console. Самые частые причины: 404 на
vendor/*.js(неправильный document root) или CSP-заголовок, блокирующийscript-src.
.
├── index.html # одностраничное приложение (HTML + CSS + JS в одном файле)
├── upload.html # страница загрузки /upload (SSO + drag'n'drop + ссылки)
├── robots.txt # запрет индексации /api/s/
├── backend/
│ ├── server.js # Node.js: /api/fetch + /api/export-docx + /api/auth/* + /api/upload + /api/s/:id
│ └── package.json
├── vendor/ # самохостящиеся библиотеки (см. таблицу выше)
│ ├── marked.min.js
│ ├── purify.min.js
│ ├── highlight.min.js
│ ├── hljs-dark.css
│ ├── hljs-light.css
│ ├── mermaid.min.js
│ ├── pikchr.js
│ └── katex/ # KaTeX: katex.min.js, katex.min.css, fonts/*.woff2
├── mdviewer-export.service # systemd-юнит для backend (EnvironmentFile=/etc/mdviewer-upload.env)
└── README.md