presently 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33cd4ebb1d6177f7409fbe3057946c3129d4e0017ba5fba671738bd3f1c2e85d
-  data.tar.gz: 6d38e77b81eb7d9acce56a49b83478f276c938fc901b47cd0a4afe56b7c0fe6e
+  metadata.gz: 9d60b3fb59bbf07f0fdd4f3e1756998485049e2b55dc56225160e160af02346e
+  data.tar.gz: 4837aa9c8574f3b759a3199db53ad263d323df5cd6239df7292e8535ad83702c
 SHA512:
-  metadata.gz: 76b50edaff01e665b361ed0f21730c2d049224a08971b965288253c8383bcfbd997edec1670daa4b4991ab073e9db4a08fc056a04c5cf1c48b57510f03aa9fed
-  data.tar.gz: 472b3b21ba096b15675c98d4b53093ab49cf8fd508a5eceb90e5aa739c3de29b8ee39231a0bf4b88411df468780b6039004f2086c7ee96845ef300f7d04c0bd6
+  metadata.gz: b597972eabe2fec25758be28d3630db39756e93e7e2c24c43cfcdbaca3385741c1306748ada054cc7ea9d8bdbe9ba91f05217453cd5bfca3a1be5c2cc885b8d9
+  data.tar.gz: 122236fe265570f0be41163f662376b55df718d28ee52eada7e796c415ea52edd0f8f225649e1b9438d457cbb9281c2d06674274a80a33d6ec7b12ef304bed80

data/bake/presently/rehearse.rb

@@ -82,7 +82,7 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 	offset = prior_records.length
 	slides.each_with_index do |slide, index|
 		relative_path = slide.path
-		headline = extract_headline(slide)
+		headline = slide.title
 		absolute = offset + index + 1
 		total = offset + slides.length
 		
@@ -199,14 +199,6 @@ private
 
 UPDATE_THRESHOLD = 1.0
 
-def extract_headline(slide)
-	body = slide.content["body"]
-	return slide.title unless body && !body.empty?
-	
-	first_line = body.to_commonmark.strip.lines.first.to_s.strip
-	first_line.empty? ? slide.title : first_line
-end
-
 def print_report(records, log_path)
 	planned_total = records.sum{|record| record[:planned]}
 	actual_total = records.sum{|record| record[:actual]}

data/context/getting-started.md

@@ -60,11 +60,7 @@ template: title
 duration: 30
 ---
 
-# Title
-
-Welcome to My Talk
-
-# Subtitle
+# Welcome to My Talk
 
 A presentation built with Presently
 
@@ -76,7 +72,7 @@ These are presenter notes — only visible in the presenter view.
 Each slide has three parts:
 
 1. **YAML frontmatter** between `---` markers at the top, specifying the template, duration, and other metadata.
-2. **Content** with Markdown headings that become named sections for the template.
+2. **Content** with an optional H1 title and any template placeholders written as H2 sections.
 3. **Presenter notes** after a `---` separator in the body (optional).
 
 ### Styling Slides
@@ -196,7 +192,7 @@ Templates define the visual layout of each slide. Select a template using the `t
 
 ### Default
 
-A general-purpose content slide. All content without a heading goes into the `body` section.
+A general-purpose content slide. An H1 becomes the slide title and the remaining document becomes its body.
 
 ``` markdown
 ---
@@ -204,6 +200,8 @@ template: default
 duration: 60
 ---
 
+# Key points
+
 - First point
 - Second point
 - Third point
@@ -211,7 +209,7 @@ duration: 60
 
 ### Title
 
-A large title with a subtitle, centered on the slide.
+A large title with a short body, centered on the slide.
 
 ``` markdown
 ---
@@ -219,18 +217,14 @@ template: title
 duration: 30
 ---
 
-# Title
-
-My Presentation Title
-
-# Subtitle
+# My Presentation Title
 
 A subtitle or tagline
 ```
 
 ### Section
 
-A section divider slide with a large heading and accent background.
+A section divider slide with a large heading, optional supporting body, and accent background.
 
 ``` markdown
 ---
@@ -238,9 +232,9 @@ template: section
 duration: 15
 ---
 
-# Heading
+# Part Two
 
-Part Two
+Architecture and design
 ```
 
 ### Two Column
