utopia-project 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 684a750f24a6ee8464e5d0f9a8d97ddca456faad4370660a7cc89af4893f7e0e
-  data.tar.gz: f01d30c525b3a4dacb0fb2533580a45cc437eac597f26a907ccdb2a1784708e7
+  metadata.gz: 75761109578cafa260705da53ebe35f0cdf617339e4291aa5e45ac0ee732a598
+  data.tar.gz: 01e21571bdb13616d8fe59618c83ee85d689f3519919adf980377118cfc912e6
 SHA512:
-  metadata.gz: 56fa2bab4641e1731846878b80af87d21150b9b66cff416cf1a58969fbcd5b8baf688c1e70a5440cb33518b7147761050511e253c5a7705769d9b72b601656c3
-  data.tar.gz: 8c1e81410e786b271a94a6850eb747b4908458565c116eeb3b62d9584cfd3fe0dcec8233cf7aeec7b549421e78513db7e07c623dcfdddf5e3ddcf395af89ec21
+  metadata.gz: 5083d276b08113645f82979721c42fd02167373ca4402aa236b96c16620f4b063f1e8ab910a3f4bd58bcaa079c506a38f4c861546eba054a377d772549de0619
+  data.tar.gz: f1df6623efe3335d6db6888a958d5dcc345e08279b2ca4f5d818d66328884ada55dcbcf87e4bfb8e4199284b309961f9c1b3d9f8d8e66bf5efc0dc2010e2dcd1

data/bake/utopia/project.rb

@@ -39,7 +39,7 @@ def serve(port: nil, bind: nil)
 	end
 	
 	if port
-		options << "--port" << port
+		options << "--port" << port.to_s
 	end
 	
 	system("falcon", "serve", "--config", config_path, "--preload", preload_path, *options)

data/lib/utopia/project/guide.rb

@@ -7,6 +7,8 @@ require "utopia/path"
 require "xrb/reference"
 require "decode"
 
+require_relative "sidebar"
+
 module Utopia
 	module Project
 		# Provides structured access to a directory which contains documentation and source code to explain a specific process.
@@ -127,6 +129,12 @@ module Utopia
 				@documentation ||= self.best_documentation
 			end
 			
+			# Generate a navigation from the guide's document.
+			# @returns [Sidebar]
+			def navigation
+				@navigation ||= Sidebar.build(self.document)
+			end
+			
 			# All files associated with this guide.
 			# @returns [Array(String)] The file-system paths.
 			def files

data/lib/utopia/project/releases_document.rb

@@ -4,6 +4,7 @@
 # Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "document"
+require_relative "sidebar"
 
 module Utopia
 	module Project
@@ -107,6 +108,19 @@ module Utopia
 					yield release(name)
 				end
 			end
+			
+			# Generate a navigation from the releases.
+			# @returns [Sidebar]
+			def navigation
+				@navigation ||= begin
+					entries = release_names.map do |name|
+						anchor = name.downcase.gsub(/\s+/, "-")
+						Sidebar::Entry.new(name, 2, anchor)
+					end
+					
+					Sidebar.new(entries)
+				end
+			end
 		end
 	end
 end

