presently 0.26.0 → 0.26.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57754e7cc66ec20e3ef797b20afbe147fda8979e96aafc14cdb9c35eaedb5495
-  data.tar.gz: 242278bc2177efc35609ece981bb3f6cb5fed099e628894d6c8ed9dcf77ce020
+  metadata.gz: fc69b4f81a2143dbbccc8d591c1fb675bb447057b77ffde4420f1ad1d7b3819a
+  data.tar.gz: b49c223f245c7949d72d8510d41d59f3e43efd6eb33b22bfe931bc84c0e1473d
 SHA512:
-  metadata.gz: 206d33b334f6d1ed9f4b7df2b328022bb5b332a43a53932840be6bd5c00a5b1a41d8df262b441309d04a17d0fc74bdf6120449f4ff1ec0f84228385856d3df9e
-  data.tar.gz: 42f72ece55c0c02160fd12b90006651f0cd3cb1d2b4a95fa12516dbc1d88172652d76afd5639a3ff7c7b8edd6e57eb7d7ba6fb6a6303a90109bcff005aefdb2a
+  metadata.gz: '00686d6b384cdbbd81b27cc96e33e5301222c4b14a54c18f9221c2795f2b1eb0175ca4fbfc8caf10c3f2bb463df7ea85ba169b76b9b9e7c75049b419663b8be6'
+  data.tar.gz: d5348d5212bdde155fd4dcd7ea284606ff893716144fa8b04f202f3c18f0f18688431fe7ca59320c32c521baab047419b80170e31950fc57fe9dbcbaa545f95f

data/context/getting-started.md

@@ -188,173 +188,9 @@ The defaults are 1920×1080 at up to 30 frames per second. The exporter starts a
 
 ## Templates
 
-Templates define the visual layout of each slide. Select a template using the `template` field in the frontmatter.
+Templates define the visual layout of each slide. Select one with the `template` field in the frontmatter; slides without it use `default`. Common choices include `title` for an opening slide, `two_column` for comparisons, and `code` for code walkthroughs.
 
-### Default
-
-A general-purpose content slide. An H1 becomes the slide title and the remaining document becomes its body.
-
-``` markdown
----
-template: default
-duration: 60
----
-
-# Key points
-
-- First point
-- Second point
-- Third point
-```
-
-### Title
-
-A large title with a short body, centered on the slide.
-
-``` markdown
----
-template: title
-duration: 30
----
-
-# My Presentation Title
-
-A subtitle or tagline
-```
-
-### Section
-
-A section divider slide with a large heading, optional supporting body, and accent background.
-
-``` markdown
----
-template: section
-duration: 15
----
-
-# Part Two
-
-Architecture and design
-```
-
-### Two Column
-
-A side-by-side layout with `left` and `right` sections.
-
-``` markdown
----
-template: two_column
-duration: 90
----
-
-# Client and server responsibilities
-
-The application is split across two cooperating environments.
-
-## Left
-
-**Server Side**
-
-- Ruby + Lively
-- WebSocket connections
-
-## Right
-
-**Client Side**
-
-- Live DOM updates
-- CSS animations
-```
-
-### Code
-
-A syntax-highlighted code slide with optional focus regions for code walkthroughs. Use the `focus` frontmatter to specify which lines to highlight (1-based). Lines outside the focus range are dimmed, and the code scrolls to center the focused region.
-
-``` markdown
----
-template: code
-duration: 60
-focus: 2-8
----
-
-# Constructor
-
-```ruby
-class Presentation
-  def initialize
-    @slides = []
-    @current_index = 0
-  end
-
-  def advance!
-    @current_index += 1
-  end
-end
-​```
-```
-
-Create animated walkthroughs by using multiple slides with the same code but different `focus` ranges. The transition between them smoothly scrolls and shifts the dim overlays.
-
-### Statement
-
-A prominent statement or quote, centered on the slide. Supports an optional `## Translation` placeholder.
-
-``` markdown
----
-template: statement
-duration: 30
----
-
-The best way to predict the future is to create it.
-
-## Translation
-
-未来を予測する最善の方法は、それを創ることである。
-```
-
-### Translations
-
-Templates can extract an optional `## Translation` section and position it independently from the main document. Every standard template displays it separately in a lighter style.
-
-### Image
-
-A centered image with an optional caption.
-
-``` markdown
----
-template: image
-duration: 30
----
-
-![Architecture diagram](/images/architecture.png)
-
-## Caption
-
-System architecture overview
-```
-
-### Diagram
-
-A centered canvas for diagrams and other custom visual layouts, with an optional title. A single grid or flex container is usually enough to create a diagram that remains centered as the slide scales:
-
-``` markdown
----
-template: diagram
-duration: 60
----
-
-# Request lifecycle
-
-<div style="display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 2em; width: 80%;">
-  <div>Browser</div>
-  <div>→</div>
-  <div>Server</div>
-</div>
-```
-
-For coordinate-based layouts, wrap the elements in `<div class="diagram-freeform">`. The wrapper fills the canvas and absolutely positions each direct child.
-
-All other templates also support absolutely positioned overlays since the slide container is `position: relative`. This lets you add callouts, badges, or annotations on top of any template's normal content.
+See the [Templates guide](../templates/index) for built-in layouts, examples, translations, and custom templates.
 
 ## Transitions
 
