phlox-md-reader
/phlox-md-reader
Zamienia pliki Markdown w czytelne strony HTML ze spisem treści, wzorami, strukturami chemicznymi i trybem ciemnym.
- Autor
- qinpai ↗
- Repozytorium
- phlox-md-reader ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 10.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 12
- Skrypty
- 4
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 4 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: install-skill.ps1, install-skill.sh, install_indigo.py, mdread.py
Co robi i kiedy
Zamienia pliki Markdown w czytelne strony HTML ze spisem treści, wzorami, strukturami chemicznymi i trybem ciemnym.
Wyzwalacze z opisu
Oryginalny opis (EN)
Phlox-md-reader — 把 Markdown 渲染成"能长时间读下去"的中文阅读页:左侧目录、自动编号插图、离线 KaTeX 公式、化学结构式/反应式(SMILES/反应 SMILES 出图)、提示框与徽章、深色与四套配色、PC/手机自适应;在本地起一个内网端口边改边看(保存自动刷新),也能导出单文件 HTML 发给别人。当用户说"把这份 md 渲染一下 / 我想像网页一样读 / 起个端口我手机也看 / 导出一份单文件 html / 结构式画出来"时使用。
Jak działa
- 一、它解决什么
- 二、什么时候用哪个命令
- 三、三个必须知道的开关
- 四、页面里有什么
- 五、写 md 时要注意的三件事
- 六、出问题时按这个顺序查
- 七、自检(交付前跑一遍,别凭"应该没问题")
- 八、以后要改它,改这几处就够
- 九、文件布局
Podgląd SKILL.md
---
name: phlox-md-reader
description: Phlox-md-reader — 把 Markdown 渲染成"能长时间读下去"的中文阅读页:左侧目录、自动编号插图、离线 KaTeX 公式、化学结构式/反应式(SMILES/反应 SMILES 出图)、提示框与徽章、深色与四套配色、PC/手机自适应;在本地起一个内网端口边改边看(保存自动刷新),也能导出单文件 HTML 发给别人。当用户说"把这份 md 渲染一下 / 我想像网页一样读 / 起个端口我手机也看 / 导出一份单文件 html / 结构式画出来"时使用。
---
# Phlox-md-reader:把 md 变成可长时间阅读的页面
## 一、它解决什么
普通的 md 预览(编辑器内置、GitHub、docsify)只做"把标记翻译成 HTML"。真实的阅读需求是另一回事:
- 一屏 120 字的长行,读三分钟就累 → 需要**版心控制**(每行 52–54 个汉字)与流体字号。
- 长文档需要**目录**,而且要在手机上也能调到 → 宽屏固定左栏,窄屏抽屉 + 遮罩。
- 插图需要**编号与题注**,长截图需要**限高滚动框**,否则一页被一张图撑爆。
- 化学式不能只贴 PNG → 让 SMILES 直接出结构式,题注自动补分子式与分子量。
- 改一个字就要刷新 → **保存即刷新**,而且**保留滚动位置**。
这个 skill 只做这一件事:给一个 md 路径,把它变成可读、可定位、可分享的页面。除 Python 与 `requirements.txt` 里的两个库外不需要额外配置。
## 二、什么时候用哪个命令
| 用户说 | 用 | 结果 |
|---|---|---|
| 渲染、打开看看、边改边看、手机也想看 | `serve` | 起服务,浏览器打开,保存 md 自动刷新(800ms 轮询) |
| 存成 html、不用端口 | `build` | 在同目录写一份 `xxx.html`,本地打开即可(图片相对路径) |
| 发给同学、离线看、关掉会话后还要能看 | `export` | 一份单文件 html,图片/公式/字体/样式全内嵌,双击可读 |
| 打不开、公式不出来、化学图没出 | `doctor` | 自检 KaTeX / Indigo / markdown / 端口 / 防火墙 / 本机地址 |
命令都以 skill 目录为当前目录执行(`python mdread.py …`),脚本自带 UTF-8 输出重配,中文路径不会乱码。
```bash
python mdread.py serve "<md 路径>" # 单份文档
python mdread.py serve "<目录路径>" # 整个目录,左上角 📁 文件夹下拉切换文档
python mdread.py serve note.md --port 7800 --lan on # 指定端口;--lan on 才预开放局域网(默认只本机)
python mdread.py build note.md --out out.html
python mdread.py export note.md
python mdread.py doctor
```
## 三、三个必须知道的开关
**1. 局域网访问默认关闭。** 服务默认只绑 `127.0.0.1`,外部机器连不上。要手机看,点页面工具栏的「🌐 局域网 开」——它是**真的重新绑 socket**(不是软拒绝),开了之后顶部出现常驻地址条:
```
📶 局域网已开 手机连同一个 Wi-Fi,打开:http://192.168.1.42:7800/ [复制地址] [× 关闭这条]
```
地址条在电脑上常驻、可选中、可一键复制;**手机端不显示任何浮层**(toast 和地址条都被 CSS 关掉,避免挡正文)。命令行也可以直接 `--lan on` 预设。
**开关状态只由这一个按钮改。** 保存 md 触发自动刷新、在文档之间切换,都**不会**动它:状态是服务端进程内的 `SRV["state"]["lan"]`,页面每次渲染只读取;只有 `POST /api/lan` 会改,改完立刻 `rebind()` 重绑 socket。所以"开着手机看"时改稿子,手机那端一直连着。
**2. 端口会自动后退。** 默认 7788,`--port` 可指定任意端口;目标端口被占用时会自动往后找(+1 … +19)并在日志里写明「[端口] 7800 被占用,改用 7802」。注意 Windows 允许 `0.0.0.0:端口` 与 `127.0.0.1:端口` 同时绑上,所以判定"占用"用的是真连一次(`port_busy()`),不是靠 bind 报错。
**3. 手机的 CSS 与 JS 是脚本内的常量。** 改完 `mdread.py` 里的样式**必须重启服务**,否则浏览器拿到的还是旧页面(这是本项目最容易误判"改了没生效"的坑)。
## 四、页面里有什么
- **目录**:宽屏左栏(`--side`,默认 250px),窄屏 ☰ 抽屉 + 遮罩,滚动时高亮当前节;h2/h3 自动加锚点,编号从标题里抽出来单独排版。
- **文档切换**:工具栏最左是 `📁 当前文档名 ▾` 的文件夹按钮,点开向下列表(编号 + 文件名,当前那份高亮),选一份即切换;列表最多 70vh 高、内部滚动,**滚动位置记在 sessionStorage**(关掉再打开回到原处),点空白或 Esc 收起。不是横向长条——横向长条在触控板上要么滚不动、要么切完文档弹回最左端。
- **版心**:`html{font-size:clamp(17px,15px+0.22vw,20.5px)}`,正文 `max-width:min(54em,92vw)`;1440 屏约 `每行 54 字 · 962px · 17.8px`,工具栏右侧实时显示这行读数。
- **插图**:`` → 自动编号 + 题注;**高 > 2×宽**的长图自动进限高 76vh 的滚动框,题注后加「原图 760×1800,框内滚动看全图」。
- **化学**:` ```smiles ` 出结构式(题注自动补 `C9 H8 O4 · MW 180.16`),` ```rxn ` 出反应式。
- **公式**:离线 KaTeX(`$…$`、`$$…$$`),断网可用;导出时字体以 base64 内嵌。
- **排版元素**:`> [!NOTE]` 等五种提示框(说明/提示/要点/注意/风险)、`==高亮==`、`【机读】【目视比对】【推断】【待完善】【实测】【结论】` 彩色徽章、宽表格横向滑动。
- **配色**:`🎨` 循环四套色相(深蓝默认 / 青绿 / 琥珀 / 砖红)× `◐` 明暗,记在 localStorage;移动端可用。
- **导出**:`⎙` 打印样式(Ctrl+P 存 PDF,隐藏工具栏与目录)。
## 五、写 md 时要注意的三件事
1. **箭头上的条件只能写英文或符号。** Indigo 内置字库没有 CJK,`! 吡啶, 0 °C` 会渲染成 `□□, 0 °C`。正确写法:
````
```rxn
! pyridine, 0 °C
CC(=O)Cl.O=C([O-])c1ccccc1[O-].[Na+].[Na+]>>CC(=O)Oc1ccccc1C(=O)O
```
````
中文条件写进正文或题注("吡啶作缚酸剂,0 °C 下滴加")。多步反应也不支持(`A>>B>>C` 会报 `invalid character within atom description: '>'`),逐步写多个块。
2. **图片放 `figs/`**,用相对路径引用;题注就是 alt 文本,写清楚"这是什么"而不是"图片1"。缺图会在服务日志里以 `[缺图]` 报出来,不会静默变空框。
3. **标题编号自己写**(`## 1 背景`、`### 1.1 现状`)。渲染器会把编号抽成 `<span class="secnum">` 排成小号强调色,目录里也按编号排序——不写编号也能用,只是没那么利落。
## 六、出问题时按这个顺序查
| 现象 | 查什么 |
|---|---|
| 手机打不开 | 先看电脑上端口是否 `0.0.0.0`(工具栏开了局域网?);再看 Windows 防火墙是否为 python 放了入站规则(端口段 7788–7807);再确认手机与电脑在同一网段(校园网常做接入层隔离,换热点最稳) |
| 公式显示成 `$…$` 原文 | `doctor` 看 KaTeX 组件是否为 24 个文件;确认 md 里 `$` 前后没有多余空格 |
| 化学块显示"化学渲染未启用" | `doctor` 看 Indigo 是否可用;`vendor/` 丢了就重装 `pip install --target vendor epam.indigo` |
| 化学块显示 SMILES 解析失败 | 首行 `!` 条件是否写了中文;多步反应是否写了两个 `>` |
| 图占位显示成 alt 文字(破图) | 这是**路径模式**混用的典型症状:`serve` 必须走 `/files/<绝对路径>`,`build` 必须走相对路径,`export` 必须 base64。三个模式靠 `md_to_html(..., mode="serve|build|export")` 区分,`_img_src()` 与化学图分支都按 `mode` 取值,别在别处拼 `img_prefix` |
| 改了样式没生效 | 重启服务(CSS 是脚本常量) |
| 页面像旧版本 | 服务端已强制 `Cache-Control: no-store`,仍是旧的说明重启过的是另一个进程 |
## 七、自检(交付前跑一遍,别凭"应该没问题")
```bash
python mdread.py build test.md # 看日志里 图/目视比对/缺图 的统计
python mdread.py export test.md # 单文件应 ≈ 原 md 的 20–40 倍(含字体)
```
页面级验收不看"应该没问题",逐项确认:工具栏高度、按钮文字是否被裁(`scrollWidth > clientWidth`)、标题有没有被工具栏压住、长图框的 `clientHeight / scrollHeight`、公式是否渲染成 `.katex`(而不是留在原样的 `$…$`)、化学块是否出图而不是错误提示。三档宽度各看一次:1440、844(横屏)、390(竖屏)。
## 八、以后要改它,改这几处就够
| 想改什么 | 改哪里 | 注意 |
|---|---|---|
| 配色(加第五套色相 / 调色值) | `mdread.py` 的 `CSS` 里 `body[data-accent="…"]` 块 + `JS` 里的 `ACCENTS` 数组 | 亮暗两套都要给,缺一个暗色下会看不清 |
| 边距 / 字号 / 版心 | `--fsx`、`--measure`、`--barh`、`--side`、`--pad` 这些变量;说明见 `references/style.md` | 改完必须重启服务 |
| 徽章词表 | `BADGE_COLORS`(`【机读】` 等 6 个) | 新词不加就退化成灰底 |
| 提示框标签 | `CALLOUTS`(NOTE/TIP/IMPORTANT/WARNING/CAUTION 的中文名) | 键必须大写,对应 `[!NOTE]` |
| 化学出图尺寸/配色 | `render_chem()` 里的 `base_w/base_h`、`render-background-color` | 尺寸是 2 倍渲染再裁白边,别直接改小,会糊 |
| 页面骨架(工具栏按钮、页脚) | `PAGE` 模板字符串 | 占位符 `__TOC__`/`__BODY__`/`__DOCS__` 等不能删 |
| 目录/刷新行为 | `build_toc_html()`、`/api/watch`、`JS` 里的轮询间隔 800ms | 轮询太快会占 CPU,800–1500ms 是甜点 |
| 扫描哪些 md | `Docs._scan()`(默认只扫第一层) | 递归扫描会把草稿目录里的每一份 md 都塞进下拉列表 |
改完的验证顺序:`python mdread.py build 测试.md` 看日志统计 → 浏览器看真页 → 手机宽度与横屏各看一次 → `export` 一份单文件确认没有外链。动大改之前先复制一份 `mdread.py` 当备份。
## 九、文件布局
```
phlox-md-reader/
├── SKILL.md 本文件
├── mdread.py 主程序(serve / build / export / doctor / demo)
├── install_indigo.py 化学依赖的一键安装与自检(--check 验证渲染)
├── assets/katex/ KaTeX 0.16.11 离线包(js + css + 20 个 woff2 字体,MIT)
├── examples/ 可运行样张(01-reading-guide.md、02-chemistry.md + figs/)
├── docs/ README 截图
├── vendor/ epam.indigo(化学渲染,可选;缺了只跳过化学块)
└── references/style.md 设计令牌:配色、字号、断点、间距
```
产物一律放在**源 md 同目录**:`xxx.html`(build)、`xxx_单文件.html`(export)、`.mdread/chem/*.png`(化学图缓存,按内容哈希命名)。
Pliki w paczce (12)
- .gitattributes 1 KB
- .gitignore 1 KB
- LICENSE 1 KB
- README.md 14 KB
- SKILL.md 11 KB
- install-skill.ps1 6 KB
- install-skill.sh 3 KB
- install_indigo.py 3 KB
- mdread.py 60 KB
- requirements.txt 1 KB
- skill-files-lite.txt 1 KB
- skill-files.txt 1 KB
Wersje
W bazie nie ma innych skilli o nazwie phlox-md-reader.
Migawka bazy z 13.11.2026 · wersja paczki bcca32c9fcae (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100md-to-pdf
Konwertuje Markdown na stylowane pliki PDF z diagramami Mermaid, wzorami LaTeX i KaTeX, tabelami i podświetlaniem składni kodu. - 100doc-forge
Pisze dokumenty czytelne do działania: README, specyfikacje, raporty, runbooki i notatki wydania, w Markdown oraz jako HTML lub PDF. - 90webdesign-网页简洁风格美化-202610v1.1
Zamienia Markdown lub istniejącą stronę w jednoplikowy HTML w prostym stylu, z jasnym i ciemnym motywem, spisem treści i wydrukiem. - 90markdown-to-html
Tworzy lub recenzuje konwersję z Markdown do HTML, dbając o format, dostępność, wydajność i wizualną weryfikację wyniku. - 93generate-docs
Generuje dokumentację projektu lub badań jako samodzielny plik HTML, Markdown lub PDF, z nawigacją i motywem jasnym lub ciemnym. - 100markdown-preview-enhanced
Opisuje rozszerzenie VSCode Markdown Preview Enhanced: podgląd na żywo, synchronizację przewijania, wzory KaTeX i MathJax, diagramy mermaid i PlantUML, bloki kodu do wykonania, reveal.js i eksport przez pandoc.