# RevealPack
**A comprehensive CLI tool for managing and building multiple Reveal.js presentations with shared themes and resources.**
RevealPack is designed for creating suites of presentations that share themes and resources, such as lecture series, multi-day seminars, or training programs. It abstracts the slide deck creation process while providing complete control over individual slides or groups of slides within each presentation.
## 🚀 Key Features
- **Multi-Presentation Management**: Create and manage multiple presentations from a single project
- **Shared Resources**: Common libraries, themes, and assets across all presentations
- **Flexible Content**: Support for HTML, Markdown, and mixed content slides
- **Live Development**: Real-time preview with automatic rebuilds on file changes
- **Theme Compilation**: SCSS/SASS support with Dart Sass compilation
- **Plugin Management**: Built-in and external plugin support with automatic downloading
- **Distribution Ready**: Package presentations for standalone distribution
- **Customizable**: Extensive configuration options for themes, plugins, and presentation settings
## 📋 Requirements
- **Python** >= 3.12 (3.9+ supported, 3.12+ recommended)
- **Dart Sass CLI** - Required for SCSS/SASS theme compilation
- **Reveal.js** >= 4.0.0 (tested with 5.2.1, backwards compatible with 4.x)
### Install Dart Sass
RevealPack requires the Dart Sass CLI to compile SCSS/SASS theme files. **The build process will fail without it.**
**Install Dart Sass from the official website:**
- Visit [https://sass-lang.com/install](https://sass-lang.com/install)
- Follow the installation instructions for your operating system
- Ensure `sass` is available in your system PATH
**Alternative installation methods:**
```bash
# macOS (using Homebrew)
brew install sass/sass/sass
# Windows (using Chocolatey)
choco install sass
# Linux (using npm)
npm install -g sass
```
**Verify installation:**
```bash
sass --version
```
## 🛠️ Installation
### Install RevealPack from PyPI
```bash
pip install revealpack
```
*Note: Use the appropriate method for your setup, e.g., `pip3` or `python -m pip...`*
## 🏗️ Project Structure
RevealPack creates a structured project with the following organization:
```
your-project/
├── config.json # Project configuration
├── assets/ # RevealPack assets and themes
├── source/ # Source files
│ ├── lib/ # Shared libraries and assets
│ ├── decks/ # Individual presentation decks
│ │ ├── lecture-01/ # Each subdirectory = one presentation
│ │ │ ├── slide1.html
│ │ │ ├── slide2.html
│ │ │ └── presentation.json
│ │ └── lecture-02/
│ ├── cached/ # Downloaded packages (Reveal.js, plugins)
│ ├── reveal_template.html # Generated presentation template
│ └── toc_template.html # Generated table of contents template
└── build/ # Built presentations (output)
├── index.html # Table of contents
├── lecture-01/
└── lecture-02/
```
## 🚀 Quick Start
### 1. Initialize a New Project
```bash
# Create a new directory and navigate to it
mkdir my-presentations
cd my-presentations
# Initialize RevealPack project
revealpack init
```
This creates:
- `config.json` with default settings
- `assets/` directory with RevealPack resources
### 2. Configure Your Project
Edit `config.json` to customize:
- Project information (title, authors, version)
- Directory structure
- Reveal.js version and plugins
- Theme settings
- Presentation configurations
### 3. Set Up Development Environment
```bash
revealpack setup
```
This:
- Creates necessary directories
- Downloads Reveal.js and specified plugins
- Validates theme configuration
- Generates presentation templates
### 4. Create Your Presentations
Add content to `source/decks/`:
- Each subdirectory becomes a separate presentation
- Use HTML or Markdown for slides
- Optionally add `presentation.json` for metadata
### 5. Build Presentations
```bash
revealpack build
```
This compiles all presentations with:
- Theme compilation (SCSS → CSS)
- Plugin integration
- Asset copying
- HTML generation
### 6. Serve for Development
```bash
revealpack serve
```
Starts a local server with live reloading for development.
## 📖 Commands Reference
### `revealpack init [--destination PATH]`
Initialize a new RevealPack project by copying configuration and assets.
### `revealpack setup [--root PATH]`
Set up the development environment:
- Creates project directories
- Downloads Reveal.js and plugins
- Validates theme configuration
- Generates templates
### `revealpack build [OPTIONS]`
Build all presentations or specified decks.
**Options:**
- `--root PATH`: Root directory (default: current directory)
- `--clean`: Perform clean build (removes existing build files)
- `--decks LIST`: Build specific decks (comma-separated or file path)
- `--log-level LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
### `revealpack serve [OPTIONS]`
Serve presentations with live reloading for development.
**Options:**
- `--root PATH`: Root directory (default: current directory)
- `--no-build`: Skip initial build, serve existing files only
- `--clean`: Perform clean build before serving
- `--decks LIST`: Build and serve specific decks
### `revealpack package [OPTIONS]`
Package presentations for distribution (creates Electron app).
**Options:**
- `--root PATH`: Root directory (default: current directory)
- `--target-dir PATH`: Output directory for package
- `--no-build`: Skip build step
- `--clean`: Perform clean build before packaging
- `--decks LIST`: Package specific decks
### `revealpack docs`
Open RevealPack documentation in your browser.
## ⚙️ Configuration
The `config.json` file controls all aspects of your project:
### Project Information
```json
{
"info": {
"authors": ["Your Name"],
"short_title": "Lectures",
"project_title": "Science Lectures",
"year": "2024",
"version": "1.0.0"
}
}
```
### Directory Structure
```json
{
"directories": {
"build": "build",
"package": "dist",
"source": {
"root": "source",
"presentation_root": "decks",
"libraries": "lib"
}
}
}
```
### Reveal.js and Plugins
```json
{
"packages": {
"reveal.js": "5.2.1",
"reveal_plugins": {
"built_in": ["notes", "highlight", "math"],
"external": {
"plugin-name": {
"version": "1.0.0",
"url": "https://example.com/plugin.zip",
"alias": "optional-alias",
"main": "main-file"
}
}
}
}
}
```
**Note:** RevealPack is tested with Reveal.js 5.2.1 and is backwards compatible with Reveal.js 4.x versions.
### Theme Configuration
```json
{
"theme": "path/to/theme.scss",
"highlight_theme": "monokai",
"custom_scripts": ["path/to/script.js"]
}
```
### Reveal.js Settings
```json
{
"reveal_configurations": {
"center": false,
"controls": true,
"transition": "fade",
"width": 1920,
"height": 1080
}
}
```
## 🎨 Theming
RevealPack supports both pre-compiled CSS and SCSS/SASS themes:
### SCSS/SASS Themes
- Create `.scss` or `.sass` files
- Use variables, mixins, and nested rules
- Automatic compilation with Dart Sass
- Hot reloading during development
### Theme Structure
```scss
// Example theme.scss
$primary-color: #007acc;
$background-color: #f8f9fa;
.reveal {
background-color: $background-color;
.slides section {
color: $primary-color;
}
}
```
## 📝 Content Creation
### HTML Slides
Create individual HTML files for each slide:
```html
<!-- slide1.html -->
<section>
<h1>Welcome to My Presentation</h1>
<p>This is the first slide</p>
</section>
```
### Markdown Support
Use Markdown for simpler content:
```markdown
# Welcome to My Presentation
This is the first slide
---
## Second Slide
- Point 1
- Point 2
- Point 3
```
### Presentation Metadata
Add `presentation.json` to customize individual presentations:
```json
{
"title": "Lecture 1: Introduction",
"author": "Dr. Smith",
"date": "2024-01-15",
"slides": [
"slide1.html",
"slide2.html",
"slide3.html"
]
}
```
## 🔧 Troubleshooting
### Dart Sass Issues
If you encounter errors related to SCSS compilation:
1. **Check if Dart Sass is installed:**
```bash
sass --version
```
2. **If not installed, install Dart Sass:**
- Visit [https://sass-lang.com/install](https://sass-lang.com/install)
- Follow the installation instructions for your operating system
3. **If installed but not found, check your PATH:**
- Ensure the directory containing the `sass` executable is in your system PATH
- Restart your terminal/command prompt after installation
4. **Environment variable override:**
You can specify a custom path to the Dart Sass executable using the `REVEALPACK_SASS_PATH` environment variable:
```bash
export REVEALPACK_SASS_PATH=/path/to/your/sass
revealpack build
```
### Common Error Messages
- **"Dart Sass CLI not found"**: Install Dart Sass from the official website
- **"SCSS compilation failed"**: Check your SCSS syntax and ensure Dart Sass is properly installed
- **"Plugin download failed"**: Check your internet connection and plugin URLs
- **"Theme not found"**: Verify the theme path in `config.json`
## 🤝 Contributing
For more detailed information on development, see the [Developer's Guide](https://revealpack.readthedocs.io/en/latest/dev/).
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "RevealPack",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "CLI, Reveal.js, presentation, slides, slide deck, presentation tools, HTML presentations, automation, package manager, documentation, theming, templating, Python, Markdown, web development, JavaScript, build system",
"author": "Khris Griffis, Ph.D.",
"author_email": "khris.griffis.phd@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/12/18/1f164f34f0d526b2149c41e10b0bad288b79449697823b3fb7bf63c56cba/revealpack-1.3.0.tar.gz",
"platform": null,
"description": "# RevealPack\n\n**A comprehensive CLI tool for managing and building multiple Reveal.js presentations with shared themes and resources.**\n\nRevealPack is designed for creating suites of presentations that share themes and resources, such as lecture series, multi-day seminars, or training programs. It abstracts the slide deck creation process while providing complete control over individual slides or groups of slides within each presentation.\n\n## \ud83d\ude80 Key Features\n\n- **Multi-Presentation Management**: Create and manage multiple presentations from a single project\n- **Shared Resources**: Common libraries, themes, and assets across all presentations\n- **Flexible Content**: Support for HTML, Markdown, and mixed content slides\n- **Live Development**: Real-time preview with automatic rebuilds on file changes\n- **Theme Compilation**: SCSS/SASS support with Dart Sass compilation\n- **Plugin Management**: Built-in and external plugin support with automatic downloading\n- **Distribution Ready**: Package presentations for standalone distribution\n- **Customizable**: Extensive configuration options for themes, plugins, and presentation settings\n\n## \ud83d\udccb Requirements\n\n- **Python** >= 3.12 (3.9+ supported, 3.12+ recommended)\n- **Dart Sass CLI** - Required for SCSS/SASS theme compilation\n- **Reveal.js** >= 4.0.0 (tested with 5.2.1, backwards compatible with 4.x)\n\n### Install Dart Sass\n\nRevealPack requires the Dart Sass CLI to compile SCSS/SASS theme files. **The build process will fail without it.**\n\n**Install Dart Sass from the official website:**\n- Visit [https://sass-lang.com/install](https://sass-lang.com/install)\n- Follow the installation instructions for your operating system\n- Ensure `sass` is available in your system PATH\n\n**Alternative installation methods:**\n```bash\n# macOS (using Homebrew)\nbrew install sass/sass/sass\n\n# Windows (using Chocolatey)\nchoco install sass\n\n# Linux (using npm)\nnpm install -g sass\n```\n\n**Verify installation:**\n```bash\nsass --version\n```\n\n## \ud83d\udee0\ufe0f Installation\n\n### Install RevealPack from PyPI\n\n```bash\npip install revealpack\n```\n\n*Note: Use the appropriate method for your setup, e.g., `pip3` or `python -m pip...`*\n\n## \ud83c\udfd7\ufe0f Project Structure\n\nRevealPack creates a structured project with the following organization:\n\n```\nyour-project/\n\u251c\u2500\u2500 config.json # Project configuration\n\u251c\u2500\u2500 assets/ # RevealPack assets and themes\n\u251c\u2500\u2500 source/ # Source files\n\u2502 \u251c\u2500\u2500 lib/ # Shared libraries and assets\n\u2502 \u251c\u2500\u2500 decks/ # Individual presentation decks\n\u2502 \u2502 \u251c\u2500\u2500 lecture-01/ # Each subdirectory = one presentation\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 slide1.html\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 slide2.html\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 presentation.json\n\u2502 \u2502 \u2514\u2500\u2500 lecture-02/\n\u2502 \u251c\u2500\u2500 cached/ # Downloaded packages (Reveal.js, plugins)\n\u2502 \u251c\u2500\u2500 reveal_template.html # Generated presentation template\n\u2502 \u2514\u2500\u2500 toc_template.html # Generated table of contents template\n\u2514\u2500\u2500 build/ # Built presentations (output)\n \u251c\u2500\u2500 index.html # Table of contents\n \u251c\u2500\u2500 lecture-01/\n \u2514\u2500\u2500 lecture-02/\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Initialize a New Project\n\n```bash\n# Create a new directory and navigate to it\nmkdir my-presentations\ncd my-presentations\n\n# Initialize RevealPack project\nrevealpack init\n```\n\nThis creates:\n- `config.json` with default settings\n- `assets/` directory with RevealPack resources\n\n### 2. Configure Your Project\n\nEdit `config.json` to customize:\n- Project information (title, authors, version)\n- Directory structure\n- Reveal.js version and plugins\n- Theme settings\n- Presentation configurations\n\n### 3. Set Up Development Environment\n\n```bash\nrevealpack setup\n```\n\nThis:\n- Creates necessary directories\n- Downloads Reveal.js and specified plugins\n- Validates theme configuration\n- Generates presentation templates\n\n### 4. Create Your Presentations\n\nAdd content to `source/decks/`:\n- Each subdirectory becomes a separate presentation\n- Use HTML or Markdown for slides\n- Optionally add `presentation.json` for metadata\n\n### 5. Build Presentations\n\n```bash\nrevealpack build\n```\n\nThis compiles all presentations with:\n- Theme compilation (SCSS \u2192 CSS)\n- Plugin integration\n- Asset copying\n- HTML generation\n\n### 6. Serve for Development\n\n```bash\nrevealpack serve\n```\n\nStarts a local server with live reloading for development.\n\n## \ud83d\udcd6 Commands Reference\n\n### `revealpack init [--destination PATH]`\nInitialize a new RevealPack project by copying configuration and assets.\n\n### `revealpack setup [--root PATH]`\nSet up the development environment:\n- Creates project directories\n- Downloads Reveal.js and plugins\n- Validates theme configuration\n- Generates templates\n\n### `revealpack build [OPTIONS]`\nBuild all presentations or specified decks.\n\n**Options:**\n- `--root PATH`: Root directory (default: current directory)\n- `--clean`: Perform clean build (removes existing build files)\n- `--decks LIST`: Build specific decks (comma-separated or file path)\n- `--log-level LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n\n### `revealpack serve [OPTIONS]`\nServe presentations with live reloading for development.\n\n**Options:**\n- `--root PATH`: Root directory (default: current directory)\n- `--no-build`: Skip initial build, serve existing files only\n- `--clean`: Perform clean build before serving\n- `--decks LIST`: Build and serve specific decks\n\n### `revealpack package [OPTIONS]`\nPackage presentations for distribution (creates Electron app).\n\n**Options:**\n- `--root PATH`: Root directory (default: current directory)\n- `--target-dir PATH`: Output directory for package\n- `--no-build`: Skip build step\n- `--clean`: Perform clean build before packaging\n- `--decks LIST`: Package specific decks\n\n### `revealpack docs`\nOpen RevealPack documentation in your browser.\n\n## \u2699\ufe0f Configuration\n\nThe `config.json` file controls all aspects of your project:\n\n### Project Information\n```json\n{\n \"info\": {\n \"authors\": [\"Your Name\"],\n \"short_title\": \"Lectures\",\n \"project_title\": \"Science Lectures\",\n \"year\": \"2024\",\n \"version\": \"1.0.0\"\n }\n}\n```\n\n### Directory Structure\n```json\n{\n \"directories\": {\n \"build\": \"build\",\n \"package\": \"dist\",\n \"source\": {\n \"root\": \"source\",\n \"presentation_root\": \"decks\",\n \"libraries\": \"lib\"\n }\n }\n}\n```\n\n### Reveal.js and Plugins\n```json\n{\n \"packages\": {\n \"reveal.js\": \"5.2.1\",\n \"reveal_plugins\": {\n \"built_in\": [\"notes\", \"highlight\", \"math\"],\n \"external\": {\n \"plugin-name\": {\n \"version\": \"1.0.0\",\n \"url\": \"https://example.com/plugin.zip\",\n \"alias\": \"optional-alias\",\n \"main\": \"main-file\"\n }\n }\n }\n }\n}\n```\n\n**Note:** RevealPack is tested with Reveal.js 5.2.1 and is backwards compatible with Reveal.js 4.x versions.\n\n### Theme Configuration\n```json\n{\n \"theme\": \"path/to/theme.scss\",\n \"highlight_theme\": \"monokai\",\n \"custom_scripts\": [\"path/to/script.js\"]\n}\n```\n\n### Reveal.js Settings\n```json\n{\n \"reveal_configurations\": {\n \"center\": false,\n \"controls\": true,\n \"transition\": \"fade\",\n \"width\": 1920,\n \"height\": 1080\n }\n}\n```\n\n## \ud83c\udfa8 Theming\n\nRevealPack supports both pre-compiled CSS and SCSS/SASS themes:\n\n### SCSS/SASS Themes\n- Create `.scss` or `.sass` files\n- Use variables, mixins, and nested rules\n- Automatic compilation with Dart Sass\n- Hot reloading during development\n\n### Theme Structure\n```scss\n// Example theme.scss\n$primary-color: #007acc;\n$background-color: #f8f9fa;\n\n.reveal {\n background-color: $background-color;\n \n .slides section {\n color: $primary-color;\n }\n}\n```\n\n## \ud83d\udcdd Content Creation\n\n### HTML Slides\nCreate individual HTML files for each slide:\n\n```html\n<!-- slide1.html -->\n<section>\n <h1>Welcome to My Presentation</h1>\n <p>This is the first slide</p>\n</section>\n```\n\n### Markdown Support\nUse Markdown for simpler content:\n\n```markdown\n# Welcome to My Presentation\n\nThis is the first slide\n\n---\n\n## Second Slide\n\n- Point 1\n- Point 2\n- Point 3\n```\n\n### Presentation Metadata\nAdd `presentation.json` to customize individual presentations:\n\n```json\n{\n \"title\": \"Lecture 1: Introduction\",\n \"author\": \"Dr. Smith\",\n \"date\": \"2024-01-15\",\n \"slides\": [\n \"slide1.html\",\n \"slide2.html\",\n \"slide3.html\"\n ]\n}\n```\n\n## \ud83d\udd27 Troubleshooting\n\n### Dart Sass Issues\n\nIf you encounter errors related to SCSS compilation:\n\n1. **Check if Dart Sass is installed:**\n ```bash\n sass --version\n ```\n\n2. **If not installed, install Dart Sass:**\n - Visit [https://sass-lang.com/install](https://sass-lang.com/install)\n - Follow the installation instructions for your operating system\n\n3. **If installed but not found, check your PATH:**\n - Ensure the directory containing the `sass` executable is in your system PATH\n - Restart your terminal/command prompt after installation\n\n4. **Environment variable override:**\n You can specify a custom path to the Dart Sass executable using the `REVEALPACK_SASS_PATH` environment variable:\n ```bash\n export REVEALPACK_SASS_PATH=/path/to/your/sass\n revealpack build\n ```\n\n### Common Error Messages\n\n- **\"Dart Sass CLI not found\"**: Install Dart Sass from the official website\n- **\"SCSS compilation failed\"**: Check your SCSS syntax and ensure Dart Sass is properly installed\n- **\"Plugin download failed\"**: Check your internet connection and plugin URLs\n- **\"Theme not found\"**: Verify the theme path in `config.json`\n\n## \ud83e\udd1d Contributing\n\nFor more detailed information on development, see the [Developer's Guide](https://revealpack.readthedocs.io/en/latest/dev/).\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI tool for managing Reveal.js presentation packages",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://revealpack.readthedocs.io/en/latest/",
"Homepage": "https://github.com/Khlick/RevealPack",
"Issues": "https://github.com/Khlick/RevealPack/issues",
"Repository": "https://github.com/Khlick/RevealPack"
},
"split_keywords": [
"cli",
" reveal.js",
" presentation",
" slides",
" slide deck",
" presentation tools",
" html presentations",
" automation",
" package manager",
" documentation",
" theming",
" templating",
" python",
" markdown",
" web development",
" javascript",
" build system"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "66c3073c235aa47d3838e12253ce7c72063d2eff7b4d7654482101a849d03c96",
"md5": "6ea3cb09ff43cd1a4e94d5c5b5709488",
"sha256": "715b2296c64774fe17f1eedc904ae06426d857f5dd11726a33d1ab9aa131d54c"
},
"downloads": -1,
"filename": "revealpack-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6ea3cb09ff43cd1a4e94d5c5b5709488",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 39226,
"upload_time": "2025-07-11T16:47:24",
"upload_time_iso_8601": "2025-07-11T16:47:24.267073Z",
"url": "https://files.pythonhosted.org/packages/66/c3/073c235aa47d3838e12253ce7c72063d2eff7b4d7654482101a849d03c96/revealpack-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "12181f164f34f0d526b2149c41e10b0bad288b79449697823b3fb7bf63c56cba",
"md5": "f34b879ef3a51dadde612bef586c6492",
"sha256": "9c3e7d6fe6028b6a1ee766066749b25f994a38427db84599b983d3b8949eb0cc"
},
"downloads": -1,
"filename": "revealpack-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "f34b879ef3a51dadde612bef586c6492",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 36310,
"upload_time": "2025-07-11T16:47:25",
"upload_time_iso_8601": "2025-07-11T16:47:25.508975Z",
"url": "https://files.pythonhosted.org/packages/12/18/1f164f34f0d526b2149c41e10b0bad288b79449697823b3fb7bf63c56cba/revealpack-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 16:47:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Khlick",
"github_project": "RevealPack",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": []
},
{
"name": "beautifulsoup4",
"specs": []
},
{
"name": "jinja2",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "watchdog",
"specs": []
},
{
"name": "flask",
"specs": []
},
{
"name": "mkdocs",
"specs": []
},
{
"name": "mkdocs-material",
"specs": []
},
{
"name": "build",
"specs": []
},
{
"name": "twine",
"specs": []
},
{
"name": "mike",
"specs": []
}
],
"lcname": "revealpack"
}
JSON