@@ -400,35 +236,37 @@ The presenter view at `/presenter` provides:
 - **Progress bar** — visual indicator of time consumed for the current slide.
 - **Reload button** — reload slides from disk without restarting the server.
 
-## Custom Templates
+### Starting the Timer from a Title Slide
 
-You can provide your own `.xrb` template files by configuring the templates root:
+A title slide can stay on screen while the audience settles. Add `timer: start` to its frontmatter to start the presentation timer when you advance to the next slide:
 
-``` ruby
-# In your environment configuration:
-service "presently" do
-  include Presently::Environment::Application
+``` markdown
+---
+template: title
+duration: 0
+timer: start
+---
 
-  def templates_root
-    File.expand_path("templates", self.root)
-  end
-end
-```
+# My Presentation
 
-Templates receive a {ruby Presently::TemplateScope}. `self.slide_header` renders the semantic H1 title and optional section metadata, while `self.document` renders the remaining slide body. `self.extract(name)` removes an H2 placeholder with that exact heading text from the body and returns its rendered content. Extract placeholders before rendering the remaining document:
-
-``` xrb
-<?r translation = self.extract("Translation") ?>
-#{self.slide_header}
-<div class="slide-body">
-	#{self.document}
-</div>
-<?r if translation ?>
-	<div class="slide-translation">#{translation}</div>
-<?r end ?>
+We'll begin shortly.
 ```
 
-Extraction stops at the next heading of the same or a higher level, so lower-level headings remain inside the extracted fragment. Placeholder names are case-sensitive and must match the heading text exactly. Only placeholders requested by the template are removed; other headings remain ordinary document content.
+The timer stays stopped while the title is displayed. Advancing from it in `/presenter` or `/display` starts the timer before showing the next slide. Setting `duration: 0` excludes the waiting slide from the expected presentation duration and pacing calculations. The `title` template itself does not control the timer.
+
+Durations are read as floating-point seconds, including numeric strings. Negative, invalid, or non-finite values are treated as `0.0`. An unspecified or null duration defaults to `0.0` seconds, meaning no time has been allocated to that slide. Set explicit durations, or apply recorded narration durations, to establish a pacing schedule. When the total allocated duration is zero, the presenter shows elapsed time without pacing indicators, a progress bar, or a remaining-time estimate.
+
+The `timer` field supports these actions:
+
+| Value | Effect when advancing from this slide |
+|---|---|
+| `start` | Starts the timer only if it has never started. Revisiting the slide does not reset elapsed time or resume a manually paused timer. |
+| `pause` | Pauses the timer, preserving elapsed time. Has no effect before the timer starts. |
+| `resume` | Resumes a started timer, preserving elapsed time. Has no effect before the timer starts or while it is already running. |
+
+For a break, put `timer: pause` on the slide immediately before the break slide, and `timer: resume` on the break slide itself. Give the break slide `duration: 0` to exclude the break from pacing calculations. Advancing into the break pauses timing; advancing out resumes it.
+
+Timer actions run only when **Next** successfully moves to another slide. Going backwards, jumping directly to a slide, reloading, reconnecting, and restoring saved state do not trigger them. Neither does navigation in `/record`, or recorded playback. Slides without a recognized timer action leave the timer unchanged; the manual timer controls remain available.
 
 ## Customizing the Application
 
@@ -438,8 +276,8 @@ For advanced customization, create an `application.rb` and run with `presently a
 #!/usr/bin/env presently
 
 class Application < Presently::Application