@@ -253,14 +247,18 @@ template: two_column
 duration: 90
 ---
 
-# Left
+# Client and server responsibilities
+
+The application is split across two cooperating environments.
+
+## Left
 
 **Server Side**
 
 - Ruby + Lively
 - WebSocket connections
 
-# Right
+## Right
 
 **Client Side**
 
@@ -277,9 +275,10 @@ A syntax-highlighted code slide with optional focus regions for code walkthrough
 template: code
 duration: 60
 focus: 2-8
-title: Constructor
 ---
 
+# Constructor
+
 ```ruby
 class Presentation
   def initialize
@@ -298,7 +297,7 @@ Create animated walkthroughs by using multiple slides with the same code but dif
 
 ### Statement
 
-A prominent statement or quote, centered on the slide. Supports an optional `# Translation` section.
+A prominent statement or quote, centered on the slide. Supports an optional `## Translation` placeholder.
 
 ``` markdown
 ---
@@ -308,14 +307,14 @@ duration: 30
 
 The best way to predict the future is to create it.
 
-# Translation
+## Translation
 
 未来を予測する最善の方法は、それを創ることである。
 ```
 
 ### Translations
 
-All templates support an optional `# Translation` section. When present, the translation is displayed below the main content in a lighter style. This works with `title`, `section`, `statement`, and `image` templates.
+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
 
@@ -329,7 +328,7 @@ duration: 30
 
 ![Architecture diagram](/images/architecture.png)
 
-# Caption
+## Caption
 
 System architecture overview
 ```
@@ -344,11 +343,7 @@ template: diagram
 duration: 60
 ---
 
-# Title
-
-Request lifecycle
-
-# Body
+# Request lifecycle
 
 <div style="display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: 2em; width: 80%;">
   <div>Browser</div>
@@ -420,7 +415,20 @@ service "presently" do
 end
 ```
 
-Templates receive a {ruby Presently::TemplateScope} with access to `self.slide` (the {ruby Presently::Slide} instance) and `self.section(name)` for retrieving named content sections.
+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.
 
 ## Customizing the Application
 

data/lib/presently/slide.rb

@@ -14,13 +14,13 @@ require_relative "stylesheet"
 module Presently
 	# A single slide parsed from a Markdown file.
 	#
-	# Each slide has YAML front_matter for metadata (template, duration, focus), content sections
-	# split by Markdown headings, and optional presenter notes separated by `---`.
+	# Each slide has YAML front_matter for metadata (template, duration, focus), a Markdown
+	# document, and optional presenter notes separated by `---`.
 	class Slide
 		# A fragment of a Markly AST document.
 		#
 		# Wraps a `Markly::Node` of type `:document` and provides rendering helpers.
-		# Used for both content sections and presenter notes so callers can choose
+		# Used for both slide documents and presenter notes so callers can choose
 		# their output format without the parser pre-committing to one.
 		class Fragment
 			# Markly extensions enabled for all slide Markdown rendering.
@@ -35,6 +35,13 @@ module Presently
 			# @attribute [Markly::Node] The underlying AST document node.
 			attr :node
 			
+			# Duplicate this fragment and its underlying AST.
+			# @returns [Fragment] An independently mutable copy.
+			def initialize_copy(other)
+				super
+				@node = other.node.dup
+			end
+			
 			# Whether the fragment has no content.
 			# @returns [Boolean]
 			def empty?
@@ -47,6 +54,51 @@ module Presently
 				Markly::Renderer::HTML.new(flags: Markly::UNSAFE, extensions: EXTENSIONS).render(@node)
 			end
 			