data/lib/utopia/project/sidebar.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020-2025, by Samuel Williams.
+
+module Utopia
+	module Project
+		# Generates a sidebar navigation from markdown document headings.
+		class Sidebar
+			# Represents a sidebar navigation entry with title, level, and anchor.
+			class Entry
+				def initialize(title, level, anchor)
+					@title = title
+					@level = level
+					@anchor = anchor
+				end
+				
+				# The text content of the heading.
+				# @attribute [String]
+				attr :title
+				
+				# The heading level (1-6).
+				# @attribute [Integer]
+				attr :level
+				
+				# The anchor ID for linking to this heading.
+				# @attribute [String]
+				attr :anchor
+			end
+			# Build a sidebar from a markdown document by extracting headings.
+			# @parameter document [Document] The document to extract headings from
+			# @returns [Sidebar]
+			def self.build(document)
+				entries = extract_headings_from_document(document)
+				new(entries)
+			end
+			
+			# Initialize with an array of entries.
+			# @parameter entries [Array(Entry)] The navigation entries
+			def initialize(entries)
+				@entries = entries
+			end
+			
+			# The navigation entries.
+			# @attribute [Array(Entry)]
+			attr :entries
+			
+			# Check if there are any navigation entries.
+			# @returns [Boolean]
+			def any?
+				!entries.empty?
+			end
+			
+			# Generate HTML markup for the sidebar navigation.
+			# @parameter sidebar [Boolean] Whether this is rendered in a sidebar layout (unused, kept for compatibility)
+			# @parameter title [String] The title for the navigation section
+			# @returns [XRB::MarkupString]
+			def to_html(sidebar: false, title: "Table of Contents")
+				return XRB::Markup.raw("") unless any?
+				
+				XRB::Builder.fragment do |builder|
+					builder.tag :nav do
+						builder.tag :heading do
+							builder.text title
+						end
+						builder.tag :ul do
+							entries.each do |entry|
+								if entry.level > 2
+									builder.tag :li, {class: "level-#{entry.level}"} do
+										builder.tag :a, {href: "##{entry.anchor}"} do
+											builder.text entry.title
+										end
+									end
+								else
+									builder.tag :li do
+										builder.tag :a, {href: "##{entry.anchor}"} do
+											builder.text entry.title
+										end
+									end
+								end
+							end
+						end
+					end
+				end
+			end
+			
+			private
+			
+			def self.extract_headings_from_document(document)
+				headings = []
+				return headings unless document&.root
+				
+				document.root.walk do |node|
+					if node.type == :header
+						title = node.first_child&.to_plaintext
+						level = node.header_level
+						anchor = generate_anchor(title)
+						
+						# Only include H2 and below in sidebar (skip H1 main title)
+						if title && !title.empty? && level >= 2
+							headings << Entry.new(title, level, anchor)
+						end
+					end
+				end
+				
+				headings
+			end
+			
+			def self.generate_anchor(title)
+				# Generate anchor ID exactly like Markly renderer does it
+				title.downcase
+					.gsub(/\s+/, "-")     # Replace spaces with hyphens
+					.gsub("&", "&amp;")   # HTML encode ampersand
+					.gsub('"', "&quot;")  # HTML encode quotes
+					.gsub("'", "&#39;")   # HTML encode single quotes
+					.gsub("<", "&lt;")    # HTML encode less than
+					.gsub(">", "&gt;")    # HTML encode greater than
+			end
+			
+		end
+	end
+end

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.36.0"
+		VERSION = "0.37.0"
 	end
 end

data/pages/_page.xnode

@@ -39,10 +39,8 @@
 	<body>
 		<content:header />
 		
-		<main>
+		<main class="#{attributes[:class]}">
 			<utopia:content/>
-				
-			<footer>Documentation generated by <a href="https://github.com/socketry/utopia-project">Utopia::Project</a>.</footer>
 		</main>
 	</body>
 </html>

data/pages/guides/show.xnode

@@ -1,24 +1,32 @@
-<content:page>
+<content:page class="with-sidebar">
 	<?r
 		base = self[:base]
 		guide = self[:guide]
+		navigation = guide.navigation
 	?>
-	<content:heading>#{guide.title}</content:heading>
 	
-	<?r
-		if document = guide.document
-			?>#{document.to_html}<?r
-		end
+	<aside class="sidebar">
+		#{navigation.to_html}
+	</aside>
+	<div class="content">
+		<content:heading>#{guide.title}</content:heading>
 		
-		guide.sources.each do |source|
-			?><h2><code>#{File.basename source.path}</code></h2><?r
-			source.segments.each do |segment|
-				if documentation = segment.documentation
-					?>#{base.format(documentation.text, language: source.language)}<?r
+		<?r
+			if document = guide.document
+				?>#{document.to_html}<?r
+			end
+			
+			guide.sources.each do |source|
+				?><h2><code>#{File.basename source.path}</code></h2><?r
+				source.segments.each do |segment|
+					if documentation = segment.documentation
+						?>#{base.format(documentation.text, language: source.language)}<?r
+					end
+					
+					?><pre><code class="language-#{source.language.name}">#{segment.code}</code></pre><?r
 				end
