Add subsection support across exporters

CHANGELOG.md

@@ -10,9 +10,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 (unreleased)=
 ## [Unreleased](https://github.com/jeertmans/manim-slides/compare/v5.5.2...HEAD)
 
+(unreleased-added)=
+### Added
+
+- Introduced `Slide.next_subsection()` to record intra-slide checkpoints. New
+  presenter/convert flags (`--subsections`, `--html-subsections`,
+  `--pdf-subsections`, and `--pptx-subsections`) allow the Qt/HTML presenters,
+  PDF exporter, and PowerPoint converter to pause at those subsections or split
+  slides when explicitly requested.
+
 (unreleased-changed)=
 ### Changed
 
+- Changed defaults for subsection handling to make subsections work automatically:
+  - Qt presenter: `--subsections` changed from `off` to `pause`
+  - HTML/RevealJS: `--html-subsections` changed from `disabled` to `pause`
+  - PDF/PowerPoint: unified into single `--subsections` flag (default: `all`)
+- Unified subsection handling across formats:
+  - Removed separate `--pdf-subsections` and `--pptx-subsections` flags
+  - Single `--subsections` flag now controls both PDF and PowerPoint exports
+  - Simplified modes to `none` and `all` (removed `final` and `split` as redundant)
+  - Consistent terminology across all export formats
+- PowerPoint exports temporarily force `--subsections=none` and emit a warning when
+  `--subsections=all` is requested, since per-subsection slide splitting is not yet
+  implemented for PPTX.
+- Qt presenter now freezes the last rendered frame when slides or subsections end
+  to avoid flashing to black between steps.
+- Documented the RevealJS limitation where rewinding subsections replays their
+  clip instead of showing the final accumulated state immediately.
 - Sort the scenes alphabetically when listing scenes
   (e.g., when prompting for scenes with `manim-slides present`).
   [@msaadsbr](https://github.com/msaadsbr) [#573](https://github.com/jeertmans/manim-slides/pull/573)

README.md

@@ -61,7 +61,11 @@ The documentation is available [online](https://eertmans.be/manim-slides/).
 
 Call `self.next_slide()` every time you want to create a pause between
 animations, and `self.next_slide(loop=True)` if you want the next slide to loop
-over animations until the user presses continue:
+over animations until the user presses continue.
+Use `self.next_subsection()` when you need multiple presenter-controlled pause
+points inside a single slide (similar to Beamer overlays). Subsections
+automatically work in the Qt/HTML presenters and can be exported to PDF or
+PowerPoint with additional flags:
 
 ```python
 from manim import *  # or: from manimlib import *

docs/source/reference/api.md

@@ -15,6 +15,7 @@ use, not the methods used internally when rendering.
         canvas,
         canvas_mobjects,
         mobjects_without_canvas,
+        next_subsection,
         next_section,
         next_slide,
         remove_from_canvas,

docs/source/reference/examples.md

@@ -156,6 +156,41 @@ directly write the `construct` method in the body of `MovingCameraSlide`.
             self.wait()
 ```
 
+## Subsection Example
+
+Example demonstrating the use of subsections within a single slide.
+
+**Key concept**: `next_subsection()` keeps building on existing content (accumulates),
+while `next_slide()` starts fresh (clears the screen). This example shows a diagram
+being built step by step, with each subsection adding more elements while keeping
+everything from previous subsections visible.
+
+```{eval-rst}
+.. manim-slides:: ../../../example.py:SubsectionExample
+    :hide_source:
+    :quality: high
+
+.. literalinclude:: ../../../example.py
+   :language: python
+   :linenos:
+   :pyobject: SubsectionExample
+```
+
+This example creates **two slides**:
+- **Slide 1**: Title slide showing "Subsections Demo"
+- **Slide 2**: Starts with title and subtitle, then has **four subsections** that build the diagram:
+  1. Subsection "Add circle": adds a circle
+  2. Subsection "Add square": adds a square (circle still visible)
+  3. Subsection "Add labels": adds labels (circle and square still visible)
+  4. Subsection "Add arrows": adds an arrow connecting them (everything still visible)
+
+The key point: the subtitle appears **before** the first subsection, so it's part of the
+base slide content. Each subsection then adds more elements while keeping all previous
+content visible.
+
+Note that `auto_next=True` on the third subsection will automatically advance
+to the fourth subsection after animations complete.
+
 ## Advanced Example
 
 A more advanced example is `ConvertExample`, which is used as demo slide and tutorial.

docs/source/reference/sharing.md

@@ -14,12 +14,40 @@ In the next sections, we will assume your animations are described
 in `example.py`, and you have one presentation called `BasicExample`.
 :::
 
+## Understanding Subsections
+
+Before sharing slides, it's important to understand **subsections**. Subsections
+allow multiple pause points within a single slide, useful for step-by-step reveals:
+
+- `next_subsection()`: **Accumulates** content (keeps building on what's there)
+- `next_slide()`: **Clears** content (starts fresh)
+
+All presentation modes support subsections with the `--subsections` flag:
+
+- `--subsections=all` (default): Enable subsections (pause at each subsection/create separate pages)
+- `--subsections=none`: Ignore subsections (play through/show final state only)
+
 ## With Manim Slides installed on the target machine
 
 If Manim Slides, Manim (or ManimGL), and their dependencies are installed, then
 using `manim-slides present` allows for the best presentations, with the most
 options available.
 
+### Controlling Subsection Behavior
+
+When presenting with the Qt GUI, you can control how subsections behave:
+
+```bash
+# Default: pause at each subsection, press key to advance
+manim-slides present BasicExample
+
+# Explicit (same as default)
+manim-slides present BasicExample --subsections=all
+
+# Play through entire slide without pausing at subsections
+manim-slides present BasicExample --subsections=none
+```
+
 ### Sharing your Python file(s)
 
 The lightest way to share your presentation is with the Python files that
@@ -85,9 +113,18 @@ First, you need to create the HTML file and its assets directory.
 Example:
 
 ```bash
+# Default: subsections create pause points (press arrow keys to advance)
 manim-slides convert BasicExample basic_example.html
+
+# Without subsections: play through entire slide
+manim-slides convert BasicExample basic_example.html --subsections=none
 ```
 
+**Limitation:** When you skim backwards through subsections in HTML/RevealJS,
+each subsection clip restarts from its beginning. Unlike the Qt presenter, the
+final accumulated state is not frozen when rewinding, so expect a short replay
+when stepping back.
+
 Then, you need to copy the HTML files and its assets directory to target location,
 while keeping the relative path between the HTML and the assets the same. The
 easiest solution is to compress both the file and the directory into one ZIP,
@@ -172,17 +209,26 @@ A convenient conversion feature is to the PowerPoint format, thanks to the
 it is still considered in an *EXPERIMENTAL* status because we do not
 exactly know what versions of PowerPoint (or LibreOffice Impress) are supported.
 
-Basically, you can create a PowerPoint in a single command:
+You can create a PowerPoint in a single command:
 
 ```bash
+# PowerPoint currently exports one slide per manim slide (subsections disabled)
 manim-slides convert --to=pptx BasicExample basic_example.pptx
+
+# Explicitly silence the warning by disabling subsections yourself
+manim-slides convert --to=pptx BasicExample basic_example.pptx --subsections=none
 ```
 
 All the videos and necessary files will be contained inside the `.pptx` file, so
 you can safely share it with anyone. By default, the `poster_frame_image`, i.e.,
 what is displayed by PowerPoint when the video is not playing, is the first
 frame of each slide. This allows for smooth transitions.
 
+**Subsection handling:** PowerPoint export currently forces `--subsections=none`.
+Passing `--subsections=all` logs a warning and behaves the same. The HTML/RevealJS
+and PDF exporters still honor `--subsections=all`, so use those formats when you
+need to step through subsections.
+
 In the future, we hope to provide more features to this format,
 so feel free to suggest new features too!
 
@@ -192,10 +238,18 @@ If you ever need backup slides, that are only made of PDF pages
 with static images, you can generate such a PDF with the following command:
 
 ```bash
+# Default: subsections become separate PDF pages
 manim-slides convert --to=pdf BasicExample basic_example.pdf
+
+# Without subsections: one page per manim slide, final state only
+manim-slides convert --to=pdf BasicExample basic_example.pdf --subsections=none
 ```
 
 Note that you will lose all the benefits from animated slides. Therefore,
-this is only recommended to be used as a backup plan. By default, the last frame
-of each slide will be printed. This can be changed to be the first one with
-`-cframe_index=first`.
+this is only recommended to be used as a backup plan.
+
+**Subsection handling:** By default (`--subsections=all`), each subsection becomes
+a separate PDF page, showing the progressive build-up. Use `--subsections=none`
+to create one page per manim slide showing only the final state. The frame index
+option (`-cframe_index=first` or `last`) controls which frame is captured when
+subsections are not used.

example.py

@@ -224,6 +224,52 @@ def construct(self):
         self.play(Transform(square, learn_more_text))
 
 
+class SubsectionExample(Slide):
+    def construct(self):
+        title = Text("Subsections Demo", color=YELLOW)
+        self.play(Write(title))
+        self.next_slide()
+
+        self.clear()
+        title = Text("Building a Diagram", font_size=36, color=YELLOW).to_edge(UP)
+        self.play(Write(title))
+        self.next_subsection(name="Show title")
+
+        circle = Circle(radius=1, color=BLUE).shift(LEFT * 2)
+        self.play(Create(circle))
+        self.next_subsection(name="Add circle")
+
+        square = Square(side_length=2, color=RED).shift(RIGHT * 2)
+        self.play(Create(square))
+        self.next_subsection(name="Add square")
+
+        circle_label = Text("Circle", font_size=20).next_to(circle, DOWN)
+        square_label = Text("Square", font_size=20).next_to(square, DOWN)
+        self.play(Write(circle_label), Write(square_label))
+        self.next_subsection(name="Add labels", auto_next=True)
+
+        arrow = Arrow(circle.get_right(), square.get_left(), buff=0.1, color=GREEN)
+        arrow_label = Text("Connection", font_size=16).next_to(arrow, UP)
+        self.play(Create(arrow), Write(arrow_label))
+        self.next_slide()
+
+        self.clear()
+        title = Text("Transformations", font_size=36, color=YELLOW).to_edge(UP)
+        self.play(Write(title))
+        self.next_subsection(name="Show title")
+
+        dot = Dot(color=ORANGE).shift(DOWN)
+        self.play(FadeIn(dot))
+        self.next_subsection(name="Add dot")
+
+        triangle = Triangle(color=PURPLE).shift(UP)
+        self.play(Create(triangle))
+        self.next_subsection(name="Add triangle")
+
+        self.play(dot.animate.move_to(triangle.get_center()))
+        self.next_slide()
+
+
 # For ThreeDExample, things are different
 
 if not MANIMGL:

manim_slides/config.py

@@ -1,5 +1,6 @@
 import json
 import shutil
+from collections.abc import Sequence
 from functools import wraps
 from inspect import Parameter, signature
 from pathlib import Path
@@ -11,6 +12,7 @@
     BaseModel,
     Field,
     FilePath,
+    NonNegativeInt,
     PositiveInt,
     PrivateAttr,
     conset,
@@ -151,6 +153,40 @@ def merge_with(self, other: "Config") -> "Config":
         return self
 
 
+class SubsectionMarker(BaseModel):  # type: ignore[misc]
+    """User-authored subsection boundary recorded before rendering."""
+
+    animation_index: NonNegativeInt
+    name: str = ""
+    auto_next: bool = False
+
+
+class SubsectionConfig(BaseModel):  # type: ignore[misc]
+    """Fully resolved subsection configuration stored after rendering."""
+
+    name: str = ""
+    auto_next: bool = False
+    start_animation: NonNegativeInt
+    end_animation: NonNegativeInt
+    start_time: float = Field(0.0, ge=0.0)
+    end_time: float = Field(0.0, ge=0.0)
+    file: Optional[FilePath] = Field(
+        None,
+        description="Path to the partial animation file for this subsection. "
+        "Only set when subsection contains exactly one animation.",
+    )
+
+    @model_validator(mode="after")
+    def animations_are_monotone(self) -> "SubsectionConfig":
+        if self.end_animation < self.start_animation:
+            raise ValueError(
+                "end_animation must be greater or equal to start_animation"
+            )
+        if self.end_time < self.start_time:
+            raise ValueError("end_time must be greater or equal to start_time")
+        return self
+
+
 class BaseSlideConfig(BaseModel):  # type: ignore
     """Base class for slide config."""
 
@@ -220,17 +256,21 @@ class PreSlideConfig(BaseSlideConfig):
 
     start_animation: int
     end_animation: int
+    subsection_markers: tuple[SubsectionMarker, ...] = Field(default_factory=tuple)
 
     @classmethod
     def from_base_slide_config_and_animation_indices(
         cls,
         base_slide_config: BaseSlideConfig,
         start_animation: int,
         end_animation: int,
+        *,
+        subsection_markers: Sequence[SubsectionMarker] = (),
     ) -> "PreSlideConfig":
         return cls(
             start_animation=start_animation,
             end_animation=end_animation,
+            subsection_markers=tuple(subsection_markers),
             **base_slide_config.model_dump(),
         )
 
@@ -280,12 +320,23 @@ class SlideConfig(BaseSlideConfig):
 
     file: FilePath
     rev_file: FilePath
+    subsections: tuple[SubsectionConfig, ...] = Field(default_factory=tuple)
 
     @classmethod
     def from_pre_slide_config_and_files(
-        cls, pre_slide_config: PreSlideConfig, file: Path, rev_file: Path
+        cls,
+        pre_slide_config: PreSlideConfig,
+        file: Path,
+        rev_file: Path,
+        *,
+        subsections: Sequence[SubsectionConfig] = (),
     ) -> "SlideConfig":
-        return cls(file=file, rev_file=rev_file, **pre_slide_config.model_dump())
+        return cls(
+            file=file,
+            rev_file=rev_file,
+            subsections=tuple(subsections),
+            **pre_slide_config.model_dump(exclude={"subsection_markers"}),
+        )
 
 
 class PresentationConfig(BaseModel):  # type: ignore[misc]