<div align="center">
<img src="docs/logo.gif" width="160" height="160" alt="Aut_Sci-Html logo">
# Aut_Sci-Html
`Aut_Sci-Html` generates academic presentation-style HTML slide deck directories from Markdown, structured outlines, JSON deck data, or PDF papers.
[](LICENSE)
[](https://www.python.org/)
[Chinese README](README.zh.md)
</div>
## Overview
`Aut_Sci-Html` is a lightweight presentation runtime for academic content. It renders a complete deck directory instead of a single HTML file, which keeps HTML, CSS, JavaScript, copied figures, and intermediate artifacts separated and easier to inspect.
The project supports two main workflows:
- `generate`: Convert Markdown slides, structured outlines, or JSON deck data into an HTML deck.
- `paper`: Convert a PDF paper into a literature-report deck using integrated insight extraction and figure extraction.
## Installation
Basic deck generation:
```bash
python -m pip install -e .
```
Paper-to-HTML workflow with PDF and figure extraction:
```bash
python -m pip install -e .[paper]
```
Or install the pinned runtime dependencies:
```bash
python -m pip install -r requirements.txt
```
## Quick Start
Generate a deck from the sample outline:
```bash
python scripts/generate_html_deck.py generate examples/sample_outline.md -o out/sample-deck
```
Generate a deck from Markdown slides:
```bash
python scripts/generate_html_deck.py generate examples/sample_slides.md -o out/sample-slides --theme journal-dark
```
Open `out/sample-deck/index.html` or `out/sample-slides/index.html` in a browser.
## CLI
Top-level help:
```bash
python scripts/generate_html_deck.py --help
```
Subcommands:
- `generate`: Input is Markdown, structured outline text, or JSON deck data.
- `paper`: Input is a PDF file.
Example:
```bash
python scripts/generate_html_deck.py generate INPUT -o OUTPUT_DIR --theme academic-blue
python scripts/generate_html_deck.py paper PAPER.pdf -o OUTPUT_DIR --author "Your Name"
```
## Supported Input Styles
### 1. Structured outline
```text
Title: Lanthanide Luminescence
Author: Your Name
Affiliation: Literature Report
1. Research Background
- Why this topic matters
- Main scientific problem
2. Mechanism
- Energy transfer pathway
- Key design variables
```
### 2. Markdown slides
Use `---` as slide separators.
```markdown
---
title: Upconversion Nanoparticles
author: Your Name
affiliation: Group Meeting
theme: academic-blue
---
# Research Background
- Why the field matters
- Key bottlenecks
---
layout: section
subtitle: 02
# Mechanism
```
### 3. JSON deck data
Pass a deck JSON object to the `generate` command. The parser automatically detects JSON input files.
## Paper To HTML
Generate a literature-report deck directly from a PDF:
```bash
python scripts/generate_html_deck.py paper paper.pdf -o out/paper-report --author "Your Name"
```
Useful paper-mode options:
- `--paper-type auto|research|review`: Override automatic paper routing.
- `--theme academic-blue|journal-dark`: Select deck styling.
- `--dpi 300`: Figure extraction DPI.
- `--max-figures 6`: Maximum number of extracted figures.
- `--no-figures`: Skip figure extraction.
- `--verbose`: Show more extraction logs.
Research papers are organized around problem, method, results, innovation, applications, and limitations.
Review literature is organized around scope, taxonomy, evidence base, consensus, controversy, evidence quality, gaps, and future directions.
The PDF workflow writes:
- `structured_insights.json`
- `figure_manifest.json`
- `figures/`
- `{paper-stem}-deck.md`
- `deck.json`
- `assets/`
- `index.html`
## Themes
Built-in themes:
- `academic-blue`
- `journal-dark`
If an unknown theme is requested, the renderer falls back to `academic-blue`.
## Presentation Markup Rules
- Use `layout: section` to create chapter divider slides.
- Use `subtitle: 01` with section slides to show chapter numbering.
- Wrap emphasis with `**important**` or `==important==` to render red highlights.
- Bullet slides render as numbered key points by default.
- Slides with one or two bullets switch to a plain list treatment.
- Long titles are automatically scaled down.
## Navigation
- Click: next slide
- Click the left third of the screen: previous slide
- Right / Space / PageDown: next slide
- Left / PageUp: previous slide
- Home / End: first / last slide
- `F`: fullscreen
## Development
Run tests:
```bash
pytest
```
Project layout:
- [src/sci_html](/abs/path/D:/Skills/Aut_Sci-Html/src/sci_html)
- [scripts/generate_html_deck.py](/abs/path/D:/Skills/Aut_Sci-Html/scripts/generate_html_deck.py)
- [examples](/abs/path/D:/Skills/Aut_Sci-Html/examples)
- [themes](/abs/path/D:/Skills/Aut_Sci-Html/themes)
- [tests](/abs/path/D:/Skills/Aut_Sci-Html/tests)
## Notes
- Single-file HTML export is intentionally not supported.
- PDF figure extraction errors do not block deck generation; warnings are recorded in `figure_manifest.json`.
- This project uses a native lightweight runtime instead of reveal.js, Slidev, or Marp.
# Aut_Sci-Html
`Aut_Sci-Html` 用于把学术汇报内容生成成浏览器可直接打开的 HTML 幻灯片目录。输入可以是 Markdown、结构化提纲、JSON deck 数据，或者 PDF 论文。
[English README](README.md)
## 项目定位
这个项目不是单文件 HTML 导出器，而是生成一个完整的 deck 目录。这样可以把 HTML、CSS、JavaScript、提取出来的图片和中间产物分开管理，更适合学术报告场景下的检查、二次修改和分发。
主要有两种工作流：
- `generate`：把 Markdown、提纲或 JSON 转成 HTML 幻灯片。
- `paper`：把 PDF 论文直接转成文献汇报风格的 HTML deck。
## 安装
仅使用基础 deck 生成功能：
```bash
python -m pip install -e .
```
需要 PDF 论文解析和图片提取：
```bash
python -m pip install -e .[paper]
```
或者直接安装仓库里固定的依赖：
```bash
python -m pip install -r requirements.txt
```
## 快速开始
用示例提纲生成 deck：
```bash
python scripts/generate_html_deck.py generate examples/sample_outline.md -o out/sample-deck
```
用 Markdown 幻灯片生成 deck：
```bash
python scripts/generate_html_deck.py generate examples/sample_slides.md -o out/sample-slides --theme journal-dark
```
生成后直接打开：
```text
out/sample-deck/index.html
```
## 命令行
查看帮助：
```bash
python scripts/generate_html_deck.py --help
```
两个子命令：
- `generate`：输入是 Markdown、结构化提纲或 JSON。
- `paper`：输入是 PDF 文件。
常用形式：
```bash
python scripts/generate_html_deck.py generate INPUT -o OUTPUT_DIR --theme academic-blue
python scripts/generate_html_deck.py paper PAPER.pdf -o OUTPUT_DIR --author "Your Name"
```
## 支持的输入格式
### 1. 结构化提纲
```text
Title: 镧系发光
Author: Your Name
Affiliation: 文献汇报
1. 研究背景
- 为什么重要
- 主要科学问题
2. 机理
- 能量传递路径
- 关键设计变量
```
### 2. Markdown 幻灯片
使用 `---` 分隔幻灯片。
```markdown
---
title: Upconversion Nanoparticles
author: Your Name
affiliation: Group Meeting
theme: academic-blue
---
# Research Background
- Why the field matters
- Key bottlenecks
---
layout: section
subtitle: 02
# Mechanism
```
### 3. JSON deck
`generate` 子命令也支持 JSON deck 文件，解析器会自动识别。
## PDF 论文转 HTML
直接从 PDF 生成文献汇报 deck：
```bash
python scripts/generate_html_deck.py paper paper.pdf -o out/paper-report --author "Your Name"
```
常用参数：
- `--paper-type auto|research|review`：覆盖自动论文类型判断。
- `--theme academic-blue|journal-dark`：切换主题。
- `--dpi 300`：图片提取 DPI。
- `--max-figures 6`：最多放入的图片数量。
- `--no-figures`：跳过图片提取。
- `--verbose`：输出更详细的解析日志。
对原始研究论文，deck 会围绕这些部分组织：
- problem
- method
- results
- innovation
- applications
- limitations
对综述、系统综述、meta-analysis，deck 会围绕这些部分组织：
- scope
- taxonomy
- evidence base
- consensus
- controversy
- evidence quality
- gaps
- future directions
PDF 工作流会输出这些文件：
- `structured_insights.json`
- `figure_manifest.json`
- `figures/`
- `{paper-stem}-deck.md`
- `deck.json`
- `assets/`
- `index.html`
## 主题
内置主题：
- `academic-blue`
- `journal-dark`
如果传入未知主题，渲染器会自动回退到 `academic-blue`。
## 幻灯片标记规则
- 用 `layout: section` 生成章节分隔页。
- 用 `subtitle: 01` 给章节页显示编号。
- 用 `**重点**` 或 `==重点==` 标红强调文本。
- 普通内容页默认把 bullet 渲染成编号关键点。
- 当页面只有 1 到 2 条 bullet 时，会切换成更简洁的无编号样式。
- 标题过长时会自动缩小字号。
## 浏览控制
- 点击页面：下一页
- 点击页面左侧三分之一：上一页
- `Right` / `Space` / `PageDown`：下一页
- `Left` / `PageUp`：上一页
- `Home` / `End`：第一页 / 最后一页
- `F`：全屏
## 开发
运行测试：
```bash
pytest
```
主要目录：
- [src/sci_html](/abs/path/D:/Skills/Aut_Sci-Html/src/sci_html)
- [scripts/generate_html_deck.py](/abs/path/D:/Skills/Aut_Sci-Html/scripts/generate_html_deck.py)
- [examples](/abs/path/D:/Skills/Aut_Sci-Html/examples)
- [themes](/abs/path/D:/Skills/Aut_Sci-Html/themes)
- [tests](/abs/path/D:/Skills/Aut_Sci-Html/tests)
## 说明
- 项目故意不支持单文件 HTML 输出。
- PDF 图片提取失败不会阻塞 deck 生成，错误会写进 `figure_manifest.json`。
- 这个项目使用自带的轻量运行时，不依赖 reveal.js、Slidev 或 Marp。
---
## License
MIT License. See [LICENSE](LICENSE).