utopia-project 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21be268fb201720abe3d699eba3f8a71ebee79896293f8aaa0861a592d650dab
-  data.tar.gz: 93c814b9d849ad90d3a7761cf6d4c9bd2713293fb7de7bb48b5b2f28b3c8b34d
+  metadata.gz: 9857e236b8690b3e3c8ae113309fdf2af695222643cc998bcac8862c09232465
+  data.tar.gz: b8ccb22331616e6f1ff287c067bf22ace7148c7627a6be9209be9c86f928a87d
 SHA512:
-  metadata.gz: b0ece167920bd1069f74879b53a1844948808613e6865ecc3984861c9d6c6fe89bb9d2b98e60cb545523c488c8d5c439f8f5ff7a3b589a54222225272c3837f7
-  data.tar.gz: 885452bfa693632fae6fedb2970ec85575e7633fe2f98c62f06195f524f3fb4d27333b7eb399abfeb33455b5e6a4a390393a8163e526d5534f2528544048de68
+  metadata.gz: c9e2c1640bb841704474c7bf6e3bf1a077fa9eae05267fb45874ea5b07c2beefcdfd92011d152e55db42fff3a1b037611355ddcd94e9f43b6425049f765e4741
+  data.tar.gz: 21796bcb1f5844dce244d0421a92d86ee3e25a0bf8daa05e12e6c41103fbc0e64f6703f8de664e1ce1110509876f0073850e55980c95847a8c492959ec14da3c

data/lib/utopia/project/base.rb

@@ -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
@@ -193,10 +193,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,15 +202,7 @@ 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
 			
 			def readme_document

data/lib/utopia/project/guides.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, 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,5 @@
+# frozen_string_literal: true
+
 require "utopia/import_map"
 
 module Utopia

data/lib/utopia/project/sidebar.rb

@@ -90,24 +90,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.40.0"
 	end
 end

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/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,12 @@ 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.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.
@@ -69,10 +75,6 @@ Please see the [project releases](https://socketry.github.io/utopia-project/rele
 
   - [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.

data/releases.md

@@ -1,5 +1,11 @@
 # Changes
 
+## 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -75,14 +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'
+        version: '0.15'
 - !ruby/object:Gem::Dependency
   name: rackula
   requirement: !ruby/object:Gem::Requirement
@@ -142,6 +142,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
@@ -697,7 +698,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A project documentation tool based on Utopia.
 test_files: []