presently 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbb2d491928f3efc616d50e71f949a51d9ac4eca645a981372434a28855f86aa
-  data.tar.gz: 1a8eed679adbe70ab3303912f67789fb17cae0a723e6a363a96609ff70ec8e39
+  metadata.gz: 3991c95331fdcabd96b64dd78833690a52468f2a1e570eddf3234fd5e9bfa7ac
+  data.tar.gz: 816e1de43c33929e12424659455e116891294d79dcc3d2ea41cc8df9b13317dd
 SHA512:
-  metadata.gz: 40fba8bd5e994c33136e8627459a634b0c710539a19e06542ffcdacb525b003cff161418ab860c19a59ba91e8eabd2267a0b2bc004b2d509fc838ba8964ab8ab
-  data.tar.gz: e312ec32e02e1d3f21a36eb064ccedc82280984289382ffe996e3c3a03c9973a84da795e6dfd85bbc2b34fd7e4c8834387480128440ffbd5ba8c2773a3625e51
+  metadata.gz: bc5afae0aaeb288b51b4ccd6c8e66a562acd44898a49a3777299865ccff1a400258e88dd1fa3950071db8949b107fa076eac2d5042ccdd847e11d8d395801892
+  data.tar.gz: e0b1a9f6e5743beecdb4745469335c5ed8ad154e74bd5fdf2c745f54ce83532c1d81af3014c67ff8c9480e878b09a21e0df50cf73805e2a5676c0516a8ef807a

data/bake/presently/slides.rb

@@ -9,6 +9,30 @@ def initialize(context)
 	require "fileutils"
 end
 
+# Extract all presenter notes and print them to stdout.
+#
+# Loads every slide in the slides directory using the Presently API and
+# prints each slide's presenter notes to stdout. Each slide's notes are
+# preceded by a `##` heading with the slide file path.
+#
+# @parameter slides_root [String] The slides directory. Default: `slides`.
+def notes(slides_root: "slides")
+	require "presently"
+	
+	presentation = Presently::Presentation.load(slides_root)
+	
+	presentation.slides.each do |slide|
+		next unless slide.notes
+		
+		puts "## #{slide.path}"
+		puts
+		puts slide.notes.to_commonmark
+		puts
+	end
+	
+	return nil
+end
+
 # Renumber slide files sequentially with a consistent step size.
 #
 # Renames all `.md` files in the slides directory to have sequential

data/lib/presently/presenter_view.rb

@@ -270,8 +270,8 @@ module Presently
 				builder.tag(:div, class: "notes") do
 					builder.tag(:h3){builder.text("Notes")}
 					builder.tag(:div, class: "notes-content") do
-						if slide&.notes
-							builder.raw(slide.notes)
+						if notes = slide&.notes
+							builder.raw(notes.to_html)
 						else
 							builder.tag(:p, class: "no-notes"){builder.text("No presenter notes for this slide.")}
 						end

data/lib/presently/slide.rb

@@ -14,116 +14,145 @@ module Presently
 	# Each slide has YAML front_matter for metadata (template, duration, focus), content sections
 	# split by Markdown headings, 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
+		# their output format without the parser pre-committing to one.
+		class Fragment
+			# Markly extensions enabled for all slide Markdown rendering.
+			EXTENSIONS = [:table, :tasklist, :strikethrough, :autolink]
+			
+			# Initialize a fragment from a Markly document node.
+			# @parameter node [Markly::Node] A document node containing the fragment content.
+			def initialize(node)
+				@node = node
+			end
+			
+			# @attribute [Markly::Node] The underlying AST document node.
+			attr :node
+			
+			# Whether the fragment has no content.
+			# @returns [Boolean]
+			def empty?
+				@node.first_child.nil?
+			end
+			
+			# Render the fragment to HTML using the Presently renderer.
+			#
+			# Mermaid fenced code blocks are rendered as `<mermaid-diagram>` elements.
+			# @returns [String] The rendered HTML.
+			def to_html
+				Renderer.new(flags: Markly::UNSAFE, extensions: EXTENSIONS).render(@node)
+			end
+			
+			# Render the fragment back to CommonMark Markdown.
+			# @returns [String] The CommonMark source.
+			def to_commonmark
+				@node.to_commonmark
+			end
+			
+			alias to_s to_commonmark
+		end
+		
 		# Parses a Markdown slide file into structured data for {Slide}.
 		#
 		# Handles YAML front_matter extraction, presenter note separation, and
-		# Markdown-to-HTML rendering using the Markly AST.
+		# Markdown AST construction via Markly.
 		module Parser
-			# Markly extensions enabled for all slide Markdown rendering.
-			EXTENSIONS = [:table, :tasklist, :strikethrough, :autolink]
-
 			module_function
-
+			
 			# Parse the file and return a {Slide}.
 			# @parameter path [String] The file path to parse.
 			# @returns [Slide]
 			def load(path)
 				raw = File.read(path)
-
+				
 				# Parse once, with native front matter support.
-				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER, extensions: EXTENSIONS)
-
+				document = Markly.parse(raw, flags: Markly::UNSAFE | Markly::FRONT_MATTER, extensions: Fragment::EXTENSIONS)
+				
 				# Extract front matter from the first AST node if present.
 				front_matter = nil
 				if (front_matter_node = document.first_child) && front_matter_node.type == :front_matter
 					front_matter = YAML.safe_load(front_matter_node.string_content)
 					front_matter_node.delete
 				end
-
+				
 				# Find the last hrule, which acts as the separator between slide content and presenter notes.
 				last_hrule = nil
 				document.each{|node| last_hrule = node if node.type == :hrule}
-
+				
 				if last_hrule
-					notes_fragment = Markly::Node.new(:document)
+					notes_node = Markly::Node.new(:document)
 					while child = last_hrule.next
-						notes_fragment.append_child(child)
+						notes_node.append_child(child)
 					end
 					last_hrule.delete
-
+					
 					# Extract the last javascript code block from the notes as the slide script.
 					script_node = nil
-					notes_fragment.each do |node|
+					notes_node.each do |node|
 						if node.type == :code_block && node.fence_info.to_s.strip == "javascript"
 							script_node = node
 						end
 					end
-
+					
 					script = nil
 					if script_node
 						script = script_node.string_content
 						script_node.delete
 					end
-
-					content = parse_sections(document.each)
-					notes = render_nodes(notes_fragment.each)
+					
+					content = parse_sections(document)
+					notes = Fragment.new(notes_node)
 				else
-					content = parse_sections(document.each)
+					content = parse_sections(document)
 					notes = nil
 					script = nil
 				end
-
+				
 				Slide.new(path, front_matter: front_matter, content: content, notes: notes, script: script)
 			end
-
-			# Parse a list of AST nodes into sections based on top-level Markdown headings.
-			# Each heading becomes a named key; content before the first heading
-			# is collected under `"body"`. Headings inside code blocks are invisible
-			# to this method as they never appear as top-level AST nodes.
-			# @parameter nodes [Array(Markly::Node)] The nodes to parse into sections.
-			# @returns [Hash(String, String)] Sections keyed by heading name, with rendered HTML values.
-			def parse_sections(nodes)
+			
+			# 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_nodes = []
-
-				nodes.each do |node|
+				current_node = Markly::Node.new(:document)
+				
+				document.each do |node|
 					if node.type == :header
-						sections[current_key] = render_nodes(current_nodes) unless current_nodes.empty?
+						sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
 						current_key = node.to_plaintext.strip.downcase.gsub(/\s+/, "_")
-						current_nodes = []
+						current_node = Markly::Node.new(:document)
 					else
-						current_nodes << node
+						current_node.append_child(node.dup)
 					end
 				end
-
-				sections[current_key] = render_nodes(current_nodes) unless current_nodes.empty?
-
+				
+				sections[current_key] = Fragment.new(current_node) unless current_node.first_child.nil?
+				
 				sections
 			end
-
-			# Render a list of AST nodes to HTML via a temporary document.
-			# @parameter nodes [Array(Markly::Node)] The nodes to render.
-			# @returns [String] The rendered HTML.
-			def render_nodes(nodes)
-				doc = Markly::Node.new(:document)
-				nodes.each{|node| doc.append_child(node.dup)}
-				Renderer.new(flags: Markly::UNSAFE, extensions: EXTENSIONS).render(doc)
-			end
 		end
-
+		
 		# Load and parse a slide from a Markdown file.
 		# @parameter path [String] The file path to the Markdown slide.
 		# @returns [Slide]
 		def self.load(path)
 			Parser.load(path)
 		end
-
+		
 		# Initialize a slide with pre-parsed data.
 		# @parameter path [String] The file path of the slide.
 		# @parameter front_matter [Hash | Nil] The parsed YAML front_matter.
-		# @parameter content [Hash(String, String)] Content sections keyed by heading name.
-		# @parameter notes [String | Nil] The rendered HTML presenter notes.
+		# @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)
 			@path = path
@@ -132,58 +161,58 @@ module Presently
 			@notes = notes
 			@script = script
 		end
-
+		
 		# @attribute [String] The file path of the slide.
 		attr :path
-
+		
 		# @attribute [Hash | Nil] The parsed YAML front_matter.
 		attr :front_matter
-
-		# @attribute [Hash(String, String)] The content sections keyed by heading name.
+		
+		# @attribute [Hash(String, Fragment)] The content sections keyed by heading name.
 		attr :content
-
-		# @attribute [String | Nil] The rendered HTML presenter notes.
+		
+		# @attribute [Fragment | Nil] The presenter notes as a Markly AST fragment.
 		attr :notes
-
+		
 		# @attribute [String | Nil] JavaScript to execute after the slide renders on the display.
 		attr :script
-
+		
 		# The template to use for rendering this slide.
 		# @returns [String] The template name from front_matter, or `"default"`.
 		def template
 			@front_matter&.fetch("template", "default") || "default"
 		end
-
+		
 		# The expected duration of this slide in seconds.
 		# @returns [Integer] The duration from front_matter, or `60`.
 		def duration
 			@front_matter&.fetch("duration", 60) || 60
 		end
-
+		
 		# The title of this slide.
 		# @returns [String] The title from front_matter, or the filename without extension.
 		def title
 			@front_matter&.fetch("title", File.basename(@path, ".md")) || File.basename(@path, ".md")
 		end
-
+		
 		# Whether this slide should be skipped in the presentation.
 		# @returns [Boolean]
 		def skip?
 			@front_matter&.fetch("skip", false) || false
 		end
-
+		
 		# The navigation marker for this slide, used in the presenter's jump-to dropdown.
 		# @returns [String | Nil] The marker label, or `nil` if not marked.
 		def marker
 			@front_matter&.fetch("marker", nil)
 		end
-
+		
 		# The transition type for animating into this slide.
 		# @returns [String | Nil] The transition name (e.g. `"fade"`, `"slide-left"`, `"morph"`), or `nil` for instant swap.
 		def transition
 			@front_matter&.fetch("transition", nil)
 		end
-
+		
 		# The line range to focus on for code slides.
 		# @returns [Array(Integer, Integer) | Nil] The `[start, end]` line numbers (1-based), or `nil`.
 		def focus

data/lib/presently/slide_renderer.rb

@@ -68,14 +68,15 @@ module Presently
 		# @parameter name [String] The section name (derived from the Markdown heading).
 		# @returns [Boolean]
 		def section?(name)
-			!(@slide.content[name] || "").empty?
+			fragment = @slide.content[name]
+			fragment && !fragment.empty?
 		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] || "")
+			XRB::MarkupString.raw(@slide.content[name]&.to_html || "")
 		end
 	end
 end

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.3.0"
+	VERSION = "0.4.0"
 end

data/readme.md

@@ -2,6 +2,8 @@
 
 A web-based presentation tool built with [Lively](https://github.com/socketry/lively). Write your slides in Markdown, present them in the browser, and control everything from a separate presenter display.
 
+![Presenter Display](presenter.png)
+
 [![Development Status](https://github.com/socketry/presently/workflows/Test/badge.svg)](https://github.com/socketry/presently/actions?workflow=Test)
 
 ## Features
@@ -19,14 +21,19 @@ A web-based presentation tool built with [Lively](https://github.com/socketry/li
 
 Please see the [project documentation](https://socketry.github.io/presently/) for more details.
 
-  - [Animating Slides](https://socketry.github.io/presently/guides/animating-slides/index) - This guide explains how to animate content within slides using the `morph` transition and the slide scripting system.
-
   - [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.
 
+  - [Animating Slides](https://socketry.github.io/presently/guides/animating-slides/index) - This guide explains how to animate content within slides using the `morph` transition and the slide scripting system.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/presently/releases/index) for all releases.
 
+### v0.4.0
+
+  - Add `bake presently:slides:notes` task to extract all presenter notes into a single Markdown document, with each slide's file path as a heading. Useful for reviewing or sharing speaker notes outside of the presentation.
+  - Presenter notes are now kept as a Markdown AST internally and rendered to HTML on demand, so the notes you write are faithfully round-tripped rather than converted to HTML at parse time.
+
 ### v0.3.0
 
   - Add `diagram` template with a `position: relative` container — direct `<div>` children are `position: absolute` by default for free-form layouts.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.4.0
+
+  - Add `bake presently:slides:notes` task to extract all presenter notes into a single Markdown document, with each slide's file path as a heading. Useful for reviewing or sharing speaker notes outside of the presentation.
+  - Presenter notes are now kept as a Markdown AST internally and rendered to HTML on demand, so the notes you write are faithfully round-tripped rather than converted to HTML at parse time.
+
 ## v0.3.0
 
   - Add `diagram` template with a `position: relative` container — direct `<div>` children are `position: absolute` by default for free-form layouts.

metadata

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