-  def title
-    "My Conference Talk"
-  end
+	def title
+		"My Conference Talk"
+	end
 end
 ```

data/context/index.yaml

@@ -10,6 +10,10 @@ files:
   title: Getting Started
   description: This guide explains how to use `presently` to create and deliver web-based
     presentations using Markdown slides.
+- path: templates.md
+  title: Templates
+  description: This guide explains how to choose slide templates and create custom
+    layouts in Presently.
 - path: animating-slides.md
   title: Animating Slides
   description: This guide explains how to animate content within slides using the

data/context/templates.md

@@ -0,0 +1,207 @@
+# Templates
+
+This guide explains how to choose slide templates and create custom layouts in Presently.
+
+## Built-in Templates
+
+Templates define the visual layout of each slide. Select a template using the `template` field in the frontmatter.
+
+### Default
+
+A general-purpose content slide. An H1 becomes the slide title and the remaining document becomes its body.
+
+``` markdown
+---
+template: default
+duration: 60
+---
+
+# Key points
+
+- First point
+- Second point
+- Third point
+```
+
+### Title
+
+A large title with a short body, centered on the slide.
+
+``` markdown
+---
+template: title
+duration: 30
+---
+
+# My Presentation Title
+
+A subtitle or tagline
+```
+
+### Section
+
+A section divider slide with a large heading, optional supporting body, and accent background.
+
+``` markdown
+---
+template: section
+duration: 15
+---
+
+# Part Two
+
+Architecture and design
+```
+
+### Two Column
+
+A side-by-side layout with `left` and `right` sections.
+
+``` markdown
+---
+template: two_column
+duration: 90
+---
+
+# Client and server responsibilities
+
+The application is split across two cooperating environments.
+
+## Left
+
+**Server Side**
+
+- Ruby + Lively
+- WebSocket connections
+
+## Right
+
+**Client Side**
+
+- Live DOM updates
+- CSS animations
+```
+
+### Code
+
+A syntax-highlighted code slide with optional focus regions for code walkthroughs. Use the `focus` frontmatter to specify which lines to highlight (1-based). Lines outside the focus range are dimmed, and the code scrolls to center the focused region.
+
+```` markdown
+---
+template: code
+duration: 60
+focus: 2-8
+---
+
+# Constructor
+
+```ruby
+class Presentation
+  def initialize
+    @slides = []
+    @current_index = 0
+  end
+
+  def advance!
+    @current_index += 1
+  end
+end
+```
+````
+
+Create animated walkthroughs by using multiple slides with the same code but different `focus` ranges. The transition between them smoothly scrolls and shifts the dim overlays.
+
+### Statement
+
+A prominent statement or quote, centered on the slide. Supports an optional `## Translation` placeholder.
+
+``` markdown
+---
+template: statement
+duration: 30
+---
+
+The best way to predict the future is to create it.
+
+## Translation
+
+未来を予測する最善の方法は、それを創ることである。
+```
+
+### Image
+
+A centered image with an optional caption.
+
+``` markdown
+---
+template: image
+duration: 30
+---
+
+![Architecture diagram](/images/architecture.png)
+
+## Caption
+
+System architecture overview
+```
+
+### Diagram
+
+A centered canvas for diagrams and other custom visual layouts, with an optional title. A single grid or flex container is usually enough to create a diagram that remains centered as the slide scales:
+
+``` markdown
+---
+template: diagram
+duration: 60
+---
+
+# Request lifecycle
+
+<div style="display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 2em; width: 80%;">
+  <div>Browser</div>
+  <div>→</div>
+  <div>Server</div>
+</div>
+```
+
+For coordinate-based layouts, wrap the elements in `<div class="diagram-freeform">`. The wrapper fills the canvas and absolutely positions each direct child.
+
+All other templates also support absolutely positioned overlays since the slide container is `position: relative`. This lets you add callouts, badges, or annotations on top of any template's normal content.
+
+## Translations
+
+Templates can extract an optional `## Translation` section and position it independently from the main document. Every standard template displays it separately in a lighter style.
+
+## Custom Templates
+
+For layouts specific to your presentation, put `.xrb` files in a `templates/` directory alongside `slides/`. Presently searches this directory before its bundled templates, so you can add new layouts or override individual built-in templates.
+
+To search additional directories, configure `templates_roots`, which returns an ordered array of paths:
+
+``` ruby
+# In your environment configuration:
+service "presently" do
+	include Presently::Environment::Application
+	
+	def templates_roots
+		[File.expand_path("shared-templates", self.root)] + super
+	end
+end
+```
+
+For example, save the following template as `templates/custom.xrb` and select it with `template: custom` in a slide's frontmatter.
+
+Templates receive a {ruby Presently::TemplateScope}. `self.slide_header` renders the semantic H1 title and optional section metadata, while `self.document` renders the remaining slide body. `self.extract(name)` removes an H2 placeholder with that exact heading text from the body and returns its rendered content. Extract placeholders before rendering the remaining document:
+
+``` xrb
+<?r translation = self.extract("Translation") ?>
+#{self.slide_header}
+<div class="slide-body">
+	#{self.document}
+</div>
+<?r if translation ?>
+	<div class="slide-translation">#{translation}</div>
+<?r end ?>
+```
+
+Extraction stops at the next heading of the same or a higher level, so lower-level headings remain inside the extracted fragment. Placeholder names are case-sensitive and must match the heading text exactly. Only placeholders requested by the template are removed; other headings remain ordinary document content.

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.26.0"
+	VERSION = "0.26.1"
 end