-				
-				?><pre><code class="language-#{source.language.name}">#{segment.code}</code></pre><?r
 			end
-		end
-	?>
+		?>
+	</div>
+	<script src="/_static/sidebar.js"></script>
 </content:page>

data/pages/releases/index.xnode

@@ -1,13 +1,18 @@
-<content:page>
-	<?r
-	if document = self[:document]
-		?>#{Markup.raw document.to_html}<?r
-	else
-		?>
-		<content:heading>Project</content:heading>
+<?r if document = self[:document] ?>
+	<content:page class="with-sidebar">
+		<?r navigation = document.navigation ?>
+		<aside class="sidebar">
+			#{navigation.to_html(sidebar: true, title: "Releases")}
+		</aside>
+		<div class="content">
+			#{Markup.raw document.to_html}
+		</div>
+		<script src="/_static/sidebar.js"></script>
+	</content:page>
+<?r else ?>
+	<content:page>
+		<content:heading>Releases</content:heading>
 		
 		<p>This project does not have a <code>releases.md</code> file.</p>
-		<?r
-	end
-	?>
-</content:page>
+	</content:page>
+<?r end ?>

data/public/_static/sidebar.js

@@ -0,0 +1,175 @@
+/**
+ * Sidebar Navigation Highlighting
+ * Progressive enhancement for sidebar navigation with scroll tracking
+ */
+
+(function() {
+	'use strict';
+	
+	// Only run if we have a sidebar navigation
+	const sidebarNav = document.querySelector('.sidebar nav');
+	if (!sidebarNav) return;
+	
+	const navLinks = sidebarNav.querySelectorAll('a[href*="#"]');
+	const sections = Array.from(navLinks).map(link => {
+		const href = link.getAttribute('href');
+		// Extract fragment from both "#section" and "page.html#section" formats
+		const fragmentIndex = href.indexOf('#');
+		if (fragmentIndex === -1) return null;
+		const fragment = href.substring(fragmentIndex + 1);
+		// Try to find the section element using the fragment
+		let sectionElement = document.getElementById(fragment);
+		
+		// If not found, try with CSS.escape for special characters
+		if (!sectionElement && fragment !== CSS.escape(fragment)) {
+			sectionElement = document.querySelector(`#${CSS.escape(fragment)}`);
+		}
+		
+		// The element we found should be the section container, not just the heading
+		// If it's a heading, find its parent section
+		if (sectionElement && sectionElement.tagName.match(/^H[1-6]$/)) {
+			sectionElement = sectionElement.closest('section') || sectionElement.parentElement;
+		}
+		
+		return { link, sectionElement, id: fragment };
+	}).filter(item => item && item.sectionElement);
+	
+	if (sections.length === 0) return;
+	
+	let currentActive = null;
+	
+	function updateActiveLink(updatePageState = true) {
+		let activeSectionData = null;
+		let smallestValidBottom = Infinity;
+		
+		// Find the section with the smallest bottom position that is still >= 0
+		// This gives us the section that we're currently reading through
+		sections.forEach((sectionData) => {
+			const { sectionElement } = sectionData;
+			const rect = sectionElement.getBoundingClientRect();
+			const sectionBottom = rect.bottom;
+			
+			// Get the actual bottom padding for this section
+			const bottomPadding = parseFloat(getComputedStyle(sectionElement).paddingBottom);
+			
+			// We want the section whose bottom is closest to the top but still visible
+			if (sectionBottom > bottomPadding && sectionBottom < smallestValidBottom) {
+				smallestValidBottom = sectionBottom;
+				activeSectionData = sectionData;
+			}
+		});
+		
+		// If no section has bottom >= 0, fall back to the last section
+		// (meaning we've scrolled past all content)
+		if (!activeSectionData && sections.length > 0) {
+			activeSectionData = sections[sections.length - 1];
+		}
+		
+		// Update active link
+		if (activeSectionData !== currentActive) {
+			// Remove previous active
+			if (currentActive) {
+				currentActive.link.classList.remove('active');
+			}
+			
+			// Set new active
+			if (activeSectionData) {
+				activeSectionData.link.classList.add('active');
+				currentActive = activeSectionData;
+				
+				if (updatePageState) {
+					// Update URL fragment to reflect current section
+					const newFragment = '#' + activeSectionData.id;
+					if (window.location.hash !== newFragment) {
+						history.replaceState(null, null, newFragment);
+					}
+					
+					// Auto-scroll sidebar to keep active item visible
+					scrollToActiveItem(activeSectionData.link);
+				}
+			} else {
+				currentActive = null;
+				
+				if (updatePageState) {
+					// Clear fragment if no active section
+					if (window.location.hash) {
+						history.replaceState(null, null, window.location.pathname);
+					}
+				}
+			}
+		}
+	}
+	
+	function scrollToActiveItem(activeLink) {
+		const sidebar = activeLink.closest('.sidebar');
+		if (!sidebar) return;
+		
+		const sidebarRect = sidebar.getBoundingClientRect();
+		const linkRect = activeLink.getBoundingClientRect();
+		
+		// Check if the active link is outside the visible area
+		const isAbove = linkRect.top < sidebarRect.top;
+		const isBelow = linkRect.bottom > sidebarRect.bottom;
+		
+		if (isAbove || isBelow) {
+			// Calculate the ideal scroll position to center the active item
+			const sidebarScrollTop = sidebar.scrollTop;
+			const linkOffsetTop = linkRect.top - sidebarRect.top + sidebarScrollTop;
+			const sidebarHeight = sidebarRect.height;
+			const targetScrollTop = linkOffsetTop - (sidebarHeight / 2) + (linkRect.height / 2);
+			
+			// Smooth scroll the sidebar
+			sidebar.scrollTo({
+				top: Math.max(0, targetScrollTop),
+				behavior: 'smooth'
+			});
+		}
+	}
+	
+	// Throttled scroll handler
+	let scrollTimer = null;
+	
+	function onScroll() {
+		if (scrollTimer) return;
+		
+		scrollTimer = setTimeout(() => {
+			updateActiveLink();
+			scrollTimer = null;
+		}, 100);
+	}
+	
+	// Initialize and set up event listeners
+	window.addEventListener('scroll', onScroll, { passive: true });
+	window.addEventListener('resize', updateActiveLink, { passive: true });
+	
+	// Initial update without changing page state (preserves URL fragments):
+	updateActiveLink(false);
+	
+	// Smooth scroll enhancement for sidebar navigation links
+	navLinks.forEach(link => {
+		link.addEventListener('click', (event) => {
+			const href = link.getAttribute('href');
+			// Extract fragment from both "#section" and "page.html#section" formats
+			const fragmentIndex = href.indexOf('#');
+			if (fragmentIndex === -1) return;
+			const fragment = href.substring(fragmentIndex + 1);
+			
+			// Try to find the target using the fragment
+			let target = document.getElementById(fragment);
+			
+			// If not found, try with CSS.escape for special characters
+			if (!target && fragment !== CSS.escape(fragment)) {
+				target = document.querySelector(`#${CSS.escape(fragment)}`);
+			}
+			
+			if (target) {
+				event.preventDefault();
+				
+				// Update URL to trigger :target and let browser handle scrolling
+				window.location.hash = fragment;
+			}
+
+			link.focus();
+		});
+	});
+})();

