{"id":50400045,"url":"https://github.com/misakakuroko/bilingual-slide-study-kit","last_synced_at":"2026-05-30T23:00:31.625Z","repository":{"id":360209332,"uuid":"1249154701","full_name":"Misakakuroko/bilingual-slide-study-kit","owner":"Misakakuroko","description":"Turn lecture slides into bilingual exam-ready HTML study guides / 将课件转成双语考试复习 HTML","archived":false,"fork":false,"pushed_at":"2026-05-25T13:12:41.000Z","size":1499,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T14:21:31.846Z","etag":null,"topics":["bilingual","codex","codex-skill","education","exam-prep","html","lecture-notes","python","slides","study-guide"],"latest_commit_sha":null,"homepage":"https://misakakuroko.github.io/bilingual-slide-study-kit/examples/demo.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Misakakuroko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T12:06:05.000Z","updated_at":"2026-05-25T13:12:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Misakakuroko/bilingual-slide-study-kit","commit_stats":null,"previous_names":["misakakuroko/bilingual-slide-study-kit"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Misakakuroko/bilingual-slide-study-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Misakakuroko%2Fbilingual-slide-study-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Misakakuroko%2Fbilingual-slide-study-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Misakakuroko%2Fbilingual-slide-study-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Misakakuroko%2Fbilingual-slide-study-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Misakakuroko","download_url":"https://codeload.github.com/Misakakuroko/bilingual-slide-study-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Misakakuroko%2Fbilingual-slide-study-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33712579,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bilingual","codex","codex-skill","education","exam-prep","html","lecture-notes","python","slides","study-guide"],"created_at":"2026-05-30T23:00:30.637Z","updated_at":"2026-05-30T23:00:31.620Z","avatar_url":"https://github.com/Misakakuroko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bilingual-slide-study-kit\n\nLanguage: **English** | [简体中文](README.zh-CN.md)\n\n[![CI](https://github.com/Misakakuroko/bilingual-slide-study-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/Misakakuroko/bilingual-slide-study-kit/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)\n\nTurn lecture slides into bilingual, exam-ready HTML study kits.\n\n`bilingual-slide-study-kit` is a reusable Codex skill plus a deterministic slide-asset harness. It is built for students who study technical courses in a second language and need more than a summary: terminology, source-grounded explanations, exam-style English answers, Chinese translations, and visual memory aids from the original slides.\n\nIt is not a generic PPT-to-HTML converter. The goal is to turn a lecture PDF into a study page that helps a student understand the material, memorize the right terms, and write better exam answers.\n\n![Bilingual Slide Study Kit demo preview](examples/demo-preview.png)\n\nLive demo:\n[misakakuroko.github.io/bilingual-slide-study-kit/examples/demo.html](https://misakakuroko.github.io/bilingual-slide-study-kit/examples/demo.html)\n\nThe demo is self-authored and public-safe. It does not use private course material.\n\n## Case Gallery\n\nThe images below show the intended review-page experience in order. The second visual-explanation screenshot is a public-safe replacement that uses self-authored mock diagrams instead of real PPT pages.\n\n### 1. Module Overview\n\n![Module overview](examples/case-01-overview.png)\n\n### 2. Visual Explanation\n\n![Visual explanation cards](examples/case-02-visual-explanation.png)\n\n### 3. Terminology Cards\n\n![Terminology cards](examples/case-03-terminology.png)\n\n### 4. Exam-Ready Short Answers\n\n![Exam-ready short answers](examples/case-04-short-answers.png)\n\n### 5. Method Comparison\n\n![Method comparison cards](examples/case-05-comparison.png)\n\n## Why This Exists\n\nMany students do not fail technical courses because they are incapable of understanding the science. They struggle because the lecture slides, technical vocabulary, and expected exam wording are all in a second language.\n\nThis project packages a workflow for turning those slides into a bilingual study kit that can be reviewed on desktop or mobile.\n\n## What It Creates\n\nFor each lecture module, the workflow can produce a standalone HTML review page with:\n\n- a slide-range logic map,\n- selected PPT/PDF screenshots,\n- detailed explanations of important diagrams,\n- important terminology with Chinese support,\n- exam-ready English short-answer material,\n- full Chinese translations of English answer sentences,\n- method comparisons,\n- common confusions and misconceptions,\n- a memorization order for final exam or resit preparation.\n\n## Supported Platforms\n\nThe project is cross-platform. It is a Python harness plus a Codex skill, not a macOS-only app.\n\n| Platform | Status | Notes |\n| --- | --- | --- |\n| macOS | Supported | Best tested. Uses `sips` for optional image resizing when available. |\n| Linux | Supported | Tested through CI for the Python harness. |\n| Windows | Supported | Requires Python and Poppler command-line tools in `PATH`. |\n\n## Quick Start\n\n### 1. Install Requirements\n\nYou need Python 3.10+ and Poppler command-line tools:\n\n- `pdfinfo`\n- `pdftotext`\n- `pdftoppm`\n\nmacOS:\n\n```bash\nbrew install poppler\n```\n\nUbuntu/Debian:\n\n```bash\nsudo apt-get update\nsudo apt-get install poppler-utils\n```\n\nWindows PowerShell:\n\n```powershell\nwinget install Python.Python.3.12\nwinget install oschwartz10612.Poppler\n```\n\nAfter installing Poppler on Windows, open a new terminal and check:\n\n```powershell\npdfinfo -v\npdftotext -v\npdftoppm -v\n```\n\nIf those commands are not found, add Poppler's `Library\\bin` or `bin` folder to your Windows `PATH`.\n\n### 2. Install The Codex Skill\n\nClone the repository:\n\n```bash\ngit clone https://github.com/Misakakuroko/bilingual-slide-study-kit.git\ncd bilingual-slide-study-kit\n```\n\nmacOS/Linux:\n\n```bash\nmkdir -p ~/.codex/skills\ncp -R skills/course-ppt-review-html ~/.codex/skills/\n```\n\nWindows PowerShell:\n\n```powershell\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\\skills\"\nCopy-Item -Recurse \".\\skills\\course-ppt-review-html\" \"$env:USERPROFILE\\.codex\\skills\\\"\n```\n\nStart a new Codex session and invoke:\n\n```text\nUse $course-ppt-review-html to turn this lecture PDF into an exam-ready bilingual HTML review page with detailed slide explanations.\n```\n\nYou can also use a short natural-language request:\n\n```text\nGenerate a review HTML page for the Signal Processing course.\nTurn this PPT into an exam-ready review HTML page.\nCreate a bilingual study page for this module.\n```\n\n### 3. Prepare Slide Assets\n\nThe harness extracts slide text, selected slide screenshots, a manifest, and reusable HTML snippets.\n\nmacOS/Linux:\n\n```bash\npython3 scripts/prepare_ppt_review_assets.py \\\n  --pdf \"/path/to/lecture.pdf\" \\\n  --output-dir \"./out/module_assets\" \\\n  --prefix \"module\" \\\n  --pages \"3,4,7-10,13,16-18,20-21\" \\\n  --clean\n```\n\nWindows PowerShell:\n\n```powershell\npy -3 .\\scripts\\prepare_ppt_review_assets.py `\n  --pdf \"C:\\path\\to\\lecture.pdf\" `\n  --output-dir \".\\out\\module_assets\" `\n  --prefix \"module\" `\n  --pages \"3,4,7-10,13,16-18,20-21\" `\n  --clean\n```\n\nOutputs:\n\n- `module_slides_text.txt`\n- `module_manifest.json`\n- `module-slide-03.jpg` etc.\n- `module_visual_snippets.html`\n\n### 4. Render and Audit a Fixed-Quality Page\n\nTo prevent the final page from drifting into a plain summary, use the spec -\u003e render -\u003e audit workflow. Codex fills the knowledge content in JSON; the harness owns the stable page structure and quality gate.\n\n```bash\npython3 scripts/build_review_page.py init-spec \\\n  --manifest \"./out/module_assets/module_manifest.json\" \\\n  --image-base \"module_assets\" \\\n  --course-title \"Course Name\" \\\n  --module-title \"Module Name\" \\\n  --output \"./out/module.review-spec.json\"\n```\n\nAfter completing `module.review-spec.json`:\n\n```bash\npython3 scripts/build_review_page.py validate-spec --spec \"./out/module.review-spec.json\"\npython3 scripts/build_review_page.py render --spec \"./out/module.review-spec.json\" --output \"./out/module.html\"\npython3 scripts/build_review_page.py audit --html \"./out/module.html\"\n```\n\nThe audit checks navigation, detailed visual explanations, term cards, English answer cards, Chinese translations, source labels, and broken images. A page with no `.term-card`, `.answer-card`, `.explain-item`, or `.exam-line` fails.\n\n## Example Prompt\n\n```text\nUse $course-ppt-review-html to generate final review HTML pages for these modules.\n\nCourse directory:\n/path/to/course\n\nModules:\n1. Recording Brain Activity: /path/to/recording.pdf\n2. EMG: /path/to/emg.pdf\n3. TMS: /path/to/tms.pdf\n\nRequirements:\n- Do not impose a fixed number of terms or short answers.\n- Include every concept that helps exam performance.\n- Add detailed explanations for important PPT images.\n- For each slide image, explain what it teaches, how to read it, what to remember, an exam-ready English sentence, and one common misconception.\n- English short answers must have full Chinese sentence translations.\n- Prioritize slide-grounded content and label slide sources.\n- Verify mobile readability and broken images.\n```\n\n## Repository Layout\n\n```text\nbilingual-slide-study-kit/\n├── README.md\n├── README.zh-CN.md\n├── LICENSE\n├── pyproject.toml\n├── scripts/\n│   ├── prepare_ppt_review_assets.py\n│   └── build_review_page.py\n├── skills/\n│   └── course-ppt-review-html/\n│       ├── SKILL.md\n│       ├── agents/openai.yaml\n│       ├── references/review-page-criteria.md\n│       └── scripts/\n│           ├── prepare_ppt_review_assets.py\n│           └── build_review_page.py\n├── templates/\n│   └── visual-card.html\n├── examples/\n│   ├── README.md\n│   ├── case-01-overview.png\n│   ├── case-02-visual-explanation.png\n│   ├── case-03-terminology.png\n│   ├── case-04-short-answers.png\n│   ├── case-05-comparison.png\n│   ├── demo.html\n│   └── demo-preview.png\n└── tests/\n    ├── test_prepare_ppt_review_assets.py\n    └── test_build_review_page.py\n```\n\n## Design Principles\n\n- Source grounded: label whether content comes from slides, generated reasoning, or user-provided material.\n- Exam oriented: every explanation should help with recall, comparison, or answer writing.\n- Bilingual by default: English exam sentences should include full Chinese translations.\n- Visual memory first: important diagrams should be explained, not merely embedded.\n- Privacy aware: course PDFs, copyrighted screenshots, and personal paths should stay out of the repository.\n\n## Copyright And Privacy\n\nDo not commit course PDFs, copyrighted slide screenshots, generated review pages based on private course material, or personal paths. The `.gitignore` excludes common slide and generated asset files by default.\n\nFor a public demo, use self-authored or openly licensed slides.\n\n## License\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisakakuroko%2Fbilingual-slide-study-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmisakakuroko%2Fbilingual-slide-study-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmisakakuroko%2Fbilingual-slide-study-kit/lists"}