utopia-project 0.43.0 → 0.44.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e03635789e50ada548501b8220d49ae33e6ee4ec89aa993cddb358d7a8efc30
-  data.tar.gz: a97fb27c10530e9d5cd66d4caae0c173eb5f40b72dd48d2a92d35fd52e1b12a7
+  metadata.gz: aeb8c91bedd9b713aac858b1d21a2475e46339d263619e37c5ee5e55a96f9823
+  data.tar.gz: 42dd69b94451317ffebd0c44e7316accba3e2e7563c911c6e47ec3ff8b61f83d
 SHA512:
-  metadata.gz: 38468ed82c56f4048427dd94d7f687d5a45c978d7f398e3033483cfdcb9689c78e23a5b6c4cbefc8d1ae65fb9d62ae06fa05d0c85cdf21721fe5bde350ab5f68
-  data.tar.gz: 6035c40a3578098292f084f63614c3bac24ac396774466b8c649ac7770b745d74b0e75676bb4d1d03555a888f65efe2008e2d8790da9e0e67ca0463b35dd5341
+  metadata.gz: c661665e07add1839f6f49abe463e74fdc433e2184bbf802d8fbd4dcfe09c339d637625ce5ba0f63333860ee97d22414026c3bb70ab16ccdffdae8c3a3a4dcb3
+  data.tar.gz: 429aedacf04be623ca7869fde98f40cc702743da7b53fa2f51bb81c1b387b39dea7d8b475a916a76c0a9fc5cce1c51d8db0a80e2a151f62ab06c304ad7e73a45

data/context/documentation-guidelines.md

@@ -16,7 +16,7 @@ Source code documentation is included adjacent to the code it describes, using s
 However, in short:
 
 - Documentation is expected to be in markdown format.
-- You may embed links to definitions using `{MyClass}` or `{my_method}`.
+- You may embed links to definitions using ruby:`MyClass` or ruby:`my_method`.
 - You can use tags:
   - `@parameters name [Type] Description.`
   - `@yields {|argument| ...} If a block is given.`
@@ -173,7 +173,7 @@ $ bundle add $project
 
 `$project` has several core concepts:
 
-- A {ruby MyProject::MyClass} which represents the main entry point for using the project.
+- A ruby:`MyProject::MyClass` which represents the main entry point for using the project.
 
 ## Usage
 
@@ -284,7 +284,7 @@ Following `utopia-project` guidelines, each guide should:
 2. **Provide user context**: Explain why users would need this feature
 3. **Include practical examples**: Working code samples that demonstrate real scenarios
 4. **Follow consistent structure**: Problem → Use Cases → Implementation → Best Practices
-5. **Cross-reference appropriately**: Use `{ruby ClassName}` for internal references
+5. **Cross-reference appropriately**: Use ruby:`ClassName` for internal references
 6. **Include error handling**: Show how to handle common failure scenarios
 7. **Provide troubleshooting**: Common issues and solutions
 8. **Maintain currency**: Keep examples updated with latest best practices

data/lib/utopia/project/base.md

@@ -4,4 +4,4 @@ Provides structured access to a project directory which contains source code and
 
 ## Usage
 
