utopia-project 0.43.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e03635789e50ada548501b8220d49ae33e6ee4ec89aa993cddb358d7a8efc30
-  data.tar.gz: a97fb27c10530e9d5cd66d4caae0c173eb5f40b72dd48d2a92d35fd52e1b12a7
+  metadata.gz: 7f02594d75aca403abee0bf56e3e2ec4e398a81df172f6c62cf73cdccba11bc5
+  data.tar.gz: bc73b831e8e44df2de6759154a24d91d0d228e062e5c790d5956788ebddc5177
 SHA512:
-  metadata.gz: 38468ed82c56f4048427dd94d7f687d5a45c978d7f398e3033483cfdcb9689c78e23a5b6c4cbefc8d1ae65fb9d62ae06fa05d0c85cdf21721fe5bde350ab5f68
-  data.tar.gz: 6035c40a3578098292f084f63614c3bac24ac396774466b8c649ac7770b745d74b0e75676bb4d1d03555a888f65efe2008e2d8790da9e0e67ca0463b35dd5341
+  metadata.gz: 3dd75a8af1c68d0b7d4b64856f569d13468e6b3296303bcad6b02f3595709821c88de4387212aad33a629caa2854b8f5e6ebfdebfe1e0b7a17975ba44f846d68
+  data.tar.gz: 0e731e759758f27e1d64a721a9e5aa9eb275e76bf7e01e3e4fe027d2baad520c3b3f249a28bd049fb392278e47a3f646322d54488648136fdba389adc4f0b5c0

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,15 +165,9 @@ 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
@@ -176,9 +175,17 @@ module Utopia
 			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)
+			# @parameter content [String] The source code reference.
+			# @parameter language [String | Nil] The explicit source language.
+			# @returns [Markly::Node] The resolved link or code node.
+			def reference_node(content, language: nil)
+				reference = if language
+					@index.languages.reference_for(language, content)
+				else
+					@index.languages.parse_reference(content, default_language: @default_language)
+				end
+				
+				if reference
 					definition = @index.lookup(reference, relative_to: @definition)
 				end
 				
@@ -189,7 +196,7 @@ module Utopia
 				elsif reference
 					code_node(reference.identifier, reference.language.name)
 				else
-					code_node(content)
+					code_node(content, language)
 				end
 			end
 			

data/lib/utopia/project/renderer.rb

@@ -10,6 +10,15 @@ 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 a replacement node.
+			def initialize(inline_code_resolver: nil, **options)
+				@inline_code_resolver = inline_code_resolver
+				@resolving_inline_code = false
+				
+				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 +54,21 @@ 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 && !@resolving_inline_code && (language = node.code_language)
+					begin
+						@resolving_inline_code = true
+						out(@inline_code_resolver.call(node.string_content, language: language))
+					ensure
+						@resolving_inline_code = false
+					end
+				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.0"
 	end
 end

data/readme.md

@@ -33,6 +33,10 @@ 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.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.
@@ -72,10 +76,6 @@ Please see the [project releases](https://socketry.github.io/utopia-project/rele
 
   - 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,9 @@
 # Changes
 
+## 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.0
 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