data/public/_static/site.css

@@ -103,21 +103,118 @@ main {
 	max-width: 48rem;
 }
 
+@media (min-width: 64em) {
+	main.with-sidebar {
+		display: grid;
+		grid-template-columns: 16rem 1fr;
+		gap: 1rem;
+		align-items: start;
+
+		 /* 48rem content + 16rem sidebar + 1rem gap */
+		max-width: 65rem;
+	}
+	
+	main.with-sidebar .content {
+		max-width: 48rem;
+	}
+}
+
+.sidebar {
+	display: none; /* Hidden on small screens */
+}
+
+@media (min-width: 64em) {
+	.sidebar {
+		display: block;
+		position: sticky;
+		top: 2rem;
+		max-height: calc(100vh - 4rem);
+		overflow-y: auto;
+		
+		/* Custom scrollbar styling */
+		scrollbar-width: thin;
+		scrollbar-color: var(--underlay-color) transparent;
+	}
+}
+
+/* Sidebar navigation styles */
+.sidebar nav {
+	background-color: transparent;
+	border: none;
+	border-radius: 0;
+	padding: 0;
+	margin: 1rem;
+	position: sticky;
+	top: 0;
+}
+
+.sidebar nav h2 {
+	font-size: 0.9rem;
+	margin-bottom: 1rem;
+	padding-bottom: 0.5rem;
+	border-bottom: 1px solid var(--underlay-color);
+}
+
+.sidebar nav ul {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.sidebar nav li {
+	margin: 0.1rem 0;
+}
+
+.sidebar nav li.level-2 {
+	padding-left: 0;
+}
+
+.sidebar nav li.level-3 {
+	padding-left: 1rem;
+}
+
+.sidebar nav li.level-4 {
+	padding-left: 2rem;
+}
+
+.sidebar nav li.level-5 {
+	padding-left: 3rem;
+}
+
+.sidebar nav li.level-6 {
+	padding-left: 4rem;
+}
+
+.sidebar nav a {
+	padding: 0.4rem 0.75rem;
+	font-size: 0.9rem;
+	border-left: 3px solid transparent;
+	color: var(--main-color);
+	text-decoration: none;
+	display: block;
+	border-radius: 0.25rem;
+	transition: all 0.2s ease;
+}
+
+.sidebar nav a:hover {
+	border-left-color: var(--accent-color);
+	background-color: var(--header-color);
+}
+
 main img {
 	max-width: 100%;
 }
 
-:target {
-	background-color: var(--header-color);
+/* Ensure last section has enough height to be scrollable */
+.content section:last-of-type {
+	min-height: 100vh;
 }
 
 section {
-	border-radius: 1rem;
-	padding: 0.1rem 0;
+	padding: 1rem 0;
 }
 
 main > section {
-	border-radius: 1rem;
 	margin: 4rem 0;
 }
 
@@ -223,7 +320,7 @@ summary {
 }
 
 details[open] {
-	/* padding: .5rem; */
+	padding: .5rem;
 }
 
 details[open] summary {
@@ -313,3 +410,191 @@ ul.pragmas li.asynchronous {
 	box-shadow: 0 0 0.3rem #8C00FF;
 	color: #8C00FF;
 }
+
+/* Navigation - Inline styles (boxed display for small screens) */
+.inline-nav nav {
+	background-color: var(--header-color);
+	border-radius: 0.5rem;
+	padding: 1rem;
+	margin: 1rem;
+	border-left: 0.25rem solid var(--accent-color);
+}
+
+.inline-nav nav heading {
+	margin-top: 0;
+	margin-bottom: 0.5rem;
+	color: var(--accent-color);
+	font-size: 1rem;
+	display: block;
+	font-weight: 500;
+}
+
+.inline-nav nav ul {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.inline-nav nav li {
+	margin: 0.25rem 0;
+}
+
+.inline-nav nav li.level-2 {
+	padding-left: 0;
+}
+
+.inline-nav nav li.level-3 {
+	padding-left: 1rem;
+}
+
+.inline-nav nav li.level-4 {
+	padding-left: 2rem;
+}
+
+.inline-nav nav li.level-5 {
+	padding-left: 3rem;
+}
+
+.inline-nav nav li.level-6 {
+	padding-left: 4rem;
+}
+
+.inline-nav nav a {
+	color: var(--main-color);
+	text-decoration: none;
+	display: block;
+	padding: 0.25rem 0.5rem;
+	border-radius: 0.25rem;
+	transition: all 0.2s ease;
+}
+
+.inline-nav nav a:hover {
+	color: var(--accent-hover-color);
+	background-color: var(--overlay-color);
+	text-decoration: none;
+}
+
+/* Sidebar navigation styles */
+.sidebar nav,
+.sidebar details nav {
+	background-color: transparent;
+	border: none;
+	border-radius: 0;
+	padding: 0;
+	margin: 1rem;
+	position: sticky;
+	top: 0;
+}
+
+.sidebar nav heading {
+	font-size: 0.9rem;
+	margin-bottom: 1rem;
+	padding-bottom: 0.5rem;
+	border-bottom: 1px solid var(--underlay-color);
+	display: block;
+	font-weight: 500;
+	color: var(--accent-color);
+}
+
+.sidebar nav li,
+.sidebar details nav li {
+	margin: 0.1rem 0;
+}
+
+.sidebar nav li.level-2 {
+	padding-left: 0;
+}
+
+.sidebar nav li.level-3 {
+	padding-left: 1rem;
+}
+
+.sidebar nav li.level-4 {
+	padding-left: 2rem;
+}
+
+.sidebar nav li.level-5 {
+	padding-left: 3rem;
+}
+
+.sidebar nav li.level-6 {
+	padding-left: 4rem;
+}
+
+.sidebar nav a,
+.sidebar details nav a {
+	padding: 0.4rem 0.75rem;
+	font-size: 0.9rem;
+	border-left: 3px solid transparent;
+	color: var(--main-color);
+	text-decoration: none;
+	display: block;
+	border-radius: 0.25rem;
+	transition: all 0.2s ease;
+}
+
+/* Compact mode for long navigation lists */
+.sidebar nav.compact li {
+	margin: 0.05rem 0;
+}
+
+.sidebar nav.compact a {
+	padding: 0.25rem 0.5rem;
+	font-size: 0.85rem;
+	line-height: 1.3;
+}
+
+.sidebar nav.compact heading {
+	font-size: 0.8rem;
+	margin-bottom: 0.75rem;
+}
+
+.sidebar nav.compact li.level-3 {
+	padding-left: 0.75rem;
+}
+
+.sidebar nav.compact li.level-4 {
+	padding-left: 1.5rem;
+}
+
+.sidebar nav.compact li.level-5 {
+	padding-left: 2.25rem;
+}
+
+.sidebar nav.compact li.level-6 {
+	padding-left: 3rem;
+}
+
+.sidebar nav ul {
+	margin: 0;
+	padding: 0;
+	list-style: none;
+}
+
+.sidebar nav a:hover {
+	border-left-color: var(--accent-color);
+	background-color: var(--header-color);
+}
+
+/* Subtle focus indicator for keyboard navigation */
+.sidebar nav a:focus {
+	outline: 2px solid var(--accent-color);
+	outline-offset: 2px;
+	border-radius: 0.25rem;
+}
+
+/* Brief click feedback */
+.sidebar nav a:active {
+	background-color: var(--accent-hover-color);
+	color: white;
+	transform: scale(0.98);
+	transition: transform 0.1s ease;
+}
+
+/* Active section highlighting (set by JavaScript) */
+.sidebar nav a.active {
+	background-color: var(--accent-color);
+	color: white;
+	border-left-color: var(--accent-color);
+	font-weight: 500;
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -144,6 +144,7 @@ files:
 - lib/utopia/project/linkify.rb
 - lib/utopia/project/releases_document.rb
 - lib/utopia/project/renderer.rb
+- lib/utopia/project/sidebar.rb
 - lib/utopia/project/version.rb
 - license.md
 - pages/_header.xnode
@@ -255,6 +256,7 @@ files:
 - public/_components/mermaid/mermaid.min.js.map
 - public/_static/icon.png
 - public/_static/links.js
+- public/_static/sidebar.js
 - public/_static/site.css
 - public/robots.txt
 - readme.md