-To get an instance for the current project, use {Base#instance}.
+To get an instance for the current project, use ruby:`Base#instance`.

data/lib/utopia/project/base.rb

@@ -136,12 +136,12 @@ module Utopia
 			end
 			
 			# Format the given text in the context of the given definition and language.
-			# See {document} for details.
+			# See ruby:`document` for details.
 			# @returns [XRB::MarkupString]
 			#
 			# @example Format text with code links
 			# 	base = Utopia::Project::Base.new
-			# 	base.format("See {Utopia::Project::Base#guides}.") # => XRB::MarkupString
+			# 	base.format("See ruby:`Utopia::Project::Base#guides`.") # => XRB::MarkupString
 			def format(text, definition = nil, language: definition&.language, **options)
 				if document = self.document(text, definition, language: language)
 					return XRB::Markup.raw(
@@ -152,7 +152,7 @@ module Utopia
 			
 			# Convert the given markdown text into HTML.
 			#
-			# Updates source code references (`{language identifier}`) into links.
+			# Updates language-prefixed inline code (e.g. `ruby:` followed by inline code) into links.
 			#
 			# @returns [Document]
 			#

data/lib/utopia/project/document.rb

@@ -29,7 +29,7 @@ module Utopia
 			# Parse and resolve the document root.
 			# @returns [Markly::Node] The root document node.
 			def root
-				@root ||= resolve(Markly.parse(@text, extensions: [:table]))
+				@root ||= resolve(Markly.parse(@text, flags: Markly::INLINE_CODE_INFO, extensions: [:table]))
 			end
 			
 			# Extract the leading heading as the document title.
@@ -99,7 +99,12 @@ module Utopia
 			# @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)
+				renderer = Renderer.new(
+					inline_code_resolver: (@index ? method(:reference_node) : nil),
+					ids: true,
+					flags: Markly::UNSAFE,
+					**options
+				)
 				XRB::Markup.raw(renderer.render(node))
 			end
 			
@@ -160,37 +165,62 @@ module Utopia
 			# @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(
-						"<code class=\"language-#{language}\">#{XRB::Strings.to_html(content)}</code>"
-					)
-				else
-					node = Markly::Node.new(:code)
-					node.string_content = content
-					return node
-				end
+				node = Markly::Node.new(:code)
+				node.string_content = content
+				node.code_info = language if language
 				
 				return node
 			end
 			
 			private
 			
-			# Replace source code references in the given text with HTML anchors.
-			#
-			def reference_node(content)
-				if reference = @index.languages.parse_reference(content, default_language: @default_language)
-					definition = @index.lookup(reference, relative_to: @definition)
-				end
+			# Resolve a source code reference to HTML.
+			# @parameter content [String] The source code reference.
+			# @parameter language [String | Nil] The explicit source language.
+			# @returns [Markly::Node] The inline HTML node.
+			def reference_node(content, language: nil)
+				reference, definition = resolve_reference(content, language: language)
 				
 				if definition
-					link_node(reference.identifier, @base.link_for(definition),
-						code_node(definition.qualified_form, reference.language.name)
-					)
+					content = definition.qualified_form
+					language = reference.language.name
 				elsif reference
-					code_node(reference.identifier, reference.language.name)
+					content = reference.identifier
+					language = reference.language.name
+				end
+				
+				attributes = {}
+				attributes[:class] = "language-#{language}" if language
+				
+				markup = XRB::Builder.fragment do |builder|
+					builder.inline("code", attributes) do
+						if definition
+							builder.inline("a", href: @base.link_for(definition), title: reference.identifier) do
+								builder.text(content)
+							end
+						else
+							builder.text(content)
+						end
+					end
+				end
+				
+				return inline_html_node(markup.to_s)
+			end
+			
+			# Resolve source code reference metadata and its indexed definition.
+			# @parameter content [String] The source code reference.
+			# @parameter language [String | Nil] The explicit source language.
+			# @returns [Array] The parsed reference and resolved definition.
+			def resolve_reference(content, language: nil)
+				reference = if language
+					@index.languages.reference_for(language, content)
 				else
-					code_node(content)
+					@index.languages.parse_reference(content, default_language: @default_language)
 				end
+				
+				definition = @index.lookup(reference, relative_to: @definition) if reference
+				
+				return reference, definition
 			end
 			
 			def resolve(root)

data/lib/utopia/project/renderer.rb

@@ -10,6 +10,14 @@ module Utopia
 	module Project
 		# Renders project Markdown with support for Mermaid code blocks.
 		class Renderer < Markly::Renderer::HTML
+			# Initialize the project renderer.
+			# @parameter inline_code_resolver [Proc | Nil] Resolves language-prefixed inline code into an inline HTML node.
+			def initialize(inline_code_resolver: nil, **options)
+				@inline_code_resolver = inline_code_resolver
+				
+				super(**options)
+			end
+			
 			# Render a heading and expose its title to Pagefind for sub-results.
 			# @parameter node [Markly::Node] The heading node.
 			def header(node)
@@ -45,6 +53,16 @@ module Utopia
 					super
 				end
 			end
+			
+			# Render inline code, resolving language-prefixed references when possible.
+			# @parameter node [Markly::Node] The inline code node.
+			def code(node)
+				if @inline_code_resolver && (language = node.code_language)
+					out(@inline_code_resolver.call(node.string_content, language: language))
+				else
+					super
+				end
+			end
 		end
 	end
 end

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.43.0"
+		VERSION = "0.44.1"
 	end
 end

data/readme.md

@@ -33,6 +33,14 @@ 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.44.1
+
+  - Render resolved inline code references with links inside their code elements so hover and keyboard focus affect the complete reference.
+
+### v0.44.0
+
+  - Add support for language-prefixed inline code references such as ruby:`Object.new`.
+
 ### v0.41.0
 
   - Don't render empty signature block when there are only examples.
@@ -68,14 +76,6 @@ Please see the [project releases](https://socketry.github.io/utopia-project/rele
 
   - Fixed handling of segmented code guides when rendered into a `readme.md` file.
 
-### v0.33.0
-
-  - Fix presentation of release notes on releases page.
-
-### v0.31.0
-
-  - Support brief release notes in `releases.md` document.
-
 ## See Also
 
   - [Utopia](https://github.com/socketry/utopia) — The website framework which powers this web application.

data/releases.md

@@ -1,5 +1,13 @@
 # Changes
 
+## v0.44.1
+
+  - Render resolved inline code references with links inside their code elements so hover and keyboard focus affect the complete reference.
+
+## v0.44.0
+
+  - Add support for language-prefixed inline code references such as ruby:`Object.new`.
+
 ## v0.41.0
 
   - Don't render empty signature block when there are only examples.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.43.0
+  version: 0.44.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -75,14 +75,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.17'
 - !ruby/object:Gem::Dependency
   name: thread-local
   requirement: !ruby/object:Gem::Requirement