Skip to content
BDubaPublic

About

Simple single-file Markdown & JSON viewer — loads any .md or .json file via ?url= query param, with syntax highlighting, dark mode, and compact table layout

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

File Viewer

Одностраничный просмотрщик 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
  • Изображения (включая 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. Если эти домены недоступны, браузер автоматически откатывается на системные шрифты — функциональность не страдает.

Загрузка внешних файлов: /api/fetch

Зачем нужен

Браузер по умолчанию блокирует 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-экспорт): endpoint GET /api/fetch резолвит upstream, проверяет IP, делает запрос и отдаёт тело с Access-Control-Allow-Origin: *.
  • Nginx: location /api/ проксирует на 127.0.0.1:3001 (см. nginx.ssl.conf_export_docx).

Модель безопасности (SSRF-защита)

Прокси не является 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.

Что важно для LLM-агента

  • Прокси обязателен. Без 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/fetch same-origin). Для изображений: img-src должен явно перечислять разрешённые источники картинок.
  • После правок бэкенда: systemctl restart mdviewer-export, для nginx — nginx -t && systemctl reload nginx.

Деплой backend

См. раздел «Экспорт в 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

Шэринг файлов: /upload → S3 → ?url=

Загрузка .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, builtin crypto), сессия — in-memory Map + cookie mdv_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

Первоначальная настройка

  1. OIDC-клиент: создать Web-приложение (Authorization Code, confidential), redirect URI https://<viewer-domain>/api/auth/callback. ClientID/Secret → в env-файл. Один клиент на домен: при нескольких доменах вход с любого из них редиректит на домен из redirect URI.
  2. S3-бакет: создать приватный бакет, включить lifecycle --expire-days 30, креды → в env-файл.
  3. Nginx: проксирование /api/ + location = /upload { rewrite ^ /upload.html last; } (обе location — в nginx.ssl.conf_export_docx).
  4. Каталог для 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

Ops-заметки

  • Смена ClientSecret: правка env-файла → systemctl restart mdviewer-export. Существующие файлы и ссылки не затрагиваются.
  • Рестарт сервиса сбрасывает in-memory сессии → пользователи перелогиниваются одним кликом SSO.
  • IdP недоступен → загрузка невозможна, просмотр /api/s/ работает.

Экспорт в DOCX

В шапку добавлена кнопка «.docx» (рядом с переключателем темы). Она активна только когда:

  • загружен Markdown-файл,
  • настроен и запущен backend-эндпоинт /api/export-docx.

Архитектура экспорта

  • Frontend (index.html): перед отправкой исходный Markdown проходит front-end препроцессинг:
    • относительные URL изображений резолвятся в абсолютные,
    • блоки \`\`\`mermaid и \`\`\`pikchr заменяются на встроенные SVG в Base64,
    • блоки \`\`\`plantuml заменяются на ![PlantUML](plantuml_url).
  • 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-как-сервиса).

Быстрый деплой backend (пример для HestiaCP)

# 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

Деплой

Деплой статики (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 200

Backend (/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

About

Simple single-file Markdown & JSON viewer — loads any .md or .json file via ?url= query param, with syntax highlighting, dark mode, and compact table layout

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages