presently 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42f99b653f49a0ac23d4c6b49314cde4ef814e70a7d274c7d67914e4f707514d
-  data.tar.gz: f308373c9741dad960682283d52df1d34e285e32e0c9155cd0911d3e62405562
+  metadata.gz: 3c2eaa843e93a1ef3f3c97b0e89c80a3ee4484ddbee4c105ca39bc7c324671ea
+  data.tar.gz: bc27aa664ca531b38da8b807e3fcb438a41c4338a180c1ddd39fc1daa0c549ed
 SHA512:
-  metadata.gz: 48116005297631e4fbdc4d06c1b83cfadb847d61dcb03ea60e603af4c28d9d0e678539fe114fbf6ce4f12e0fbc590281094e7fa40c2be003e9d488be31a25516
-  data.tar.gz: ed77bebb4005f828ab6b09c321cf075778a394706f0ff0bd6ffc2e2852e3c73ac2da3944e1ad7744cb82e3546702d0f81c4a966acc346f9c374b032f29100df9
+  metadata.gz: 98959ac207c29fa8a4bf444e0d1e476e584183615d04abed09c8f74cda3a338ed61f9517f67d5e7e5bb40aa624c352100bf1c2f36c61663a81f61ec509fe52d8
+  data.tar.gz: 30ca2a30e72d1f0c0dbc71b31786349ecd8d8c70eae5d69f29e701e77cd2f39487909a71a4699b2be9b70169cc170065313da35e46394ab92d0b378f3849e38a

data/bake/presently/rehearse.rb

@@ -21,8 +21,8 @@ end
 #
 # @parameter slides_root [String] The slides directory. Default: `slides`.
 # @parameter speaker [String | Nil] Only rehearse slides for this speaker.
-# @parameter from [String | Nil] Substring match — start at the first slide whose filename contains this.
-# @parameter to [String | Nil] Substring match — stop after the first slide whose filename contains this.
+# @parameter from [String | Nil] Substring match — start at the first slide whose relative path contains this.
+# @parameter to [String | Nil] Substring match — stop after the first slide whose relative path contains this.
 # @parameter resume [Boolean] Resume from the slide after the last one recorded in the log. Keeps prior records and appends new ones.
 # @parameter log [String] Path to write the JSON log. Default: `tmp/rehearsal.json`.
 def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: false, log: "tmp/rehearsal.json")
@@ -31,12 +31,12 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 	slides = slides.select{|slide| slide.speaker == speaker} if speaker
 	
 	if from
-		start_index = slides.index{|slide| File.basename(slide.path).include?(from)}
+		start_index = slides.index{|slide| slide.path.include?(from)}
 		slides = slides[start_index..] if start_index
 	end
 	
 	if to
-		end_index = slides.index{|slide| File.basename(slide.path).include?(to)}
+		end_index = slides.index{|slide| slide.path.include?(to)}
 		slides = slides[..end_index] if end_index
 	end
 	
@@ -49,7 +49,7 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 		
 		prior_records = JSON.parse(File.read(log), symbolize_names: true)
 		last_path = prior_records.last&.dig(:path)
-		resume_index = slides.index{|slide| File.basename(slide.path) == last_path}
+		resume_index = slides.index{|slide| slide.path == last_path}
 		
 		if resume_index.nil?
 			puts "Last rehearsed slide (#{last_path}) not found in current slide set. Nothing to resume."
@@ -81,14 +81,14 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 	records = []
 	offset = prior_records.length
 	slides.each_with_index do |slide, index|
-		basename = File.basename(slide.path)
+		relative_path = slide.path
 		headline = extract_headline(slide)
 		absolute = offset + index + 1
 		total = offset + slides.length
 		
 		puts
 		puts "─" * 72
-		puts "[#{absolute}/#{total}] #{basename}  planned: #{format_duration(slide.duration)}  speaker: #{slide.speaker || "—"}"
+		puts "[#{absolute}/#{total}] #{relative_path}  planned: #{format_duration(slide.duration)}  speaker: #{slide.speaker || "—"}"
 		puts "  #{headline}" unless headline.empty?
 		if slide.notes
 			notes = slide.notes.to_commonmark.strip
@@ -105,7 +105,7 @@ def rehearse(slides_root: "slides", speaker: nil, from: nil, to: nil, resume: fa
 		
 		records << {
 			index: absolute,
-			path: basename,
+			path: relative_path,
 			speaker: slide.speaker,
 			planned: slide.duration,
 			actual: elapsed.round(1),

data/bake/presently/slides.rb

@@ -58,7 +58,7 @@ def speakers(slides_root: "slides")
 		puts "#{speaker} — #{format_duration(total_seconds)}"
 		
 		slides.each do |slide|
-			puts "  #{format_duration(slide.duration)}  #{slide.title}  (#{File.basename(slide.path)})"
+			puts "  #{format_duration(slide.duration)}  #{slide.title}  (#{slide.path})"
 		end
 		
 		puts
@@ -69,9 +69,10 @@ end
 
 # Renumber slide files sequentially with a consistent step size.
 #
-# Renames all `.md` files in the slides directory to have sequential
+# Renames all `.md` files directly in the given directory to have sequential
 # numeric prefixes (010, 020, 030, ...), preserving their current order.
-# The descriptive part of the filename (after the number prefix) is kept.
+# The descriptive part of the filename (after the number prefix) is kept. It
+# does not recurse; pass a nested directory as `slides_root` to renumber it.
 #
 # @parameter slides_root [String] The slides directory. Default: `slides`.
 # @parameter step [Integer] The step between slide numbers. Default: `10`.

data/context/getting-started.md

@@ -32,7 +32,27 @@ $ mkdir slides
 
 ### Writing Slides
 
-Each slide is a Markdown file in the `slides/` directory. Files are ordered alphabetically, so prefix them with numbers:
+Each slide is a Markdown file in the `slides/` directory. Files are ordered by path, and every directory and slide filename must begin with a numeric prefix:
+
+``` text
+slides/
+├── 010-welcome.md
+├── 020-performance/
+│   ├── 010-introduction.md
+│   └── 020-results.md
+└── 030-conclusion.md
+```
+
+This allows related slides to be grouped in nested directories while retaining an unambiguous presentation order. Markdown files with any unnumbered path component, such as `slides/shared/example.md`, are not treated as slides and can be used for included content.
+
+The `presently:slides:renumber` task only renumbers files directly inside the selected directory. Run it without arguments for the top-level slides, or pass a nested directory explicitly:
+
+``` shell
+$ bake presently:slides:renumber
+$ bake presently:slides:renumber slides_root=slides/020-performance
+```
+
+A slide file contains Markdown with optional frontmatter and presenter notes:
 
 ``` markdown
 ---

data/lib/presently/application.rb

@@ -49,7 +49,7 @@ module Presently
 		def controller
 			@controller ||= begin
 				templates = Templates.for(@templates_roots)
-				presentation = Presentation.load(@slides_root, templates: templates)
+				presentation = Presentation.load(@slides_root, templates)
 				
 				PresentationController.new(presentation, state: State.new)
 			end
@@ -81,7 +81,7 @@ module Presently
 			
 			if path == "/export"
 				options = Export.options_from_query(query)
-				presentation = Presentation.load(@slides_root, templates: controller.templates)
+				presentation = Presentation.load(@slides_root, controller.templates)
 				export = Export.new(presentation: presentation, **options)
 				return Protocol::HTTP::Response[200, [["content-type", "text/html"]], [export.call]]
 			end

data/lib/presently/export.rb

@@ -106,7 +106,7 @@ module Presently
 				end
 				
 				builder.tag(:span, class: "export-filename") do
-					builder.tag(:code){builder.text(File.basename(slide.path))}
+					builder.tag(:code){builder.text(slide.path)}
 				end
 				
 				if @timing

data/lib/presently/presentation.rb

@@ -9,40 +9,33 @@ require_relative "templates"
 module Presently
 	# An immutable collection of slides with configuration.
 	#
-	# Use {.load} to create a presentation from a directory of Markdown files,
-	# or initialize directly with an array of {Slide} instances.
+	# Use {.load} to create a presentation from a directory of Markdown files.
+	# Each loaded {Slide} is attached to its presentation and identified by a
+	# path relative to the presentation root.
 	class Presentation
-		# Load and sort slide files from a directory.
-		# @parameter slides_root [String] The directory containing `.md` slide files.
-		# @returns [Array(Slide)] The loaded, sorted, non-skipped slides.
-		def self.slides_from(slides_root)
-			Dir.glob(File.join(slides_root, "*.md")).sort.map{|path| Slide.load(path)}.reject(&:skip?)
-		end
-		
 		# Load a presentation from a directory of Markdown slide files.
-		# @parameter slides_root [String] The directory containing `.md` slide files.
-		# @parameter options [Hash] Additional options passed to {#initialize}.
+		# @parameter root [String] The directory containing `.md` slide files.
+		# @parameter templates [Templates] The template resolver for loading slide templates.
 		# @returns [Presentation] A new presentation with slides loaded from the directory.
-		def self.load(slides_root = "slides", **options)
-			new(slides_from(slides_root), slides_root: slides_root, **options)
+		def self.load(root = "slides", templates = Templates.for)
+			new(root, templates)
 		end
 		
 		# Initialize a new presentation.
-		# @parameter slides [Array(Slide)] The ordered list of slides.
-		# @parameter slides_root [String | Nil] The directory slides were loaded from, used by {#reload}.
+		# @parameter root [String] The root directory containing slide files.
 		# @parameter templates [Templates] The template resolver for loading slide templates.
-		def initialize(slides = [], slides_root: nil, templates: Templates.for)
-			@slides = slides
-			@slides_root = slides_root
+		def initialize(root = "slides", templates = Templates.for)
+			@root = File.expand_path(root)
 			@templates = templates
+			@slides = load_slides
 		end
 		
+		# @attribute [String] The absolute root directory containing slide files.
+		attr :root
+		
 		# @attribute [Array(Slide)] The ordered list of slides.
 		attr :slides
 		
-		# @attribute [String | Nil] The directory slides were loaded from.
-		attr :slides_root
-		
 		# @attribute [Templates] The template resolver.
 		attr :templates
 		
@@ -66,12 +59,23 @@ module Presently
 		end
 		
 		# Return a new {Presentation} with freshly loaded slides and a cleared template cache.
-		# Only works if the presentation was created with {.load}.
-		# @returns [Presentation] A new presentation instance, or `self` if no slides root is set.
+		# @returns [Presentation] A new presentation instance.
 		def reload
-			return self unless @slides_root
-			
-			self.class.new(self.class.slides_from(@slides_root), slides_root: @slides_root, templates: @templates.reload)
+			self.class.new(@root, @templates.reload)
+		end
+		
+		private
+		
+		# Load slides recursively in relative path order.
+		# @returns [Array(Slide)] The loaded, sorted, non-skipped slides.
+		def load_slides
+			Dir.glob("**/*.md", base: @root).sort.filter_map do |path|
+				components = path.split(File::SEPARATOR)
+				next unless components.all?{|component| component.match?(/\A\d/)}
+				
+				slide = Slide.load(self, path)
+				slide unless slide.skip?
+			end
 		end
 	end
 end

data/lib/presently/presenter_view.rb

@@ -204,10 +204,10 @@ module Presently
 						if slide
 							builder.text(" · ")
 							builder.tag(:code, class: "slide-path") do
-								builder.text(File.basename(slide.path))
+								builder.text(slide.path)
 							end
 							
-							if editor_url = editor_url_for(slide.path)
+							if editor_url = editor_url_for(slide.source_path)
 								builder.tag(:a, href: editor_url, class: "edit-link") do
 									builder.text("✎")
 								end

data/lib/presently/slide.rb

@@ -61,15 +61,17 @@ module Presently
 			module_function
 			
 			# Parse the file and return a {Slide}.
-			# @parameter path [String] The file path to parse.
+			# @parameter presentation [Presentation] The presentation which owns the slide.
+			# @parameter path [String] The slide path relative to the presentation root.
 			# @returns [Slide]
-			def load(path)
-				raw = File.read(path)
+			def load(presentation, path)
+				source_path = File.join(presentation.root, path)
+				raw = File.read(source_path)
 				
 				# Parse once, with native front matter support.
 				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER, extensions: Fragment::EXTENSIONS)
 				
-				expand_includes!(document, File.dirname(path))
+				expand_includes!(document, File.dirname(source_path))
 				
 				# Extract front matter from the first AST node if present.
 				front_matter = nil
@@ -111,7 +113,7 @@ module Presently
 					script = nil
 				end
 				
-				Slide.new(path, front_matter: front_matter, content: content, notes: notes, script: script)
+				Slide.new(presentation, path, front_matter: front_matter, content: content, notes: notes, script: script)
 			end
 			
 			# Expand `![[path/to/file.md]]` include directives in a parsed document.
@@ -183,19 +185,22 @@ module Presently
 		end
 		
 		# Load and parse a slide from a Markdown file.
-		# @parameter path [String] The file path to the Markdown slide.
+		# @parameter presentation [Presentation] The presentation which owns the slide.
+		# @parameter path [String] The slide path relative to the presentation root.
 		# @returns [Slide]
-		def self.load(path)
-			Parser.load(path)
+		def self.load(presentation, path)
+			Parser.load(presentation, path)
 		end
 		
 		# Initialize a slide with pre-parsed data.
-		# @parameter path [String] The file path of the slide.
+		# @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 notes [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		# @parameter script [String | Nil] JavaScript to execute after the slide renders.
-		def initialize(path, front_matter: nil, content: {}, notes: nil, script: nil)
+		def initialize(presentation, path, front_matter: nil, content: {}, notes: nil, script: nil)
+			@presentation = presentation
 			@path = path
 			@front_matter = front_matter
 			@content = content
@@ -203,9 +208,18 @@ module Presently
 			@script = script
 		end
 		
-		# @attribute [String] The file path of the slide.
+		# @attribute [Presentation] The presentation which owns the slide.
+		attr :presentation
+		
+		# @attribute [String] The slide path relative to the presentation root.
 		attr :path
 		
+		# The absolute path of the slide source file.
+		# @returns [String]
+		def source_path
+			File.join(@presentation.root, @path)
+		end
+		
 		# @attribute [Hash | Nil] The parsed YAML front_matter.
 		attr :front_matter
 		

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.15.0"
+	VERSION = "0.16.0"
 end

data/readme.md

@@ -29,6 +29,10 @@ Please see the [project documentation](https://socketry.github.io/presently/) fo
 
 Please see the [project releases](https://socketry.github.io/presently/releases/index) for all releases.
 
+### v0.16.0
+
+  - Add support for organizing slides in nested directories. Every directory and slide filename must begin with a numeric prefix, and slides are ordered by relative path.
+
 ### v0.15.0
 
 q
@@ -80,10 +84,6 @@ q
   - Add `Slide#setTimeout(callback, delay)` — a tracked replacement for the global `setTimeout`. All timeouts registered this way are automatically cancelled when the slide changes, preventing stale callbacks from firing after navigation. The global `setTimeout` in slide scripts is shadowed by this method automatically.
   - Add `Slide#cancelTimeouts()` — cancels all pending timeouts registered by the slide's script. Called automatically by the presentation engine on every slide change.
 
-### v0.6.0
-
-  - Add `bake presently:slides:speakers` task to print a timing breakdown grouped by speaker. Each speaker's slides are listed in presentation order with individual and total durations, making it easy to balance talk time in multi-speaker presentations. Slides without a `speaker` key are grouped under `(no speaker)`.
-
 ## See Also
 
   - [lively](https://github.com/socketry/lively) — The real-time application framework that powers Presently.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.16.0
+
+  - Add support for organizing slides in nested directories. Every directory and slide filename must begin with a numeric prefix, and slides are ordered by relative path.
+
 ## v0.15.0
 
 q

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Samuel Williams