data/readme.md

@@ -26,6 +26,8 @@ Please see the [project documentation](https://socketry.github.io/presently/) fo
 
   - [Getting Started](https://socketry.github.io/presently/guides/getting-started/index) - This guide explains how to use `presently` to create and deliver web-based presentations using Markdown slides.
 
+  - [Templates](https://socketry.github.io/presently/guides/templates/index) - This guide explains how to choose slide templates and create custom layouts in Presently.
+
   - [Animating Slides](https://socketry.github.io/presently/guides/animating-slides/index) - This guide explains how to animate content within slides using the slide scripting system.
 
   - [Animated Diagrams](https://socketry.github.io/presently/guides/animated-diagrams/index) - This guide explains how to design responsive, lifecycle-safe animated diagrams in Presently using semantic markup, slide-specific CSS, and Anime.js choreography.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.26.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -122,6 +122,7 @@ files:
 - context/animating-slides.md
 - context/getting-started.md
 - context/index.yaml
+- context/templates.md
 - lib/presently.rb
 - lib/presently/application.rb
 - lib/presently/clock.rb

metadata.gz.sig

@@ -1,2 +1,3 @@
-[�����h���A�F�N=��"UO�yV��7�7�	�DC�^�$�:�pn~�m�3@��I�1M�o4l�j�-<	"f�7��WT&�u?k��B�{���*z�~�A�
-���s�x���_:��u����x-��j�'-���/�u��r˃+��C/�9�H>������MxW�F���P�
+2���$ZD����?bD�l��*��!(M�c�~�%��`|��&M
+@R�(K������}�
�X�\Ϯ,-sϺ{%����'ߊ�^���$����N��`�/�X���!=�hkݯ�HZ
+^��#�<�h�h��A|��oe��G�B�ݕY��}s��+1z6����	�L�5�)̄�����5�t���X7��|ӳDi]>Y�w�aަ���qf-�X+h��@�FĜb<��V�6Ӟ�]�����t����I�d��R�	ݛ���>�!y�/�|��$N�&ҫ:