+			# Extract the content belonging to a named H2 placeholder.
+			#
+			# The matching heading itself is removed. Following nodes are extracted up
+			# to the next heading of the same or a higher level. Lower-level headings
+			# remain part of the extracted content.
+			# @parameter name [String] The heading name to extract.
+			# @returns [Fragment | Nil] The extracted content, or `nil` when not found.
+			def extract(name)
+				heading = find_heading(name)
+				return unless heading
+				
+				level = heading.header_level
+				fragment = Markly::Node.new(:document)
+				node = heading.next
+				heading.delete
+				
+				while node
+					next_node = node.next
+					break if node.type == :header && node.header_level <= level
+					
+					fragment.append_child(node)
+					node = next_node
+				end
+				
+				Fragment.new(fragment)
+			end
+			
+			# Extract the first heading at the given level, retaining the heading node.
+			# @parameter level [Integer] The Markdown heading level.
+			# @returns [Fragment | Nil] A fragment containing the extracted heading.
+			def extract_heading(level = 1)
+				heading = nil
+				@node.each do |node|
+					if node.type == :header && node.header_level == level
+						heading = node
+						break
+					end
+				end
+				return unless heading
+				
+				fragment = Markly::Node.new(:document)
+				fragment.append_child(heading)
+				Fragment.new(fragment)
+			end
+			
 			# Render the fragment back to CommonMark Markdown.
 			# @returns [String] The CommonMark source.
 			def to_commonmark
@@ -54,6 +106,27 @@ module Presently
 			end
 			
 			alias to_s to_commonmark
+			
+			# Return the plain text of the first heading at the given level.
+			# @parameter level [Integer] The Markdown heading level.
+			# @returns [String | Nil] The heading text, or `nil` when not found.
+			def heading_text(level = 1)
+				@node.each do |node|
+					if node.type == :header && node.header_level == level
+						return node.dup.extract_children.to_plaintext
+					end
+				end
+			end
+			
+			private
+			
+			def find_heading(name)
+				@node.each do |node|
+					return node if node.type == :header && node.header_level == 2 && node.dup.extract_children.to_plaintext == name
+				end
+				
+				nil
+			end
 		end
 		
 		# Parses a Markdown slide file into structured data for {Slide}.
@@ -61,8 +134,17 @@ module Presently
 		# Handles YAML front_matter extraction, presenter note separation, and
 		# Markdown AST construction via Markly.
 		module Parser
+			FLAGS = Markly::UNSAFE | Markly::FRONT_MATTER | Markly::INLINE_CODE_INFO | Markly::HTML_BLOCK_BLANK_LINES
+			
 			module_function
 			
+			# Parse slide Markdown with the standard flags and extensions.
+			# @parameter source [String] The Markdown source.
+			# @returns [Markly::Node] The parsed document.
+			def parse(source)
+				Markly.parse(source, flags: FLAGS, extensions: Fragment::EXTENSIONS)
+			end
+			
 			# Parse the file and return a {Slide}.
 			# @parameter presentation [Presentation] The presentation which owns the slide.
 			# @parameter path [String] The slide path relative to the presentation root.
@@ -72,7 +154,7 @@ module Presently
 				raw = File.read(source_path)
 				
 				# Parse once, with native front matter support.
-				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER | Markly::INLINE_CODE_INFO | Markly::HTML_BLOCK_BLANK_LINES, extensions: Fragment::EXTENSIONS)
+				document = parse(raw)
 				
 				expand_includes!(document, File.dirname(source_path), presentation.root)
 				rewrite_image_urls!(document, source_path, presentation.root)
@@ -109,14 +191,12 @@ module Presently
 						script_node.delete
 					end
 					
-					content = parse_sections(document)
 					notes = Fragment.new(notes_node)
 				else
-					content = parse_sections(document)
 					notes = nil
 				end
 				
-				Slide.new(presentation, path, front_matter: front_matter, content: content, notes: notes, scripts: scripts)
+				Slide.new(presentation, path, front_matter: front_matter, document: Fragment.new(document), notes: notes, scripts: scripts)
 			end
 			
 			# Extract reusable setup scripts from the expanded slide document.
@@ -169,7 +249,7 @@ module Presently
 				to_replace.each do |paragraph, relative_path|
 					included_path = File.expand_path(relative_path, base_dir)
 					included_raw = File.read(included_path)
-					included_document = Markly.parse(included_raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER | Markly::INLINE_CODE_INFO | Markly::HTML_BLOCK_BLANK_LINES, extensions: Fragment::EXTENSIONS)
+					included_document = parse(included_raw)
 					
 					# Strip front matter from included file if present.
 					front_matter_node = included_document.first_child
@@ -211,31 +291,6 @@ module Presently
 				end
 			end
 			
