`. 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
@@ -432,36 +268,6 @@ For a break, put `timer: pause` on the slide immediately before the break slide,
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.
-## Custom Templates
-
-You can provide your own `.xrb` template files by configuring the templates root:
-
-``` ruby
-# In your environment configuration:
-service "presently" do
- include Presently::Environment::Application
-
- def templates_root
- File.expand_path("templates", self.root)
- end
-end
-```
-
-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
-
-#{self.slide_header}
-
- #{self.document}
-
-
-
#{translation}
-
-```
-
-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.
-
## Customizing the Application
For advanced customization, create an `application.rb` and run with `presently application.rb`:
@@ -470,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
```
diff --git a/context/index.yaml b/context/index.yaml
index e714d2f..0359d13 100644
--- a/context/index.yaml
+++ b/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
diff --git a/context/templates.md b/context/templates.md
new file mode 100644
index 0000000..2d66d73
--- /dev/null
+++ b/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
+---
+
+
+
+## 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
+
+
+```
+
+For coordinate-based layouts, wrap the elements in `
`. 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
+
+#{self.slide_header}
+
+ #{self.document}
+
+
+
#{translation}
+
+```
+
+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.
diff --git a/guides/getting-started/readme.md b/guides/getting-started/readme.md
index a17fef8..612741c 100644
--- a/guides/getting-started/readme.md
+++ b/guides/getting-started/readme.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
----
-
-
-
-## 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
-
-
-```
-
-For coordinate-based layouts, wrap the elements in `
`. 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
@@ -432,36 +268,6 @@ For a break, put `timer: pause` on the slide immediately before the break slide,
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.
-## Custom Templates
-
-You can provide your own `.xrb` template files by configuring the templates root:
-
-``` ruby
-# In your environment configuration:
-service "presently" do
- include Presently::Environment::Application
-
- def templates_root
- File.expand_path("templates", self.root)
- end
-end
-```
-
-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
-
-#{self.slide_header}
-
- #{self.document}
-
-
-
#{translation}
-
-```
-
-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.
-
## Customizing the Application
For advanced customization, create an `application.rb` and run with `presently application.rb`:
@@ -470,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
```
diff --git a/guides/links.yaml b/guides/links.yaml
index 3897370..1da5328 100644
--- a/guides/links.yaml
+++ b/guides/links.yaml
@@ -1,6 +1,8 @@
getting-started:
order: 1
-animating-slides:
+templates:
order: 2
-animated-diagrams:
+animating-slides:
order: 3
+animated-diagrams:
+ order: 4
diff --git a/guides/templates/readme.md b/guides/templates/readme.md
new file mode 100644
index 0000000..2d66d73
--- /dev/null
+++ b/guides/templates/readme.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
+---
+
+
+
+## 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
+
+
+```
+
+For coordinate-based layouts, wrap the elements in `