简单文档

面向 Emlog 博客的 Markdown 文档站插件：将 Markdown 文档动态解析渲染为 HTML 文档页，不生成任何静态 HTML 文件。

插件简介

简单文档（lcbk_doc）让你可以直接在 Emlog 后台用 Markdown 写文档，前台自动渲染成带目录、可搜索、可挂附件的文档页面。核心设计目标是"简单"：

• 文档以 Markdown 原文入库，访问时动态解析渲染，全程不生成静态 HTML，升级、改版零负担；
• 基于 H2 / H3 标题自动生成两级目录（TOC），标题文字即页内锚点；
• 支持栏目分类浏览、站内搜索、代码块复制与轻量着色；
• 支持 zip / pdf / office 等附件上传、下载与浏览器内预览，并记录下载日志；
• 内置防 XSS 的 HTML 白名单净化、附件目录脚本防护、下载防盗链与断点续传。

安装启用后，前台会自动获得一个独立于博客正文的文档栏目入口，适合存放产品手册、开发文档、使用说明、帮助中心等。

功能特性

文档与渲染

• Markdown 渲染引擎：内置自包含的 Parsedown + ParsedownExtra（类名已重命名避免与主题或其他插件冲突），支持表格、任务列表、围栏代码块、脚注、删除线、自动链接等扩展语法。
• 纯动态渲染：文档每次请求时实时解析，不生成、不缓存静态 HTML 文件，正文与目录以 JSON 文件缓存于插件 cache 目录，缓存 key 由文档 ID 与正文内容哈希决定，内容一改自然失效。
• 自动两级目录：按 Markdown 的 H2 / H3 标题生成"章节 + 子项"目录；正文侧栏跟随滚动高亮（IntersectionObserver 实现，无依赖），移动端收进可开关的"目录"按钮。
• 中文标题锚点：锚点优先取标题文字生成的 slug 且保留中文，例如 ## 安装 会生成 id="安装"，正文可用 [点击](#安装) 直接页内跳转；纯符号 / 表情标题或重名标题自动回退 / 追加 -1 -2 序号，保证 id 唯一。
• 自动摘要：从正文首行提取纯文本摘要（自动跳过标题、列表、引用、代码块、图片等），用于首页卡片与 <meta description>。
• 代码块增强：每个围栏代码块自动添加语言标识条与"复制"按钮，并按语言族做零依赖的轻量着色（支持 PHP / JS / Python / Bash / SQL / C 系 / HTML / CSS 等），不支持的语言也有通用关键字高亮。
• 防 XSS 净化：渲染结果先过 HTML 白名单净化——有 DOM 扩展时走 DOMDocument 逐标签白名单（仅放行安全属性与 http/https/mailto/data:image/* 协议），无 DOM 扩展时回退正则过滤，删 script、on* 事件与 javascript: 伪协议。

站点与浏览

• 栏目分类：后台可新增 / 重命名 / 排序栏目，前台首页顶部出现"全部 / 各栏目"导航并可点击筛选；删除栏目不删文档，文档自动归入"未分类"。
• 站内搜索：首页搜索框按文档标题与正文检索，结果、分页与栏目筛选互相保留。
• 首页卡片栅格：每页 9 篇，卡片展示标题、自动摘要、更新时间、附件数与阅读量。
• 阅读统计：文档详情自动累计阅读量。
• 上一篇 / 下一篇：详情页底部按排序规则自动衔接，可关联阅读。

附件与下载日志

• 附件上传：为文档挂多个附件，后端做扩展名白名单 + 危险类型黑名单双重校验，存放到独立的 files 目录并以随机名落盘。
• 浏览器内预览：PDF、常见图片、音视频、纯文本 / Markdown 等类型提供"预览"入口（inline 输出，不计数）；SVG 因可承载脚本一律按下载处理。
• 下载与统计：强制附件方式输出并记录下载日志（附件名、文档、IP、UA、时间），单个附件累计下载数；后台"下载日志"标签可按文档筛选、一键清空。
• 断点续传：附件输出完整支持 HTTP Range（206 Partial Content），大文件下载与视频拖动进度友好；HEAD 请求只回响应头不计数。
• 防盗链开关：开启后仅放行来自本站页面、同源（含子域）或（可选）空 Referer 直连的请求，拦截跨站盗链。

后台与主题

• 明暗主题：前台默认跟随系统 prefers-color-scheme，右上角可手动切换，选择保存在 localStorage；CSS 全部收敛于 css/jc-doc.css，样式为浅色 / 深色双套变量，未引入任何第三方前端库。
• SEO 增强：页面输出 <title>、description、canonical、Open Graph、Twitter Card，文档详情页附带 Article 类型的 JSON-LD 结构化数据。
• 绿色卸载：插件删除回调会清理全部数据表与配置（附件物理文件随插件目录删除），不留残留数据。

安装与启用

1. 在 Emlog 后台 插件 → 插件管理 → 上传插件，上传后插件目录为 content/plugins/lcbk_doc/（或手动将本目录解压放置到该路径）。
2. 启用插件。启用回调会自动创建 4 张数据表并写入默认配置，无需手动建表。
3. 进入插件设置页进行站点信息配置，并开始新增文档。

从旧版本覆盖升级时，即使未重新启用插件也不会缺列：回调里带增量迁移（补 log.doc_id 索引、doc.cat_id 列），前台 / 后台每次请求开头还会做一次幂等的运行时结构补齐（lcbk_doc_ensure_schema），无权限 ALTER 时静默降级不报错。

前台访问地址

插件前台是一个独立页面，地址根据 Emlog 是否开启伪静态自动适配：

• 开启伪静态（推荐，地址更友好）： https://yourdomain/plugin/lcbk_doc
• 未开启伪静态： https://yourdomain/?plugin=lcbk_doc

若前台 404，请检查 Emlog 后台 系统 → 设置 → SEO 中的伪静态配置。

路由规则

后台使用指南

后台入口：https://yourdomain/admin/plugin.php?plugin=lcbk_doc（仅管理员可见），共 4 个标签页：

1. 基础设置（basic）

2. 文档管理（docs）

• 左侧为文档列表（标题、栏目、更新时间、阅读 / 附件数、可见状态），支持排序（数字越小越靠前）与前台可见开关。
• 新增 / 编辑文档需填写：标题（必填）、排序、所属栏目、前台可见、简介，以及核心的 Markdown 内容。
• Markdown 编辑框提供导入 .md 文件与在线草稿预览两种辅助能力：导入即把本地 Markdown 文件内容读入编辑框；预览在编辑页实时渲染查看效果（正式效果以保存后的前台为准）。
• 删除文档会级联删除其全部附件（含物理文件）、下载日志与渲染缓存。

3. 栏目管理（cats）

新增 / 重命名 / 排序 / 删除栏目。建好栏目后回到"文档管理"为文档选择栏目，前台首页即出现栏目导航。

4. 下载日志（logs）

展示最近下载记录（时间、附件名、所属文档、IP、UA），可按文档筛选，支持一键清空。

Markdown 写作约定

• 目录：正文中直接使用 ## 与 ###，渲染后自动进入两级目录；### 归属其上方最近的 ##。没有目录开关时侧栏自动隐藏。
• 页内跳转：标题文字即锚点（保留中文），正文可写 [点击跳转](#标题文字)；也可用传统 #anchor 方式引用其它标题生成的中文锚点。
• 代码块：用 加语言名（如 `php 、 ``python）即可获得语言标识、复制按钮与轻量着色。
• HTML 混排：支持在 Markdown 中嵌入原生 HTML，但仅白名单标签与属性会被保留，脚本类内容一律被剥离（有 DOM 扩展时；无 DOM 扩展时按纯文本转义，避免渲染异常）。
• 图片：支持外链图片，也允许 data:image/png;base64 内嵌小图。

附件支持范围

• 上传上限：插件硬上限 200MB，同时受 PHP upload_max_filesize、post_max_size 约束（取三者最小值）；超大附件请先在后台调整服务器 PHP 配置。
• 预览类型（浏览器内联）：pdf jpg jpeg png gif webp mp3 mp4 webm ogg txt md，同时提供"预览"与"下载"两个入口。
• 仅下载类型：zip rar 7z tar gz doc docx xls xlsx ppt pptx csv apk ipa 等。
• 存储安全：文件写入 content/plugins/lcbk_doc/files/，目录内 .htaccess 禁止列目录，并对 php / phtml / phar / cgi / py / sh 等脚本扩展名拒绝执行（Apache 2.2 / 2.4 均覆盖），上传落盘文件名随机化，杜绝可执行文件落地。

目录结构

lcbk_doc/
├── lcbk_doc.php              插件主文件：版本与常量、加载各库
├── lcbk_doc_callback.php     启用/更新/删除回调：建表、迁移、种子配置、卸载清理
├── lcbk_doc_setting.php      后台设置页：4 个标签页 + POST 处理 + 附件上传
├── lcbk_doc_show.php         前台入口：路由分发（首页/文档/下载/预览）
├── css/
│   └── jc-doc.css            前台样式（浅色/深色双主题变量，无第三方依赖）
├── files/                    附件上传目录（含 .htaccess 防护）
├── cache/                    渲染结果 JSON 缓存目录（运行时自动创建）
└── lib/
    ├── Parsedown.php         Markdown 解析器（内置副本）
    ├── ParsedownExtra.php    Markdown Extra 扩展解析器
    ├── lcbk_doc_kit.php      公共工具：配置读写、URL 生成、路由解析、输入过滤、扩展名校验、Range 解析、防盗链
    ├── lcbk_doc_md.php       Markdown 渲染入口：锚点/TOC 注入、HTML 净化、纯文本摘要、渲染缓存
    ├── lcbk_doc_store.php    数据访问层：栏目、文档、附件、下载日志的增删改查
    └── lcbk_doc_view.php     前台页面渲染、代码块交互脚本、附件下载/预览流式输出

数据表结构

全部表使用 utf8mb4_unicode_ci，表名前缀为 Emlog 的 DB_PREFIX（默认 emlog_）。

栏目表 {prefix}lcbk_doc_cat（v1.0.2 新增）

文档表 {prefix}lcbk_doc

附件表 {prefix}lcbk_doc_attach

下载日志表 {prefix}lcbk_doc_log

安全设计摘要

• 双保险扩展名校验：上传与输出环节同时校验白名单 + 危险脚本扩展名黑名单，即使后台白名单被改动，脚本文件也无法经插件下发。
• HTML 白名单净化：DOM 逐标签清理未知标签（剥壳留文本）、剥离 on* 事件属性、封禁 javascript: 伪协议；class 仅保留代码高亮所需的 language-*。
• 防注入：所有 SQL 均经 intval / Database::escape_string；前台标题、内容、URL 一律 htmlspecialchars 输出。
• 附件目录防护：files/.htaccess 禁目录列表 + 禁脚本执行 + 落盘随机名。
• 缓存安全：渲染缓存 JSON 只做纯文本读取，绝不 include / eval；缓存 key 绑定内容哈希，正文变化自然失效，删除文档时清理对应文件。
• 下载输出安全：清空输出缓冲后再流式输出二进制，避免页面污染；Content-Disposition 同时给出 ASCII 与 RFC 5987 编码文件名，兼容中文文件名下载。

常见问题

Q1：前台访问提示 404？ 确认 Emlog 是否开启伪静态。开启后地址为 /plugin/lcbk_doc；未开启用 ?plugin=lcbk_doc。仍不行请检查 系统 → 设置 → SEO 的伪静态规则是否生效。

Q2：文档里有表格 / 复杂 HTML，为什么显示成纯文本或变样？ Markdown 中嵌入的原生 HTML 需要 PHP 的 DOMDocument 扩展解析（白名单净化）；缺 DOM 扩展时会按纯文本转义处理。建议装好 dom 扩展（同时强烈建议启用 mbstring），可获得完整渲染体验。

Q3：大附件上传失败？ 先确认未超过 200MB 插件硬上限，再检查服务器 upload_max_filesize 与 post_max_size（需大于附件大小，必要时同步调大 max_execution_time）。

Q4：下载的中文文件名乱码？ 已按标准做法同时输出 filename 与 filename*=UTF-8''，现代浏览器正常；个别老旧下载工具可能退化，可改后端附件名为 ASCII 后上传。

Q5：会不会生成一堆静态文件拖慢站点？ 不会。插件是纯动态渲染，只在 cache/ 写少量 JSON 渲染缓存（正文不变即命中，正文一改自动失效），不产生任何静态 HTML。

Q6：删除插件会留残留数据吗？ 删除插件时回调会删除全部 4 张数据表与 Storage 配置；插件目录（含附件）由 Emlog 一并清理。建议删除前确认不再需要已有文档与附件。

更新日志

v1.0.3

新增

• 后台文档列表分页（每页 30）
• 后台写操作加入 CSRF 校验

修复

• 断点续传/流媒体重复计数下载
• 上/下篇无法跨栏目串联
• 阅读数刷新重复累加
• 搜索 % _ 被当通配符

安全

• 扩充禁止上传扩展名黑名单
• 收紧 files/.htaccess 脚本拦截
• 附件输出加 nosniff 头

v1.0.2

• 新增文档分类/栏目
• 新增代码块，高亮/一键复制
• 新增站内搜索
• 优化文档「上一篇 / 下一篇」仅在当前栏目内相邻，栏目切换后导航不串栏目。
• 修复若干渲染细节

v1.0.1

• 优化标题锚点
• 新增文档详情页底部上一篇 / 下一篇
• 新增返回顶部
• 优化返回文档列表移至页面顶部面包屑右侧

1.0.0

• 首发版本

许可说明

插件作者为 LAO.CHEN，通过 Emlog 官方插件市场分发。使用前请阅读 Emlog 插件分发页相关条款，本文件仅作使用说明。