-			# Parse a Markly document into content sections based on top-level headings.
-			#
-			# Each heading becomes a named key; content before the first heading is
-			# collected under `"body"`. Each value is a {Fragment} wrapping a document node.
-			# @parameter document [Markly::Node] The document to parse.
-			# @returns [Hash(String, Fragment)] Sections keyed by heading name.
-			def parse_sections(document)
-				sections = {}
-				current_key = "body"
-				current_node = Markly::Node.new(:document)
-				
-				document.each do |node|
-					if node.type == :header
-						sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
-						current_key = node.to_plaintext.strip.downcase.gsub(/\s+/, "_")
-						current_node = Markly::Node.new(:document)
-					else
-						current_node.append_child(node.dup)
-					end
-				end
-				
-				sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
-				
-				sections
-			end
 		end
 		
 		# Load and parse a slide from a Markdown file.
@@ -250,18 +305,16 @@ module Presently
 		# @parameter presentation [Presentation] The presentation which owns the slide.
 		# @parameter path [String] The slide path relative to the presentation root.
 		# @parameter front_matter [Hash | Nil] The parsed YAML front_matter.
-		# @parameter content [Hash(String, Fragment)] Content sections keyed by heading name.
+		# @parameter document [Fragment | Nil] The complete slide document.
 		# @parameter notes [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		# @parameter scripts [Array(String)] JavaScript sources to execute after the slide renders.
-		# @parameter script [String | Nil] A single JavaScript source retained for compatibility.
-		def initialize(presentation, path, front_matter: nil, content: {}, notes: nil, scripts: [], script: nil)
+		def initialize(presentation, path, front_matter: nil, document: nil, notes: nil, scripts: [])
 			@presentation = presentation
 			@path = path
 			@front_matter = front_matter
-			@content = content
+			@document = document || Fragment.new(Markly::Node.new(:document))
 			@notes = notes
 			@scripts = scripts.dup
-			@scripts << script if script
 		end
 		
 		# @attribute [Presentation] The presentation which owns the slide.
@@ -279,8 +332,8 @@ module Presently
 		# @attribute [Hash | Nil] The parsed YAML front_matter.
 		attr :front_matter
 		
-		# @attribute [Hash(String, Fragment)] The content sections keyed by heading name.
-		attr :content
+		# @attribute [Fragment] The complete slide document.
+		attr :document
 		
 		# @attribute [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		attr :notes
@@ -288,14 +341,6 @@ module Presently
 		# @attribute [Array(String)] JavaScript sources to execute after the slide renders on the display.
 		attr :scripts
 		
-		# All JavaScript sources combined into a single string.
-		# @returns [String | Nil] The combined JavaScript, or `nil` when the slide has no scripts.
-		def script
-			return if @scripts.empty?
-			
-			@scripts.join("\n\n")
-		end
-		
 		# The template to use for rendering this slide.
 		# @returns [String] The template name from front_matter, or `"default"`.
 		def template
@@ -309,9 +354,15 @@ module Presently
 		end
 		
 		# The title of this slide.
-		# @returns [String] The title from front_matter, or the filename without extension.
+		# @returns [String] The H1 text, front matter title, or filename without extension.
 		def title
-			@front_matter&.fetch("title", File.basename(@path, ".md")) || File.basename(@path, ".md")
+			@document.heading_text(1) || @front_matter&.fetch("title", nil) || File.basename(@path, ".md")
+		end
+		
+		# The section name for this slide.
+		# @returns [String | Nil] The section from front matter, or `nil` when it was not specified.
+		def section
+			@front_matter&.fetch("section", nil)
 		end
 		
 		# Whether this slide should be skipped in the presentation.

data/lib/presently/slide_renderer.rb

@@ -64,36 +64,75 @@ module Presently
 	
 	# Provides the scope for XRB template rendering.
 	#
-	# Templates access slide content via `self.section(name)` and slide metadata via `self.slide`.
+	# Templates selectively extract placeholders with `self.extract(name)` and render the remainder
+	# with `self.document`.
 	class TemplateScope
 		# Initialize a new template scope for the given slide.
 		# @parameter slide [Slide] The slide being rendered.
 		def initialize(slide)
 			@slide = slide
+			@document = slide.document.dup
+			@heading = @document.extract_heading(1)
+			@extracted = {}
 		end
 		
 		# @attribute [Slide] The slide being rendered.
 		attr :slide
 		
