utopia-project 0.39.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21be268fb201720abe3d699eba3f8a71ebee79896293f8aaa0861a592d650dab
-  data.tar.gz: 93c814b9d849ad90d3a7761cf6d4c9bd2713293fb7de7bb48b5b2f28b3c8b34d
+  metadata.gz: 2b939e146930849d4cf8f02d043129ed9ac4d4e30cef2c672936deeba8ebf834
+  data.tar.gz: e481fe629ee2812bf5138577ee0e55b8a1025960bb0f050129b40a1bae3a3565
 SHA512:
-  metadata.gz: b0ece167920bd1069f74879b53a1844948808613e6865ecc3984861c9d6c6fe89bb9d2b98e60cb545523c488c8d5c439f8f5ff7a3b589a54222225272c3837f7
-  data.tar.gz: 885452bfa693632fae6fedb2970ec85575e7633fe2f98c62f06195f524f3fb4d27333b7eb399abfeb33455b5e6a4a390393a8163e526d5534f2528544048de68
+  metadata.gz: d403f98935fc293324f8d0b1001535cfe38d7ce04aea3040257b651d89fd2bcacad593d0749fe2c250bd8b61ccbd30dd00db40f981164865d74ae26831841f51
+  data.tar.gz: 28ecbb2dae306f4a0568e7b325a5f47f2d487de5854190db1d82e8bb489effcd8d77d62ef3cf94ece65c21a863a2c7b41158fc5f4141242497908752d8910c20

data/bake/utopia/project.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 def initialize(context)
 	super
@@ -35,7 +35,7 @@ end
 # @parameter port [Integer] The port to bind to.
 # @parameter bind [String] The URL to bind to, e.g. `http://localhost:80`.
 def serve(port: nil, bind: nil)
-	config_path = File.expand_path("../../template/config.ru", __dir__)
+	config_path = File.expand_path("../../template/config/serve.rb", __dir__)
 	preload_path = File.expand_path("../../template/preload.rb", __dir__)
 	
 	options = []
@@ -55,22 +55,15 @@ end
 # @parameter output_path [String] The output path for the static site.
 # @parameter force [Boolean] Remove the output directory before generating the static content.
 def static(output_path: "docs", force: true)
-	require "rackula/command"
-	
-	config_path = File.expand_path("../../template/config.ru", __dir__)
+	application_path = File.expand_path("../../template/config/application.rb", __dir__)
 	public_path = File.expand_path("../../public", __dir__)
 	
-	arguments = []
-	
-	if force
-		arguments << "--force"
-	end
-	
-	Rackula::Command::Top["generate", *arguments,
-		"--config", config_path,
-		"--public", public_path,
-		"--output-path", output_path
-	].call
+	context["utopia:static:generate"].call(
+		output_path: output_path,
+		application_path: application_path,
+		public_path: public_path,
+		force: force,
+	)
 	
 	FileUtils.touch File.expand_path(".nojekyll", output_path)
 end
@@ -94,4 +87,3 @@ def description(root: context.root)
 		end
 	end
 end
-

data/lib/utopia/project/base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 # Copyright, 2023, by Michael Adams.
 
 require "utopia/path"
@@ -15,7 +15,7 @@ require "thread/local"
 require_relative "document"
 require_relative "releases_document"
 
-require_relative "guide"
+require_relative "guides"
 require_relative "linkify"
 
 module Utopia
@@ -24,6 +24,8 @@ module Utopia
 		class Base
 			extend Thread::Local
 			
+			# Load the current project and index its Ruby source files.
+			# @returns [Base] The loaded project.
 			def self.local
 				instance = self.new
 				
@@ -100,6 +102,9 @@ module Utopia
 				end
 			end
 			
+			# Load the supplemental document associated with a definition.
+			# @parameter definition [Decode::Definition] The definition to load documentation for.
+			# @returns [Document | Nil] The supplemental document, if it exists.
 			def document_for(definition)
 				document_path = File.join("lib", definition.lexical_path.map{|_| _.to_s.downcase}) + ".md"
 				
@@ -114,6 +119,11 @@ module Utopia
 				end
 			end
 			
+			# Format source text with links to referenced definitions.
+			# @parameter text [String] The source text to format.
+			# @parameter definition [Decode::Definition] The definition that provides the lexical context.
+			# @parameter language [Decode::Language::Generic] The source language.
+			# @returns [String] The formatted source code markup.
 			def linkify(text, definition, language: definition&.language)
 				rewriter = Linkify.new(self, language, text)
 				
@@ -193,10 +203,8 @@ module Utopia
 				end
 			end
 			
-			# Enumerate over all available guides in order.
-			# @yields {|guide| ...} If a block is given.
-			# 	@parameter guide [Guide]
-			# @returns [Enumerator(Guide)] If no block given.
+			# Get the guides collection for this project.
+			# @returns [Guides]
 			#
 			# @example List guide titles
 			# 	base = Utopia::Project::Base.new
@@ -204,33 +212,33 @@ module Utopia
 			# 		puts guide.title
 			# 	end
 			def guides
-				return to_enum(:guides) unless block_given?
-				
-				@links.index("/guides").each do |link|
-					guide_path = File.join(@root, link.path)
-					
-					next unless File.directory?(guide_path)
-					
-					yield Guide.new(self, guide_path, link.info)
-				end
+				@guides ||= Guides.new(self, @links)
 			end
 			
+			# Load the project README document.
+			# @returns [Document | Nil] The README document, if one exists.
 			def readme_document
 				if path = self.path_for("readme.md") || self.path_for("README.md")
 					Document.new(File.read(path), self)
 				end
 			end
 			
+			# Get the project title from its README.
+			# @returns [String] The project title, or a generic fallback.
 			def project_title
 				readme_document&.title || "Project"
 			end
 			
+			# Load the project release notes document.
+			# @returns [ReleasesDocument | Nil] The release notes document, if one exists.
 			def releases_document
 				if path = self.path_for("releases.md")
 					ReleasesDocument.new(File.read(path), self)
 				end
 			end
 			
+			# Enumerate the project releases.
+			# @returns [Enumerator(ReleasesDocument::Release) | Nil] The releases, if release notes exist.
 			def releases
 				if releases_document = self.releases_document
 					releases_document.releases

data/lib/utopia/project/document.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "renderer"
 require "xrb"
 
 module Utopia
 	module Project
+		# Represents a Markdown document with optional source code cross-references.
 		class Document
+			# Initialize a document from Markdown text.
+			# @parameter text [String] The Markdown source text.
+			# @parameter base [Base | Nil] The project used to resolve source code references.
+			# @parameter definition [Decode::Definition | Nil] The definition that provides the lexical context.
+			# @parameter default_language [Decode::Language::Generic | Nil] The default language for source code references.
 			def initialize(text, base = nil, definition: nil, default_language: nil)
 				@text = text
 				@base = base
@@ -20,10 +26,14 @@ module Utopia
 				@root = nil
 			end
 			
+			# Parse and resolve the document root.
+			# @returns [Markly::Node] The root document node.
 			def root
 				@root ||= resolve(Markly.parse(@text, extensions: [:table]))
 			end
 			
+			# Extract the leading heading as the document title.
+			# @returns [String | Nil] The title, if the document starts with a heading.
 			def title
 				child = self.root.first_child
 				
@@ -32,10 +42,17 @@ module Utopia
 				end
 			end
 			
+			# Get the first node in the document.
+			# @returns [Markly::Node | Nil] The first child node.
 			def first_child
 				self.root.first_child
 			end
 			
+			# Remove a named section and yield its heading for replacement.
+			# @parameter name [String] A fragment of the heading text to match.
+			# @parameter children [Boolean] Whether to remove nested subsections too.
+			# @yields {|header| ...} The matched heading node.
+			# 	@parameter header [Markly::Node] The matched heading.
 			def replace_section(name, children: false)
 				child = self.first_child
 				
@@ -72,39 +89,62 @@ module Utopia
 				end
 			end
 			
+			# Render the document as Markdown.
+			# @returns [String] The rendered Markdown.
 			def to_markdown(**options)
 				self.root.to_markdown(**options)
 			end
 			
+			# Render a document node as HTML.
+			# @parameter node [Markly::Node] The node to render.
+			# @returns [XRB::MarkupString] The rendered HTML markup.
 			def to_html(node = self.root, **options)
 				renderer = Renderer.new(ids: true, flags: Markly::UNSAFE, **options)
 				XRB::Markup.raw(renderer.render(node))
 			end
 			
+			# Wrap a node in a paragraph.
+			# @parameter child [Markly::Node] The node to wrap.
+			# @returns [Markly::Node] The paragraph node.
 			def paragraph_node(child)
 				node = Markly::Node.new(:paragraph)
 				node.append_child(child)
 				return node
 			end
 			
+			# Build an HTML block node.
+			# @parameter content [String] The raw HTML content.
+			# @parameter type [Symbol] The node type retained for compatibility.
+			# @returns [Markly::Node] The HTML node.
 			def html_node(content, type = :html)
 				node = Markly::Node.new(:html)
 				node.string_content = content
 				return node
 			end
 			
+			# Build an inline HTML node.
+			# @parameter content [String] The raw HTML content.
+			# @returns [Markly::Node] The inline HTML node.
 			def inline_html_node(content)
 				node = Markly::Node.new(:inline_html)
 				node.string_content = content
 				return node
 			end
 			
+			# Build a text node.
+			# @parameter content [String] The text content.
+			# @returns [Markly::Node] The text node.
 			def text_node(content)
 				node = Markly::Node.new(:text)
 				node.string_content = content
 				return node
 			end
 			
+			# Build a link node around a child node.
+			# @parameter title [String | Nil] The link title.
+			# @parameter url [String | XRB::Reference] The link target.
+			# @parameter child [Markly::Node] The linked child node.
+			# @returns [Markly::Node] The link node.
 			def link_node(title, url, child)
 				node = Markly::Node.new(:link)
 				node.title = title
@@ -115,6 +155,10 @@ module Utopia
 				return node
 			end
 			
+			# Build an inline code node.
+			# @parameter content [String] The code content.
+			# @parameter language [String | Nil] The source language name.
+			# @returns [Markly::Node] The code node.
 			def code_node(content, language = nil)
 				if language
 					node = inline_html_node(

data/lib/utopia/project/guide.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "utopia/path"
 require "xrb/reference"
@@ -38,10 +38,15 @@ module Utopia
 			# @attribute [Hash]
 			attr :metadata
 			
+			# The explicit display order of the guide.
+			# @returns [Integer | Nil]
 			def order
 				metadata[:order]
 			end
 			
+			# Compare guides by explicit order and then by name.
+			# @parameter other [Guide] The other guide to compare.
+			# @returns [Integer] The comparison result.
 			def <=> other
 				if order = self.order
 					if other_order = other.order

data/lib/utopia/project/guides.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "guide"
+
+module Utopia
+	module Project
+		# A collection of guides with navigation and lookup capabilities.
+		class Guides
+			include Enumerable
+			
+			# Initialize the guides collection.
+			# @parameter base [Base] The base instance for the project.
+			# @parameter links [Object] The links index for finding guides.
+			def initialize(base, links)
+				@base = base
+				@links = links
+			end
+			
+			# Iterate over all guides.
+			# @yields {|guide| ...} If a block is given.
+			# 	@parameter guide [Guide]
+			# @returns [Enumerator(Guide)] If no block is given.
+			def each(&block)
+				return to_enum(:each) unless block_given?
+				
+				@links.index("/guides").each do |link|
+					guide_path = File.join(@base.root, link.path)
+					
+					next unless File.directory?(guide_path)
+					
+					yield Guide.new(@base, guide_path, link.info)
+				end
+			end
+			
+			# Get all guides as a sorted array.
+			# @returns [Array(Guide)]
+			def to_a
+				@array ||= super.sort
+			end
+			
+			# Find a guide by name.
+			# @parameter name [String] The guide name.
+			# @returns [Guide | Nil]
+			def [](name)
+				to_a.find{|guide| guide.name == name}
+			end
+			
+			# Get the related guides (previous and next) for the given guide.
+			# @parameter guide [Guide] The current guide.
+			# @returns [Array(Guide | Nil, Guide | Nil)] A two-element array containing the previous and next guides.
+			def related(guide)
+				index = to_a.index{|g| g.name == guide.name}
+				return [nil, nil] unless index
+				
+				previous_guide = index > 0 ? to_a[index - 1] : nil
+				next_guide = index < to_a.size - 1 ? to_a[index + 1] : nil
+				
+				[previous_guide, next_guide]
+			end
+		end
+	end
+end

data/lib/utopia/project/import_map.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
 require "utopia/import_map"
 
 module Utopia
@@ -7,4 +12,4 @@ module Utopia
 			map.import("@socketry/syntax", "./@socketry/syntax/Syntax.js")
 		end
 	end
-end
+end

data/lib/utopia/project/linkify.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "decode/syntax/rewriter"
 
 module Utopia
 	module Project
+		# Rewrites source code as HTML with links to indexed definitions.
 		class Linkify < Decode::Syntax::Rewriter
+			# Initialize a source code rewriter.
 			# @parameter base [Base] The base data.
+			# @parameter language [Decode::Language::Generic] The source language.
+			# @parameter text [String] The source text to rewrite.
 			def initialize(base, language, text)
 				@base = base
 				@language = language
@@ -16,12 +20,19 @@ module Utopia
 				super(text)
 			end
 			
+			# Escape an unmatched range of source text for HTML output.
+			# @parameter range [Range] The source text range.
+			# @returns [String] The escaped text.
 			def text_for(range)
 				text = super(range)
 				
 				return XRB::Strings.to_html(text)
 			end
 			
+			# Build a link to an indexed definition.
+			# @parameter definition [Decode::Definition] The linked definition.
+			# @parameter text [String] The visible link text.
+			# @returns [XRB::MarkupString] The link markup.
 			def link_to(definition, text)
 				XRB::Builder.fragment do |builder|
 					builder.inline("a", href: @base.link_for(definition), title: definition.qualified_name) do
@@ -30,6 +41,9 @@ module Utopia
 				end
 			end
 			
+			# Apply the source links and wrap the result in a code element.
+			# @parameter output [XRB::Builder] The output builder.
+			# @returns [String] The generated HTML markup.
 			def apply(output = XRB::Builder.new)
 				output.inline("code", class: "language-#{@language.name}") do
 					super

data/lib/utopia/project/releases_document.rb

@@ -1,39 +1,56 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "document"
 require_relative "sidebar"
 
 module Utopia
 	module Project
+		# Represents project release notes organized by release headings.
 		class ReleasesDocument < Document
+			# Represents a section within a release.
 			class Summary
+				# Initialize a release section summary.
+				# @parameter node [Markly::Node] The section heading node.
 				def initialize(node)
 					@node = node
 				end
 				
+				# The section heading node.
+				# @attribute [Markly::Node]
 				attr :node
 				
+				# Generate the section identifier.
+				# @returns [String] The normalized section identifier.
 				def id
 					@node.to_plaintext.chomp.downcase.gsub(/\s+/, "-")
 				end
 				
+				# Render the section heading contents as Markdown.
+				# @returns [String] The rendered Markdown.
 				def to_markdown
 					@node.dup.extract_children.to_markdown
 				end
 				
+				# Render the section heading contents as HTML.
+				# @returns [String] The rendered HTML.
 				def to_html
 					@node.dup.extract_children.to_html
 				end
 			end
 			
+			# Represents a single release and its notes.
 			class Release
+				# Initialize a release from its heading node.
+				# @parameter node [Markly::Node] The release heading node.
 				def initialize(node)
 					@node = node
 				end
 				
+				# Extract the introductory notes for the release.
+				# @returns [Markly::Node] A document containing the release notes.
 				def notes
 					node = @node.next
 					
@@ -48,6 +65,10 @@ module Utopia
 					return notes
 				end
 				
+				# Enumerate the change sections for the release.
+				# @yields {|summary| ...} If a block is given.
+				# 	@parameter summary [Summary] A change section.
+				# @returns [Enumerator(Summary)] If no block is given.
 				def changes
 					return to_enum(:changes) unless block_given?
 					
@@ -68,15 +89,25 @@ module Utopia
 					end
 				end
 				
+				# Get the release name from its heading.
+				# @returns [String] The release name.
 				def name
 					@node.to_plaintext.chomp
 				end
 				
+				# Build a link to a section within the release.
+				# @parameter base [String] The base URL path.
+				# @parameter anchor [String] The section anchor.
+				# @returns [String] The release section URL.
 				def href(base = "/", anchor:)
 					"#{base}releases/index##{anchor.downcase.gsub(/\s+/, "-")}"
 				end
 			end
 			
+			# Enumerate release names in document order.
+			# @yields {|name| ...} If a block is given.
+			# 	@parameter name [String] A release name.
+			# @returns [Enumerator(String)] If no block is given.
 			def release_names
 				return to_enum(:release_names) unless block_given?
 				
@@ -87,6 +118,9 @@ module Utopia
 				end
 			end
 			
+			# Find a release by name.
+			# @parameter name [String] The release name.
+			# @returns [Release | Nil] The matching release.
 			def release(name)
 				self.root.each do |node|
 					if node.type == :header and node.header_level == 2 and node.to_plaintext.chomp == name
@@ -95,12 +129,18 @@ module Utopia
 				end
 			end
 			
+			# Get the first release in the document.
+			# @returns [Release | Nil] The latest release.
 			def latest_release
 				if name = release_names.first
 					release(name)
 				end
 			end
 			
+			# Enumerate releases in document order.
+			# @yields {|release| ...} If a block is given.
+			# 	@parameter release [Release] A release.
+			# @returns [Enumerator(Release)] If no block is given.
 			def releases
 				return to_enum(:releases) unless block_given?
 				

data/lib/utopia/project/renderer.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2025, by Samuel Williams.
+# Copyright, 2022-2026, by Samuel Williams.
 
 require "markly"
 require "markly/renderer/html"
 
 module Utopia
 	module Project
+		# Renders project Markdown with support for Mermaid code blocks.
 		class Renderer < Markly::Renderer::HTML
+			# Render a fenced code block, including Mermaid diagrams.
+			# @parameter node [Markly::Node] The fenced code block node.
 			def code_block(node)
 				language, _ = node.fence_info.split(/\s+/, 2)
 				

data/lib/utopia/project/sidebar.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "renderer"
 
@@ -12,6 +12,10 @@ module Utopia
 			
 			# Represents a sidebar navigation entry with title, level, and anchor.
 			class Entry
+				# Initialize a sidebar entry.
+				# @parameter title_html [XRB::Markup] The rendered heading title.
+				# @parameter level [Integer] The heading level.
+				# @parameter anchor [String] The heading anchor.
 				def initialize(title_html, level, anchor)
 					@title_html = title_html
 					@level = level
@@ -90,24 +94,14 @@ module Utopia
 			private
 			
 			def self.extract_headings_from_document(document)
-				headings = []
-				return headings unless document&.root
+				return [] unless document&.root
 				
-				document.root.walk do |node|
-					if node.type == :header
-						next if node.header_level < 2 or node.header_level > 3
-						
-						fragment = node.dup.extract_children
-						
-						title = XRB::Markup.raw(fragment.to_html)
-						level = node.header_level
-						anchor = Markly::Renderer::HTML.anchor_for(fragment)
-						
-						headings << Entry.new(title, level, anchor)
-					end
+				Markly::Renderer::Headings.extract(document.root, min_level: 2, max_level: 3).map do |heading|
+					fragment = heading.node.dup.extract_children
+					title = XRB::Markup.raw(fragment.to_html)
+					
+					Entry.new(title, heading.level, heading.anchor)
 				end
-				
-				headings
 			end
 		end
 	end

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.39.0"
+		VERSION = "0.41.0"
 	end
 end

data/lib/utopia/project.rb

@@ -1,18 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "utopia/project/version"
 
 require "variant"
 
+require "utopia/application"
+require "utopia/content"
+require "utopia/controller"
+require "utopia/exceptions"
 require "utopia/localization"
+require "utopia/redirection"
+require "utopia/static"
 
 require_relative "project/base"
 require_relative "project/import_map"
 
+# @namespace
 module Utopia
+	# Provides project documentation generation and rendering.
 	module Project
 		# The root directory of the web application files.
 		SITE_ROOT = File.expand_path("../..", __dir__)
@@ -23,9 +31,9 @@ module Utopia
 		# The root directory for static assets.
 		PUBLIC_ROOT = File.expand_path("public", SITE_ROOT)
 		
-		# Appends a project application to the rack builder.
+		# Appends a project application to the protocol HTTP middleware builder.
 		#
-		# @parameter builder [Rack::Builder]
+		# @parameter builder [Protocol::HTTP::Middleware::Builder]
 		# @parameter root [String] The file-system root path of the project/gem.
 		# @parameter locales [Array(String)] an array of locales to support, e.g. `['en', 'ja']`.
 		def self.call(builder, root = Dir.pwd, locales: nil)
@@ -33,9 +41,6 @@ module Utopia
 				# Handle exceptions in production with a error page and send an email notification:
 				builder.use Utopia::Exceptions::Handler
 				builder.use Utopia::Exceptions::Mailer
-			else
-				# We want to propate exceptions up when running tests:
-				builder.use Rack::ShowExceptions unless UTOPIA.testing?
 			end
 			
 			# We serve static files from the project root:
@@ -46,7 +51,6 @@ module Utopia
 			builder.use Utopia::Redirection::Rewrite, {
 				"/" => "/index"
 			}
-			
 			builder.use Utopia::Redirection::DirectoryIndex
 			
 			builder.use Utopia::Redirection::Errors, {
@@ -67,7 +71,6 @@ module Utopia
 				# 'gallery' => Utopia::Gallery::Tags.new
 			}
 			
-			builder.run lambda {|env| [404, {}, []]}
 		end
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2020-2025, by Samuel Williams.  
+Copyright, 2020-2026, by Samuel Williams.  
 Copyright, 2020, by Olle Jonsson.  
 Copyright, 2022-2023, by dependabot[bot].  
 Copyright, 2023, by Michael Adams.  

data/pages/_header.xnode

@@ -6,7 +6,7 @@
 			path = path + "index"
 		end
 		
-		if link = links(path.dirname, name: path.last, locale: localization.current_locale, indices: true).first
+		if link = links(path.dirname, name: path.last, locale: localization&.locale, indices: true).first
 			if replace = link[:replace]&.to_sym and base = controller[:base]
 				?> &rsaquo; #{link.to_href(content: base.public_send(replace))}<?r
 			else
@@ -30,11 +30,11 @@
 		?> &rsaquo; <a href="/guides/#{guide.name}/index">#{guide.title}</a> <?r
 	end
 
-	if localization.localized?
+	if localization&.localized?
 		?> &bull; (<?r
 		localization.all_locales.each.with_index do |locale, index|
 			?>#{index.zero? ? '' : ' '}<a href="#{localization.localized_path(page_path, locale)}">#{locale}</a><?r
 		end
 		?>)<?r
 	end
-?></header>
+?></header>

data/pages/_page.xnode

@@ -15,7 +15,7 @@
 		<link rel="icon" type="image/png" href="/_static/icon.png" />
 		<link rel="stylesheet" href="/_static/site.css" type="text/css" media="screen" />
 		
-		#{Utopia::Project::IMPORT_MAP.relative_to(request.env["REQUEST_PATH"]).to_html}
+		#{Utopia::Project::IMPORT_MAP.relative_to(request.request_path).to_html}
 		<script type="module" src="/_static/application.js"></script>
 	</head>
 	<body>

data/pages/_usage.xnode

@@ -3,7 +3,7 @@
 <?r
 	base = self[:base]
 	
-	base.guides do |guide|
+	base.guides.each do |guide|
 ?>
 	<section>
 		<h3><a href="#{guide.href}">#{guide.title}</a></h3>
@@ -18,4 +18,4 @@
 	</section>
 <?r
 	end
-?>
+?>

data/pages/guides/index.xnode

@@ -1,16 +1,25 @@
 <content:page>
-	<?r
-		base = self[:base]
-	?>
 	<content:heading>Guides</content:heading>
 	
-	<ul>
+	<section>
 		<?r
-		base = controller[:base]
+		base = self[:base]
 		
-		base.guides do |guide|
-			?><li><a href="#{guide.name}/">#{guide.title}</a></li><?r
+		base.guides.each do |guide|
+		?>
+		<section>
+			<h3><a href="#{guide.href}">#{guide.title}</a></h3>
+			
+			<?r if description = guide.description ?>
+				#{Markup.raw description.to_html}
+			<?r elsif documentation = guide.documentation ?>
+				#{base.format(documentation.text, language: guide.documentation.language)}
+			<?r else ?>
+				<p>No description.</p>
+			<?r end ?>
+		</section>
+		<?r
 		end
 		?>
-	</ul>
+	</section>
 </content:page>

data/pages/guides/show.xnode

@@ -9,6 +9,24 @@
 		#{navigation.to_html}
 	</aside>
 	<div class="content">
+		<?r
+			previous_guide, next_guide = base.guides.related(guide)
+			
+			if previous_guide or next_guide
+				?>
+				<nav class="top">
+					<?r if previous_guide
+						?><a href="#{previous_guide.href}" class="previous">← #{previous_guide.title}</a><?r
+					end
+					
+					if next_guide
+						?><a href="#{next_guide.href}" class="next">#{next_guide.title} →</a><?r
+					end ?>
+				</nav>
+				<?r
+			end
+		?>
+		
 		<content:heading>#{guide.title}</content:heading>
 		
 		<?r
@@ -27,5 +45,21 @@
 				end
 			end
 		?>
+		
+		<?r
+			if previous_guide or next_guide
+				?>
+				<nav class="bottom">
+					<?r if previous_guide
+						?><a href="#{previous_guide.href}" class="previous">← #{previous_guide.title}</a><?r
+					end
+					
+					if next_guide
+						?><a href="#{next_guide.href}" class="next">#{next_guide.title} →</a><?r
+					end ?>
+				</nav>
+				<?r
+			end
+		?>
 	</div>
 </content:page>

data/pages/source/_signature.xnode

@@ -3,7 +3,21 @@
 	symbol = self[:symbol]
 	documentation = symbol&.documentation
 	
+	# Check if there are any non-Example children before rendering:
+	has_signature_children = false
 	if documentation&.children?
+		documentation.traverse do |node, descend|
+			node.each do |child|
+				unless child.is_a?(Decode::Comment::Example)
+					has_signature_children = true
+					break
+				end
+			end
+			break if has_signature_children
+		end
+	end
+	
+	if has_signature_children
 ?>
 <details open>
 	<summary><h4>Signature</h4></summary>

data/public/_static/site.css

@@ -594,3 +594,37 @@ ul.pragmas li.asynchronous {
 	border-left-color: var(--accent-color);
 	font-weight: 500;
 }
+
+/* Guide navigation (previous/next) */
+.content nav {
+	display: flex;
+	justify-content: space-between;
+	gap: 1rem;
+	margin: 1rem;
+	font-size: 0.9rem;
+	font-weight: 500;
+}
+
+.content nav.top {
+	border-bottom: 1px solid var(--underlay-color);
+	padding-bottom: 0.5rem;
+}
+
+.content nav.bottom {
+	border-top: 1px solid var(--underlay-color);
+	padding-top: 0.5rem;
+}
+
+.content nav .next {
+	margin-left: auto;
+}
+
+@media (max-width: 768px) {
+	.content nav {
+		flex-direction: column;
+	}
+	
+	.content nav .next {
+		margin-left: 0;
+	}
+}

data/readme.md

@@ -33,6 +33,17 @@ Please see the [project documentation](https://socketry.github.io/utopia-project
 
 Please see the [project releases](https://socketry.github.io/utopia-project/releases/index) for all releases.
 
+### v0.41.0
+
+  - Don't render empty signature block when there are only examples.
+  - Use protocol HTTP middleware for serving and testing project documentation.
+
+### v0.40.0
+
+  - Fixed duplicate heading IDs when multiple sections have the same title. Permalinks and sidebar scroll tracking now work correctly when you have headings with identical text in different sections (e.g., multiple "Deployment" subsections under "Kubernetes" and "Systemd").
+  - Improved guides index page to show guide summaries (first paragraph) instead of just listing titles.
+  - Added previous/next navigation at the top and bottom of guide pages for easier sequential reading.
+
 ### v0.37.3
 
   - Support for `@example` pragmas from the `decode` gem, allowing inline code examples to be rendered in API documentation.
@@ -65,14 +76,6 @@ Please see the [project releases](https://socketry.github.io/utopia-project/rele
 
   - Support brief release notes in `releases.md` document.
 
-### v0.30.0
-
-  - [Rename `changes.md` to `releases.md`](https://socketry.github.io/utopia-project/releases/index#rename-changes.md-to-releases.md)
-
-### v0.29.0
-
-  - [Improve `changes.md` document organization](https://socketry.github.io/utopia-project/releases/index#improve-changes.md-document-organization)
-
 ## See Also
 
   - [Utopia](https://github.com/socketry/utopia) — The website framework which powers this web application.
@@ -82,11 +85,27 @@ Please see the [project releases](https://socketry.github.io/utopia-project/rele
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
 
 ### Developer Certificate of Origin
 

data/releases.md

@@ -1,5 +1,16 @@
 # Changes
 
+## v0.41.0
+
+  - Don't render empty signature block when there are only examples.
+  - Use protocol HTTP middleware for serving and testing project documentation.
+
+## v0.40.0
+
+  - Fixed duplicate heading IDs when multiple sections have the same title. Permalinks and sidebar scroll tracking now work correctly when you have headings with identical text in different sections (e.g., multiple "Deployment" subsections under "Kubernetes" and "Systemd").
+  - Improved guides index page to show guide summaries (first paragraph) instead of just listing titles.
+  - Added previous/next navigation at the top and bottom of guide pages for easier sequential reading.
+
 ## v0.37.3
 
   - Support for `@example` pragmas from the `decode` gem, allowing inline code examples to be rendered in API documentation.

data/template/config/application.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "environment"
+
+require "utopia/project"
+
+Application = Utopia::Application.build do |builder|
+	Utopia::Project.call(builder)
+end

data/template/config/environment.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2026, by Samuel Williams.
+
+require "utopia/setup"
+
+UTOPIA ||= Utopia.setup(File.expand_path("..", __dir__))

data/template/config/serve.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "utopia/application"
+
+run Utopia::Application.load(File.expand_path("application.rb", __dir__))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.41.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -75,28 +75,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: rackula
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0.15'
 - !ruby/object:Gem::Dependency
   name: thread-local
   requirement: !ruby/object:Gem::Requirement
@@ -117,14 +103,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.32'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.32'
+        version: '3.0'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -142,6 +128,7 @@ files:
 - lib/utopia/project/base.rb
 - lib/utopia/project/document.rb
 - lib/utopia/project/guide.rb
+- lib/utopia/project/guides.rb
 - lib/utopia/project/import_map.rb
 - lib/utopia/project/linkify.rb
 - lib/utopia/project/releases_document.rb
@@ -673,7 +660,9 @@ files:
 - public/robots.txt
 - readme.md
 - releases.md
-- template/config.ru
+- template/config/application.rb
+- template/config/environment.rb
+- template/config/serve.rb
 - template/gems.rb
 - template/preload.rb
 homepage: https://socketry.github.io/utopia-project
@@ -690,14 +679,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A project documentation tool based on Utopia.
 test_files: []

data/template/config.ru

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-require "utopia/setup"
-UTOPIA ||= Utopia.setup(Dir.pwd)
-
-require "utopia/project"
-Utopia::Project.call(self)