# Doc简单文档

emlog Pro 文档插件：后台用 Markdown 撰写文档，前台动态解析渲染为 HTML 文档页。

- 基于 Markdown **H2（二级标题）自动生成 TOC 目录**（桌面端侧栏 + 移动端抽屉按钮）
- 支持自定义附件（zip / pdf / docx / mp3 …）上传，前台详情页底部展示并**记录下载日志（时间 / 文件名 / 文档 / IP / User-Agent）**
- 支持 `showPageLink` 前台入口，前台访问地址在后台可直接查看
- **不生成、不缓存任何静态 HTML 文件**：每次请求现解析 Markdown，文档正文存数据库（LONGTEXT）

- 作者：<a href="https://www.emlog.net/profiles/f065546a">LAO.CHEN</a>
- 插件：<a href="https://www.emlog.net/plugin/detail/1259">Doc简单文档</a>

---

## 目录结构

```
content/plugins/lcbk_doc/
├── lcbk_doc.php              # 插件主文件（常量、依赖加载）
├── lcbk_doc_callback.php     # 启用/更新/删除回调（建表、种子配置、卸载清理）
├── lcbk_doc_setting.php      # 后台：基本设置 / 文档管理 / 下载日志
├── lcbk_doc_show.php         # 前台入口（路由分发）
├── css/jc-doc.css            # 前台样式
├── lib/
│   ├── lcbk_doc_kit.php      # 配置、URL、路由、输入过滤等工具
│   ├── lcbk_doc_md.php       # Markdown 渲染、净化、H2 目录/锚点
│   ├── lcbk_doc_store.php    # 文档/附件/下载日志 数据层
│   ├── lcbk_doc_view.php     # 前台页面骨架与渲染
│   ├── Parsedown.php         # 渲染库（类已重命名 JcParsedown，避免与 emlog 核心/其他插件冲突）
│   └── ParsedownExtra.php    # 渲染库（JcParsedownExtra）
└── README.md
```

---

## 安装

1. 将 `lcbk_doc` 整个目录上传到 `content/plugins/` 下。
2. 确保该目录及其子目录可写（上传附件时插件会在此自动创建 `files/` 子目录）：

   ```bash
   # 服务器命令行示例（请按实际路径执行）
   chmod -R 755 content/plugins/lcbk_doc
   chown -R <web用户>:<web用户组> content/plugins/lcbk_doc
   ```

3. 进入后台 **插件管理**，启用`Doc简单文档`。
   启用时会自动创建三张数据表并写入默认配置，无需手工建表：

   | 表 | 用途 |
   | --- | --- |
   | `emlog_lcbk_doc` | 文档（标题/简介/Markdown/排序/显隐/阅读数） |
   | `emlog_lcbk_doc_attach` | 附件（所属文档/文件名/存储名/大小/下载数） |
   | `emlog_lcbk_doc_log` | 附件下载日志 |

   > 实际表前缀以你的 `DB_PREFIX` 为准（默认 `emlog_`）。

---

## 使用

后台入口：**插件 → Doc简单文档**（或访问 `admin/plugin.php?plugin=lcbk_doc`）。

### 基本设置
- 文档名称 / 文档副标题 / 文档简介：展示在文档首页顶部。
- 文档内自动目录：是否按 H2 在详情页生成 TOC。
- 允许下载的扩展名：逗号分隔白名单；**php 等脚本类扩展名永远不允许上传/下载**。

### 文档管理
- 「新增文档」/「编辑」：在线编写 Markdown，支持「导入 .md 文件」直接读入编辑器、一键预览（复用 emlog 后台内置 marked）。
- 文档简介留空时，前台列表与摘要自动从正文截取。
- 排序：数字越小越靠前；状态开关控制前台是否可见。
- 编辑已保存的文档时，可在下方为它上传附件。

### 下载日志
- 查看最近 200 条附件下载记录（时间 / 文件名 / 所属文档 / IP / User-Agent），可一键清空。

---

## 前台访问

安装并启用后，前台通过如下地址访问（「查看前台」按钮会自动带你去正确地址）：

| 模式 | 文档首页 | 文档详情 | 附件下载 |
| --- | --- | --- | --- |
| 伪静态（后台开启链接模式） | `https://你的域名/plugin/lcbk_doc` | `https://你的域名/plugin/lcbk_doc/doc/3` | `https://你的域名/plugin/lcbk_doc/download/7` |
| 默认（关闭链接模式） | `https://你的域名/?plugin=lcbk_doc` | `https://你的域名/?plugin=lcbk_doc&doc=3` | `https://你的域名/?plugin=lcbk_doc&download=7` |

前台由插件自行输出页面，不受模板影响。

---

## Markdown 写作约定

- **H2（`## `）会进入 TOC 目录**，并自动获得 `jc-sec-N` 锚点。
- H1 / H3–H6 不进入目录，但也会获得 `jc-hd-N` 锚点供页内跳转。
- 支持 GFM 表格、围栏代码块（` ```lang `）、任务列表等（ParsedownExtra）。
- 渲染结果会做安全净化：剥离 `script/style/object/embed/svg/math` 等标签、全部 `on*` 事件属性、`javascript:` 伪协议。
- 建议第一个标题用 `# 文档名`，后续章节用 `## 章节`。

---

## 附件说明

- 上传白名单：后台「基本设置 → 允许下载的扩展名」。
- 物理文件存放：`content/plugins/lcbk_doc/files/`，按 `d{文档ID}_{时间戳}_{随机串}.{扩展名}` 重命名（原始文件名仅用于展示），并在下载时再次校验扩展名属于白名单。
- 单文件上限：**200 MB**（同时受 php.ini `upload_max_filesize` / `post_max_size` 限制）。
- 每次下载先写日志、累加计数，再以二进制方式输出文件。
- 删除文档/附件会同步清理数据库记录、下载日志与磁盘文件。

> 建议在服务器层再封一层（示例为 Apache `.htaccess`，随插件提供于 `files/.htaccess`）：禁止列目录，并拒绝把 `files/` 下的任何文件当脚本执行。Nginx 用户请在站点配置中增加 `location ~ ^/content/plugins/lcbk_doc/files/.*\.php$ { deny all; }` 等规则。

---

## 卸载

后台停用插件即可；若需彻底卸载，请先到后台删除该插件，删除回调会自动：

1. `DROP` 三张数据表；
2. 清空 `emlog_storage` 中该插件的配置项。

> 插件目录本身由 emlog 删除流程移除；`files/` 内上传的附件随目录一并删除。

---

## 环境要求与兼容性

- 需要 emlog Pro（采用 `mysqli` 或 `pdo` 数据库驱动均可，代码对两种驱动做了兼容）。
- `mbstring`、`dom` 扩展**非必需**：
  - 缺少 `mbstring` 时自动以多字节安全方式截断文本；
  - 缺少 `dom` 时 Markdown 中原生 HTML 片段自动按纯文本转义显示，不会报错。
- 插件自带的 Markdown 渲染类已重命名（`JcParsedown*`），与 emlog 核心或其他插件的 Parsedown 互不冲突。