-		# The content sections of the slide.
-		# @returns [Hash(String, String)] Sections keyed by heading name.
-		def content
-			@slide.content
+		# Render the slide body after title and placeholder extraction.
+		# @returns [XRB::MarkupString] The remaining document as HTML.
+		def document
+			markup(@document)
 		end
 		
-		# Whether the named content section exists and has content.
-		# @parameter name [String] The section name (derived from the Markdown heading).
-		# @returns [Boolean]
-		def section?(name)
-			fragment = @slide.content[name]
-			fragment && !fragment.empty?
+		# Extract and render a named H2 placeholder from this render's document.
+		#
+		# Extraction is cached so a template can reference a placeholder more than
+		# once without mutating the document repeatedly.
+		# @parameter name [String] The heading name to extract.
+		# @returns [XRB::MarkupString | Nil] The extracted HTML, or `nil` when absent.
+		def extract(name)
+			fragment = extract_fragment(name)
+			return unless fragment && !fragment.empty?
+			
+			markup(fragment)
+		end
+		
+		# Render the slide header using semantic markup.
+		# @returns [XRB::MarkupString] The rendered header, or an empty string when no metadata is present.
+		def slide_header
+			section = @slide.section
+			
+			return XRB::MarkupString.raw("") unless present?(section) || @heading
+			
+			builder = XRB::Builder.new
+			builder.tag(:header, class: "slide-header") do
+				if present?(section)
+					builder.tag(:div, class: "slide-section-heading") do
+						builder.text(section.to_s)
+					end
+				end
+				
+				builder.raw(@heading.to_html) if @heading
+			end
+			
+			XRB::MarkupString.raw(builder.to_s)
+		end
+		
+		private
+		
+		def extract_fragment(name)
+			return @extracted[name] if @extracted.key?(name)
+			
+			@extracted[name] = @document.extract(name)
+		end
+		
+		def markup(fragment)
+			XRB::MarkupString.raw(fragment&.to_html || "")
 		end
 		
-		# Get a named content section as raw HTML markup.
-		# @parameter name [String] The section name (derived from the Markdown heading).
-		# @returns [XRB::MarkupString] The rendered HTML content, safe for embedding.
-		def section(name)
-			XRB::MarkupString.raw(@slide.content[name]&.to_html || "")
+		def present?(value)
+			value && !value.to_s.empty?
 		end
 	end
 end

data/lib/presently/templates.rb

@@ -24,7 +24,7 @@ module Presently
 		end
 		
 		# Initialize with a fully-resolved root list.
-		# Prefer {.build} for normal use; use this when you already have the complete list.
+		# Prefer {.for} for normal use; use this when you already have the complete list.
 		# @parameter roots [Array(String)] The complete ordered list of directories to search.
 		def initialize(roots = [DEFAULT_ROOT])
 			@roots = roots

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.20.0"
+	VERSION = "0.21.0"
 end

data/public/_static/index.css

