utopia-project 0.38.0 → 0.40.0

data/public/_static/sidebar.js

@@ -3,77 +3,116 @@
  * 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*="#"]');
-	
-	// Build a map of sidebar links by their fragment IDs
-	const sidebarLinksByFragment = new Map();
-	navLinks.forEach(link => {
-		const href = link.getAttribute('href');
-		const fragmentIndex = href.indexOf('#');
-		if (fragmentIndex !== -1) {
-			const fragment = href.substring(fragmentIndex + 1);
-			sidebarLinksByFragment.set(fragment, link);
-		}
-	});
+class SidebarNavigation {
+	static extractFragment(href) {
+		const index = href.indexOf('#');
+		return index !== -1 ? href.substring(index + 1) : null;
+	}
 	
-	if (sidebarLinksByFragment.size === 0) return;
+	constructor(sidebarNav, sidebarLinksByFragment, allSections, sections, navLinks, sectionToSidebarLinkMap) {
+		this.sidebarNav = sidebarNav;
+		this.navLinks = navLinks;
+		this.currentActive = null;
+		this.sidebarLinksByFragment = sidebarLinksByFragment;
+		this.allSections = allSections;
+		this.sections = sections;
+		this.sectionToSidebarLinkMap = sectionToSidebarLinkMap;
+		
+		// Store references for cleanup
+		this.scrollTimer = null;
+		this.scrollHandler = null;
+		this.resizeHandler = null;
+		this.clickHandlers = new Map();
+		
+		// Initialize
+		this.setupEventListeners();
+		
+		// Initial update without changing page state (preserves URL fragments)
+		this.updateActiveLink(false);
+	}
 	
-	// Get all sections/headings on the page and annotate them with their sidebar link
-	const allSections = Array.from(document.querySelectorAll('section, h1, h2, h3, h4, h5, h6'))
-		.filter(el => el.id) // Only keep elements with IDs
-		.map(el => {
-			// Get the section element (section or heading's parent)
-			const sectionElement = el.tagName === 'SECTION' ? el : (el.closest('section') || el.parentElement);
-			return { element: sectionElement, id: el.id };
+	setupEventListeners() {
+		// Throttled scroll handler
+		this.scrollHandler = () => {
+			if (this.scrollTimer) return;
+			
+			this.scrollTimer = setTimeout(() => {
+				this.updateActiveLink();
+				this.scrollTimer = null;
+			}, 100);
+		};
+		
+		this.resizeHandler = () => this.updateActiveLink();
+		
+		// Set up event listeners
+		window.addEventListener('scroll', this.scrollHandler, { passive: true });
+		window.addEventListener('resize', this.resizeHandler, { passive: true });
+		
+		// Smooth scroll enhancement for sidebar navigation links
+		this.navLinks.forEach(link => {
+			const clickHandler = (event) => {
+				const href = link.getAttribute('href');
+				const fragment = SidebarNavigation.extractFragment(href);
+				
+				if (!fragment) return;
+				
+				const target = document.getElementById(fragment);
+				
+				if (target) {
+					event.preventDefault();
+					
+					// Update URL to trigger :target and let browser handle scrolling
+					window.location.hash = fragment;
+					
+					link.focus();
+				}
+			};
+			
+			this.clickHandlers.set(link, clickHandler);
+			link.addEventListener('click', clickHandler);
 		});
+	}
 	
-	// Annotate each section with which sidebar link should be active
-	// Walk through in DOM order and track the "last seen" sidebar link
-	let lastSeenSidebarId = null;
-	allSections.forEach(({element, id}) => {
-		if (sidebarLinksByFragment.has(id)) {
-			// This section has a sidebar link - use it
-			lastSeenSidebarId = id;
-		}
-		// Annotate the section element with the sidebar link to activate
-		if (lastSeenSidebarId) {
-			element.dataset.sidebarLink = lastSeenSidebarId;
+	destroy() {
+		// Clear any pending timer
+		if (this.scrollTimer) {
+			clearTimeout(this.scrollTimer);
+			this.scrollTimer = null;
 		}
-	});
-	
-	// Build sections array with link references for active state tracking
-	const sections = Array.from(sidebarLinksByFragment.entries()).map(([id, link]) => {
-		let sectionElement = document.getElementById(id);
 		
-		if (!sectionElement && id !== CSS.escape(id)) {
-			sectionElement = document.querySelector(`#${CSS.escape(id)}`);
+		// Remove window event listeners
+		if (this.scrollHandler) {
+			window.removeEventListener('scroll', this.scrollHandler);
+			this.scrollHandler = null;
 		}
 		
-		if (sectionElement && sectionElement.tagName.match(/^H[1-6]$/)) {
-			sectionElement = sectionElement.closest('section') || sectionElement.parentElement;
+		if (this.resizeHandler) {
+			window.removeEventListener('resize', this.resizeHandler);
+			this.resizeHandler = null;
 		}
 		
-		return sectionElement ? { link, sectionElement, id } : null;
-	}).filter(Boolean);
-	
-	if (sections.length === 0) return;
-	
-	let currentActive = null;
+		// Remove click handlers from all links
+		this.clickHandlers.forEach((handler, link) => {
+			link.removeEventListener('click', handler);
+		});
+		this.clickHandlers.clear();
+		
+		// Clear the section-to-sidebar-link mapping
+		this.sectionToSidebarLinkMap.clear();
+		
+		// Remove active class from current link
+		if (this.currentActive) {
+			this.currentActive.link.classList.remove('active');
+			this.currentActive = null;
+		}
+	}
 	
-	function updateActiveLink(updatePageState = true) {
-		let activeSectionData = null;
+	findCurrentSection() {
 		let smallestValidBottom = Infinity;
 		let currentSectionElement = null;
 		
 		// Find which section the user is currently viewing
-		allSections.forEach(({element}) => {
+		this.allSections.forEach(({element}) => {
 			const rect = element.getBoundingClientRect();
 			const sectionBottom = rect.bottom;
 			
@@ -87,54 +126,68 @@
 			}
 		});
 		
-		// Look up which sidebar link should be active using the data attribute
-		if (currentSectionElement && currentSectionElement.dataset.sidebarLink) {
-			const sidebarLinkId = currentSectionElement.dataset.sidebarLink;
-			activeSectionData = sections.find(s => s.id === sidebarLinkId);
+		// Look up which sidebar link should be active using the map
+		if (currentSectionElement) {
+			const sidebarLinkId = this.sectionToSidebarLinkMap.get(currentSectionElement);
+			if (sidebarLinkId) {
+				return this.sections.find(s => s.id === sidebarLinkId);
+			}
 		}
 		
-		// If still no section found, fall back to the last section
-		if (!activeSectionData && sections.length > 0) {
-			activeSectionData = sections[sections.length - 1];
+		// If no section found, fall back to the last section
+		return this.sections.length > 0 ? this.sections[this.sections.length - 1] : null;
+	}
+	
+	setActiveSection(activeSectionData) {
+		// Remove previous active
+		if (this.currentActive) {
+			this.currentActive.link.classList.remove('active');
 		}
 		
-		// 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');
+			this.currentActive = activeSectionData;
+		} else {
+			this.currentActive = null;
+		}
+	}
+	
+	updateUrlFragment(sectionId) {
+		if (sectionId) {
+			const newFragment = '#' + sectionId;
+			if (window.location.hash !== newFragment) {
+				history.replaceState(null, null, newFragment);
+			}
+		} else {
+			// Clear fragment if no active section
+			if (window.location.hash) {
+				history.replaceState(null, null, window.location.pathname);
 			}
+		}
+	}
+	
+	updateActiveLink(updatePageState = true) {
+		const activeSectionData = this.findCurrentSection();
+		
+		// Only update if section changed
+		if (activeSectionData !== this.currentActive) {
+			this.setActiveSection(activeSectionData);
 			
-			// 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);
-					}
+			if (updatePageState) {
+				if (activeSectionData) {
+					this.updateUrlFragment(activeSectionData.id);
+					this.scrollToActiveItem(activeSectionData.link);
+				} else {
+					this.updateUrlFragment(null);
 				}
 			}
 		}
 	}
 	
-	function scrollToActiveItem(activeLink) {
-		const sidebar = activeLink.closest('.sidebar');
+	scrollToActiveItem(activeLink) {
+		// Use the sidebar nav container we already have
+		const sidebar = this.sidebarNav.closest('.sidebar');
 		if (!sidebar) return;
 		
 		const sidebarRect = sidebar.getBoundingClientRect();
@@ -159,50 +212,69 @@
 		}
 	}
 	
-	// Throttled scroll handler
-	let scrollTimer = null;
-	
-	function onScroll() {
-		if (scrollTimer) return;
+	// Static method to initialize with default selector
+	static initialize(selector = '.sidebar nav') {
+		const sidebarNav = document.querySelector(selector);
+		if (!sidebarNav) return null;
 		
-		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 navLinks = sidebarNav.querySelectorAll('a[href*="#"]');
+		
+		// Build a map of sidebar links by their fragment IDs
+		const sidebarLinksByFragment = new Map();
+		navLinks.forEach(link => {
 			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);
+			const fragment = SidebarNavigation.extractFragment(href);
 			
-			// 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 (fragment) {
+				sidebarLinksByFragment.set(fragment, link);
+			}
+		});
+		
+		// Early exit if no sidebar links with fragments
+		if (sidebarLinksByFragment.size === 0) return null;
+		
+		// Get all sections/headings on the page and annotate them with their sidebar link
+		const allSections = Array.from(document.querySelectorAll('section, h1, h2, h3, h4, h5, h6'))
+			.filter(el => el.id) // Only keep elements with IDs
+			.map(el => {
+				// Get the section element (section or heading's parent)
+				const sectionElement = el.tagName === 'SECTION' ? el : (el.closest('section') || el.parentElement);
+				return { element: sectionElement, id: el.id };
+			});
+		
+		// Annotate each section with which sidebar link should be active
+		// Walk through in DOM order and track the "last seen" sidebar link
+		// Store mapping in a Map instead of mutating DOM with data attributes
+		const sectionToSidebarLinkMap = new Map();
+		let lastSeenSidebarId = null;
+		allSections.forEach(({element, id}) => {
+			if (sidebarLinksByFragment.has(id)) {
+				// This section has a sidebar link - use it
+				lastSeenSidebarId = id;
+			}
+			// Map the section element to the sidebar link to activate
+			if (lastSeenSidebarId) {
+				sectionToSidebarLinkMap.set(element, lastSeenSidebarId);
 			}
+		});
+		
+		// Build sections array with link references for active state tracking
+		const sections = Array.from(sidebarLinksByFragment.entries()).map(([id, link]) => {
+			let sectionElement = document.getElementById(id);
 			
-			if (target) {
-				event.preventDefault();
-				
-				// Update URL to trigger :target and let browser handle scrolling
-				window.location.hash = fragment;
+			if (sectionElement && sectionElement.tagName.match(/^H[1-6]$/)) {
+				sectionElement = sectionElement.closest('section') || sectionElement.parentElement;
 			}
+			
+			return sectionElement ? { link, sectionElement, id } : null;
+		}).filter(Boolean);
+		
+		// Early exit if no valid sections found
+		if (sections.length === 0) return null;
+		
+		// All checks passed - create the instance
+		return new SidebarNavigation(sidebarNav, sidebarLinksByFragment, allSections, sections, navLinks, sectionToSidebarLinkMap);
+	}
+}
 
-			link.focus();
-		});
-	});
-})();
+export { SidebarNavigation };

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.38.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
@@ -267,79 +268,6 @@ files:
 - public/_components/@socketry/syntax/themes/base/xrb.css
 - public/_components/@socketry/syntax/themes/base/yaml.css
 - public/_components/@socketry/syntax/themes/theming.md
-- public/_components/jquery-litebox/jquery.litebox.css
-- public/_components/jquery-litebox/jquery.litebox.gallery.css
-- public/_components/jquery-litebox/jquery.litebox.js
-- public/_components/jquery-syntax/base/jquery.syntax.brush.apache.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.applescript.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.assembly.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.bash-script.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.bash.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.clang.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.css.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.diff.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.html.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.ocaml.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.protobuf.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.python.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.ruby.css
-- public/_components/jquery-syntax/base/jquery.syntax.brush.xml.css
-- public/_components/jquery-syntax/base/jquery.syntax.core.css
-- public/_components/jquery-syntax/base/jquery.syntax.editor.css
-- public/_components/jquery-syntax/base/theme.js
-- public/_components/jquery-syntax/bright/jquery.syntax.core.css
-- public/_components/jquery-syntax/bright/theme.js
-- public/_components/jquery-syntax/jquery.syntax.brush.apache.js
-- public/_components/jquery-syntax/jquery.syntax.brush.applescript.js
-- public/_components/jquery-syntax/jquery.syntax.brush.assembly.js
-- public/_components/jquery-syntax/jquery.syntax.brush.bash-script.js
-- public/_components/jquery-syntax/jquery.syntax.brush.bash.js
-- public/_components/jquery-syntax/jquery.syntax.brush.basic.js
-- public/_components/jquery-syntax/jquery.syntax.brush.clang.js
-- public/_components/jquery-syntax/jquery.syntax.brush.csharp.js
-- public/_components/jquery-syntax/jquery.syntax.brush.css.js
-- public/_components/jquery-syntax/jquery.syntax.brush.diff.js
-- public/_components/jquery-syntax/jquery.syntax.brush.go.js
-- public/_components/jquery-syntax/jquery.syntax.brush.haskell.js
-- public/_components/jquery-syntax/jquery.syntax.brush.html.js
-- public/_components/jquery-syntax/jquery.syntax.brush.io.js
-- public/_components/jquery-syntax/jquery.syntax.brush.java.js
-- public/_components/jquery-syntax/jquery.syntax.brush.javascript.js
-- public/_components/jquery-syntax/jquery.syntax.brush.kai.js
-- public/_components/jquery-syntax/jquery.syntax.brush.lisp.js
-- public/_components/jquery-syntax/jquery.syntax.brush.lua.js
-- public/_components/jquery-syntax/jquery.syntax.brush.nginx.js
-- public/_components/jquery-syntax/jquery.syntax.brush.ocaml.js
-- public/_components/jquery-syntax/jquery.syntax.brush.ooc.js
-- public/_components/jquery-syntax/jquery.syntax.brush.pascal.js
-- public/_components/jquery-syntax/jquery.syntax.brush.perl5.js
-- public/_components/jquery-syntax/jquery.syntax.brush.php-script.js
-- public/_components/jquery-syntax/jquery.syntax.brush.php.js
-- public/_components/jquery-syntax/jquery.syntax.brush.plain.js
-- public/_components/jquery-syntax/jquery.syntax.brush.protobuf.js
-- public/_components/jquery-syntax/jquery.syntax.brush.python.js
-- public/_components/jquery-syntax/jquery.syntax.brush.ruby.js
-- public/_components/jquery-syntax/jquery.syntax.brush.scala.js
-- public/_components/jquery-syntax/jquery.syntax.brush.smalltalk.js
-- public/_components/jquery-syntax/jquery.syntax.brush.sql.js
-- public/_components/jquery-syntax/jquery.syntax.brush.super-collider.js
-- public/_components/jquery-syntax/jquery.syntax.brush.swift.js
-- public/_components/jquery-syntax/jquery.syntax.brush.xml.js
-- public/_components/jquery-syntax/jquery.syntax.brush.xrb.js
-- public/_components/jquery-syntax/jquery.syntax.brush.yaml.js
-- public/_components/jquery-syntax/jquery.syntax.cache.js
-- public/_components/jquery-syntax/jquery.syntax.core.js
-- public/_components/jquery-syntax/jquery.syntax.editor.js
-- public/_components/jquery-syntax/jquery.syntax.js
-- public/_components/jquery-syntax/jquery.syntax.min.js
-- public/_components/jquery-syntax/paper/jquery.syntax.core.css
-- public/_components/jquery-syntax/paper/theme.js
-- public/_components/jquery/jquery.js
-- public/_components/jquery/jquery.min.js
-- public/_components/jquery/jquery.min.map
-- public/_components/jquery/jquery.slim.js
-- public/_components/jquery/jquery.slim.min.js
-- public/_components/jquery/jquery.slim.min.map
 - public/_components/mermaid/chunks/mermaid.core/architectureDiagram-VXUJARFQ.mjs
 - public/_components/mermaid/chunks/mermaid.core/architectureDiagram-VXUJARFQ.mjs.map
 - public/_components/mermaid/chunks/mermaid.core/blockDiagram-VD42YOAC.mjs
@@ -738,6 +666,7 @@ files:
 - public/_components/mermaid/mermaid.js.map
 - public/_components/mermaid/mermaid.min.js
 - public/_components/mermaid/mermaid.min.js.map
+- public/_static/application.js
 - public/_static/icon.png
 - public/_static/links.js
 - public/_static/sidebar.js
@@ -769,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: []

metadata.gz.sig

@@ -1 +1,3 @@
-dd^�N�=!dѰ�Cޠ�����M���6����er�<�\��F�A<M�M��詴���)>$g��'�e2k�ep������.�f�#��m �}3��Vx���߹�c`�G�ڷ)�/���h��~��p�OK��T2,C죄Ӹ���S/�-�t|�w٨� �(�C}��U
+h��j���d�D1}i����HB�*���%4�V��7^��Eki>�#n&����æ�I^�
+��i��t����g�&1�����7�o�~��^jLԪ�r^=s~������Q����s�_���4��
+@;(>H\��n��Bc��&;\pȝ��w�1�9��Lq��x!���kMJ�s�RМ*d