Przejdź do treści
Biblioteka skilli
Dokumenty i biuro · Konwersja i formaty

phlox-md-reader

/phlox-md-reader

Zamienia pliki Markdown w czytelne strony HTML ze spisem treści, wzorami, strukturami chemicznymi i trybem ciemnym.

Licencja
MIT
Ostatnia zmiana repozytorium
10.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
12
Skrypty
4
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 10.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 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

能长时间读下去把这份 md 渲染一下 / 我想像网页一样读 / 起个端口我手机也看 / 导出一份单文件 html / 结构式画出来
Oryginalny opis (EN)

Phlox-md-reader — 把 Markdown 渲染成"能长时间读下去"的中文阅读页:左侧目录、自动编号插图、离线 KaTeX 公式、化学结构式/反应式(SMILES/反应 SMILES 出图)、提示框与徽章、深色与四套配色、PC/手机自适应;在本地起一个内网端口边改边看(保存自动刷新),也能导出单文件 HTML 发给别人。当用户说"把这份 md 渲染一下 / 我想像网页一样读 / 起个端口我手机也看 / 导出一份单文件 html / 结构式画出来"时使用。

Jak działa

  1. 一、它解决什么
  2. 二、什么时候用哪个命令
  3. 三、三个必须知道的开关
  4. 四、页面里有什么
  5. 五、写 md 时要注意的三件事
  6. 六、出问题时按这个顺序查
  7. 七、自检(交付前跑一遍,别凭"应该没问题")
  8. 八、以后要改它,改这几处就够
  9. 九、文件布局
Sekcje z nagłówków SKILL.md, w oryginale · 131 linii, 643 słów
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`,工具栏右侧实时显示这行读数。
- **插图**:`![题注](figs/x.png)` → 自动编号 + 题注;**高 > 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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.