@@ -51,7 +51,6 @@ html, body {
 
 .slide {
 	--slide-font-size: 2.2cqi;
-	--slide-font-body: 1em;
 	--slide-font-title: 1.8em;
 	--slide-font-heading: 1.6em;
 	--slide-font-statement: 1.5em;
@@ -89,10 +88,33 @@ html, body {
 	line-height: 1.5;
 }
 
+.slide-header {
+	flex: none;
+	width: 100%;
+	padding: 0;
+	background: none;
+	border: 0;
+	margin-bottom: var(--slide-gap);
+}
+
+.slide-section-heading {
+	margin-bottom: calc(var(--slide-gap) * 0.25);
+	color: var(--accent-light);
+	font-family: var(--font-mono);
+	font-size: 0.45em;
+	font-weight: 700;
+	letter-spacing: 0.08em;
+	text-transform: uppercase;
+}
+
+.slide-header > h1 {
+	margin: 0;
+	font-size: var(--slide-font-heading);
+	line-height: 1.1;
+}
+
 /* Default template */
 .default-template .slide-body {
-	font-size: var(--slide-font-body);
-	line-height: 1.5;
 	width: 100%;
 }
 
@@ -118,22 +140,19 @@ html, body {
 	text-align: center;
 }
 
-.title-template .slide-title {
-	font-size: var(--slide-font-title);
-	font-weight: 700;
+.title-template .slide-header {
 	margin-bottom: calc(var(--slide-gap) * 0.75);
 }
 
-.title-template .slide-title p {
-	margin: 0;
+.title-template .slide-header > h1 {
+	font-size: var(--slide-font-title);
 }
 
-.title-template .slide-subtitle {
-	font-size: var(--slide-font-body);
+.title-template .slide-body {
 	opacity: 0.7;
 }
 
-.title-template .slide-subtitle p {
+.title-template .slide-body p {
 	margin: 0;
 }
 
@@ -146,22 +165,49 @@ html, body {
 	text-align: center;
 }
 
-.section-template .slide-heading {
-	font-size: var(--slide-font-heading);
+.section-template .slide-header {
+	margin-bottom: 0;
+}
+
+.section-template .slide-header > h1 {
 	font-weight: 700;
 }
 
-.section-template .slide-heading p {
+.section-template .slide-body {
+	margin-top: calc(var(--slide-gap) * 0.75);
+	opacity: 0.7;
+}
+
+.section-template .slide-body p {
 	margin: 0;
 }
 
 /* Two column template */
 .two-column-template {
-	flex-direction: row;
-	gap: calc(var(--slide-gap) * 1.5);
 	padding: calc(var(--slide-gutter) * 0.75) var(--slide-gutter);
 }
 
+.two-column-template .slide-columns {
+	display: flex;
+	align-items: center;
+	flex: 1;
+	width: 100%;
+	gap: calc(var(--slide-gap) * 1.5);
+}
+
+.two-column-template > .slide-body {
+	width: 100%;
+	margin-bottom: var(--slide-gap);
+}
+
+.two-column-template > .slide-body > :first-child {
+	margin-top: 0;
+}
+
+.two-column-template > .slide-body > :last-child {
+	margin-bottom: 0;
+}
+
 .two-column-template .column {
 	flex: 1;
 	min-width: 0;
@@ -178,23 +224,10 @@ html, body {
 }
 
 /* Diagram template */
-.diagram-template {
-	padding: var(--slide-gutter);
-}
-
-.diagram-template .slide-title {
-	flex: none;
-	width: 100%;
-	margin-bottom: var(--slide-gap);
-	font-size: var(--slide-font-body);
-	font-weight: 700;
+.diagram-template .slide-header {
 	text-align: center;
 }
 
-.diagram-template .slide-title p {
-	margin: 0;
-}
-
 .diagram-template .slide-body {
 	display: grid;
 	flex: 1;
@@ -356,6 +389,10 @@ pre > syntax-code {
 	width: 100%;
 }
 
+.statement-template .slide-header {
+	margin-bottom: 0;
+}
+
 .statement-template .slide-statement mermaid-diagram {
 	font-weight: normal;
 }
@@ -386,11 +423,17 @@ mermaid-diagram {
 /* Fullscreen template */
 .fill-template {
 	padding: 0;
-	width: 100%;
-	height: 100%;
 }
 
-.fill-template .slide-content {
+.fill-template .slide-header {
+	position: absolute;
+	top: var(--slide-gutter);
+	left: var(--slide-gutter);
+	z-index: 1;
+	width: calc(100% - var(--slide-gutter) * 2);
+}
+
+.fill-template .slide-body {
 	width: 100%;
 	height: 100%;
 	display: flex;
@@ -398,10 +441,19 @@ mermaid-diagram {
 	justify-content: center;
 }
 
-.fill-template .slide-content img,
-.fill-template .slide-content iframe,
-.fill-template .slide-content svg,
-.fill-template .slide-content video {
+.fill-template .slide-translation {
+	position: absolute;
+	bottom: var(--slide-gutter);
+	left: var(--slide-gutter);
+	z-index: 1;
+	width: calc(100% - var(--slide-gutter) * 2);
+	text-align: center;
+}
+
+.fill-template .slide-body img,
+.fill-template .slide-body iframe,
+.fill-template .slide-body svg,
+.fill-template .slide-body video {
 	width: 100%;
 	height: 100%;
 	object-fit: contain;
@@ -414,14 +466,12 @@ mermaid-diagram {
 	align-items: stretch;
 }
 
-.code-template .code-title {
-	font-size: var(--slide-font-secondary);
-	font-weight: 600;
+.code-template .slide-header {
 	margin-bottom: calc(var(--slide-gap) * 0.5);
 }
 
-.code-template .code-title p {
-	margin: 0;
+.code-template .slide-header > h1 {
+	font-size: var(--slide-font-secondary);
 }
 
 .code-viewport {
@@ -760,6 +810,7 @@ body.playback[data-controls="false"] .playback-start-screen {
 	display: flex;
 	align-items: center;
 	gap: 1rem;
+	min-width: 0;
 }
 
 .toolbar > button,

data/readme.md

@@ -67,6 +67,15 @@ The task records the presentation at 1920×1080 and 30 frames per second by defa
 
 Please see the [project releases](https://socketry.github.io/presently/releases/index) for all releases.
 
+### v0.21.0
+
+  - [Semantic Slides](https://socketry.github.io/presently/releases/index#semantic-slides)
+  - [Slide Scripts](https://socketry.github.io/presently/releases/index#slide-scripts)
+
+### v0.20.1
+
+  - Keep presenter toolbars within the viewport when slide paths are long.
+
 ### v0.19.0
 
   - Keep Anime.js resources created by delayed slide callbacks bound to the slide lifecycle.
@@ -112,14 +121,6 @@ q
 
   - Change zoom to 50% on slide preview (presenter display).
 
-### v0.12.0
-
-  - Add support for translation to code slide.
-
-### v0.11.0
-
-  - Add `Slide#element` and `SlideContext#element` getters — expose the slide body DOM element directly for cases where `find()` is not sufficient, such as measuring dimensions, attaching event listeners, or integrating third-party libraries.
-
 ## See Also
 
   - [lively](https://github.com/socketry/lively) — The real-time application framework that powers Presently.

data/releases.md

@@ -1,5 +1,21 @@
 # Releases
 
+## v0.21.0
+
+### Semantic Slides
+
+Slides now use semantic Markdown instead of treating every heading as a named section. Use a single H1 for the slide title, write the body directly after it, and replace structural sections such as `# Title`, `# Body`, `# Subtitle`, and `# Heading` with ordinary title and body content. For example, replace `# Title` followed by the title text with `# The actual title`, and move any display title from front matter into the H1.
+
+Template-specific placeholders are exact, case-sensitive H2 headings: `## Translation`, `## Caption`, `## Left`, and `## Right`. Custom templates should replace `self.section(name)` with `self.extract(name)` before rendering `self.document`; extraction removes that placeholder so it can be positioned independently.
+
+### Slide Scripts
+
+Slide scripts are now exposed only through `Slide#scripts`. Replace the compatibility `Slide#script` accessor and `script:` initializer argument with the ordered `scripts` array.
+
+## v0.20.1
+
+  - Keep presenter toolbars within the viewport when slide paths are long.
+
 ## v0.19.0
 
   - Keep Anime.js resources created by delayed slide callbacks bound to the slide lifecycle.

data/templates/code.xrb

@@ -1,17 +1,16 @@
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner code-template">
-	<?r if title = self.slide.title and !title.empty? ?>
-		<div class="code-title"><p>#{title}</p></div>
-	<?r end ?>
+	#{self.slide_header}
 	<div class="code-viewport" data-focus-start="#{self.slide.focus&.first}" data-focus-end="#{self.slide.focus&.last}">
 		<div class="code-scroll">
-			#{self.section("body")}
+			#{self.document}
 		</div>
 		<div class="code-dim code-dim-top"></div>
 		<div class="code-dim code-dim-bottom"></div>
 	</div>
-	<?r if self.section?("translation") ?>
+	<?r if translation ?>
 		<div class="slide-translation">
-			#{self.section("translation")}
+			#{translation}
 		</div>
 	<?r end ?>
 </div>

data/templates/default.xrb

@@ -1,10 +1,12 @@
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner default-template">
+	#{self.slide_header}
 	<div class="slide-body">
-		#{self.section("body")}
+		#{self.document}
 	</div>
-	<?r if self.section?("translation") ?>
+	<?r if translation ?>
 		<div class="slide-translation">
-			#{self.section("translation")}
+			#{translation}
 		</div>
 	<?r end ?>
 </div>

data/templates/diagram.xrb

@@ -1,10 +1,12 @@
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner diagram-template">
-	<?r if self.section?("title") ?>
-		<div class="slide-title">
-			#{self.section("title")}
-		</div>
-	<?r end ?>
+	#{self.slide_header}
 	<div class="slide-body">
-		#{self.section("body")}
+		#{self.document}
 	</div>
+	<?r if translation ?>
+		<div class="slide-translation">
+			#{translation}
+		</div>
+	<?r end ?>
 </div>

data/templates/fill.xrb

@@ -1,5 +1,12 @@
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner fill-template">
-	<div class="slide-content">
-		#{self.section("body")}
+	#{self.slide_header}
+	<div class="slide-body">
+		#{self.document}
 	</div>
+	<?r if translation ?>
+		<div class="slide-translation">
+			#{translation}
+		</div>
+	<?r end ?>
 </div>

data/templates/image.xrb

@@ -1,13 +1,16 @@
+<?r caption = self.extract("Caption") ?>
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner image-template">
+	#{self.slide_header}
 	<div class="slide-image">
-		#{self.section("body")}
+		#{self.document}
 	</div>
-	<?r if self.section?("caption") ?>
-		<div class="slide-caption">#{self.section("caption")}</div>
+	<?r if caption ?>
+		<div class="slide-caption">#{caption}</div>
 	<?r end ?>
-	<?r if self.section?("translation") ?>
+	<?r if translation ?>
 		<div class="slide-translation">
-			#{self.section("translation")}
+			#{translation}
 		</div>
 	<?r end ?>
 </div>

data/templates/section.xrb

@@ -1,10 +1,16 @@
+<?r translation = self.extract("Translation") ?>
+<?r header = self.slide_header ?>
+<?r body = self.document ?>
 <div class="slide-inner section-template">
-	<div class="slide-heading">
-		#{self.section("heading")}
-	</div>
-	<?r if self.section?("translation") ?>
+	#{header}
+	<?r unless body.empty? ?>
+		<div class="slide-body">
+			#{body}
+		</div>
+	<?r end ?>
+	<?r if translation ?>
 		<div class="slide-translation">
-			#{self.section("translation")}
+			#{translation}
 		</div>
 	<?r end ?>
 </div>

data/templates/statement.xrb

@@ -1,10 +1,12 @@
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner statement-template">
+	#{self.slide_header}
 	<div class="slide-statement">
-		#{self.section("body")}
+		#{self.document}
 	</div>
-	<?r if self.section?("translation") ?>
+	<?r if translation ?>
 		<div class="slide-translation">
-			#{self.section("translation")}
+			#{translation}
 		</div>
 	<?r end ?>
 </div>

data/templates/title.xrb

@@ -1,15 +1,12 @@
+<?r translation = self.extract("Translation") ?>
 <div class="slide-inner title-template">
-	<div class="slide-title">
-		#{self.section("title")}
+	#{self.slide_header}
+	<div class="slide-body">
+		#{self.document}
 	</div>
-	<?r if self.section?("subtitle") ?>
-		<div class="slide-subtitle">
-			#{self.section("subtitle")}
-		</div>
-	<?r end ?>
-	<?r if self.section?("translation") ?>
+	<?r if translation ?>
 		<div class="slide-translation">
-			#{self.section("translation")}
+			#{translation}
 		</div>
 	<?r end ?>
 </div>

data/templates/two_column.xrb

@@ -1,8 +1,26 @@
+<?r left = self.extract("Left") ?>
+<?r right = self.extract("Right") ?>
+<?r translation = self.extract("Translation") ?>
+<?r header = self.slide_header ?>
+<?r body = self.document ?>
 <div class="slide-inner two-column-template">
-	<div class="column left-column">
-		#{self.section("left")}
-	</div>
-	<div class="column right-column">
-		#{self.section("right")}
+	#{header}
+	<?r unless body.empty? ?>
+		<div class="slide-body">
+			#{body}
+		</div>
+	<?r end ?>
+	<div class="slide-columns">
+		<div class="column left-column">
+			#{left}
+		</div>
+		<div class="column right-column">
+			#{right}
+		</div>
 	</div>
+	<?r if translation ?>
+		<div class="slide-translation">
+			#{translation}
+		</div>
+	<?r end ?>
 </div>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -286,7 +286,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A web-based presentation tool built with Lively.
 test_files: []