tweak: add title frontmatter for mdx, prefer included examples first

Author: AvarianKnight

src/NativeCodeGen.Cli/NativeCodeGen.Cli.csproj

@@ -28,6 +28,7 @@
     <!-- Trimming to reduce binary size -->
     <PublishTrimmed>true</PublishTrimmed>
     <TrimMode>link</TrimMode>
+
   </PropertyGroup>
 
   <!-- Preserve types for reflection-based libraries -->

src/NativeCodeGen.Core/Export/DatabaseConverter.cs

@@ -47,10 +47,34 @@ public static ExportDatabase Convert(NativeDatabase db, ExportOptions options)
             }
         }
 
-        // Convert shared examples
+        // Convert shared examples - referenced examples first
+        var referencedExamples = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var ns in db.Namespaces)
+        {
+            foreach (var native in ns.Natives)
+            {
+                foreach (var exampleName in native.RelatedExamples)
+                {
+                    referencedExamples.Add(exampleName);
+                }
+            }
+        }
+
+        // Add referenced examples first, then the rest
+        foreach (var name in referencedExamples)
+        {
+            if (db.SharedExamples.TryGetValue(name, out var example))
+            {
+                export.SharedExamples.Add(ConvertSharedExample(example));
+            }
+        }
+
         foreach (var (name, example) in db.SharedExamples)
         {
-            export.SharedExamples.Add(ConvertSharedExample(example));
+            if (!referencedExamples.Contains(name))
+            {
+                export.SharedExamples.Add(ConvertSharedExample(example));
+            }
         }
 
         // Add type definitions
@@ -141,6 +165,7 @@ private static ExportSharedExample ConvertSharedExample(Models.SharedExample exa
         return new ExportSharedExample
         {
             Name = example.Name,
+            Title = example.Title,
             Content = example.Content,
             Language = example.Language
         };

src/NativeCodeGen.Core/Export/ExportModels.cs

@@ -191,8 +191,11 @@ public partial class ExportSharedExample
     public string Name { get; set; } = string.Empty;
 
     [ProtoMember(2)]
-    public string Content { get; set; } = string.Empty;
+    public string? Title { get; set; }
 
     [ProtoMember(3)]
+    public string Content { get; set; } = string.Empty;
+
+    [ProtoMember(4)]
     public string? Language { get; set; }
 }

src/NativeCodeGen.Core/Export/natives.proto

@@ -91,6 +91,7 @@ message NativeReference {
 
 message SharedExample {
   string name = 1;
-  string content = 2;
-  optional string language = 3;
+  optional string title = 2;
+  string content = 3;
+  optional string language = 4;
 }

src/NativeCodeGen.Core/Models/SharedExample.cs

@@ -3,6 +3,7 @@ namespace NativeCodeGen.Core.Models;
 public class SharedExample
 {
     public string Name { get; set; } = string.Empty;
+    public string? Title { get; set; }
     public string Content { get; set; } = string.Empty;
     public string? Language { get; set; }
     public string? SourceFile { get; set; }

src/NativeCodeGen.Core/Registry/SharedExampleRegistry.cs

@@ -1,13 +1,29 @@
 using NativeCodeGen.Core.Models;
+using YamlDotNet.Serialization;
+using YamlDotNet.Serialization.NamingConventions;
 
 namespace NativeCodeGen.Core.Registry;
 
+public class SharedExampleFrontmatter
+{
+    public string? Title { get; set; }
+}
+
 public class SharedExampleRegistry
 {
     private readonly Dictionary<string, SharedExample> _examples = new(StringComparer.OrdinalIgnoreCase);
+    private readonly IDeserializer _deserializer;
 
     public int Count => _examples.Count;
 
+    public SharedExampleRegistry()
+    {
+        _deserializer = new DeserializerBuilder()
+            .WithNamingConvention(CamelCaseNamingConvention.Instance)
+            .IgnoreUnmatchedProperties()
+            .Build();
+    }
+
     public void LoadExamples(string directory)
     {
         if (!Directory.Exists(directory))
@@ -18,19 +34,54 @@ public void LoadExamples(string directory)
             var name = Path.GetFileNameWithoutExtension(file);
             var content = File.ReadAllText(file);
 
-            // Extract language and code content from markdown code block
-            var (language, code) = ParseCodeBlock(content);
+            // Extract frontmatter and code content
+            var (frontmatter, body) = ParseFrontmatter(content);
+            var (language, code) = ParseCodeBlock(body);
 
             _examples[name] = new SharedExample
             {
                 Name = name,
+                Title = frontmatter?.Title,
                 Content = code,
                 Language = language,
                 SourceFile = file
             };
         }
     }
 
+    private (SharedExampleFrontmatter? frontmatter, string body) ParseFrontmatter(string content)
+    {
+        var lines = content.Split('\n');
+        if (lines.Length == 0 || lines[0].Trim() != "---")
+            return (null, content);
+
+        int endIndex = -1;
+        for (int i = 1; i < lines.Length; i++)
+        {
+            if (lines[i].Trim() == "---")
+            {
+                endIndex = i;
+                break;
+            }
+        }
+
+        if (endIndex == -1)
+            return (null, content);
+
+        var yamlContent = string.Join('\n', lines.Skip(1).Take(endIndex - 1));
+        var body = string.Join("\n", lines.Skip(endIndex + 1));
+
+        try
+        {
+            var frontmatter = _deserializer.Deserialize<SharedExampleFrontmatter>(yamlContent);
+            return (frontmatter, body);
+        }
+        catch
+        {
+            return (null, body);
+        }
+    }
+
     private static (string? language, string content) ParseCodeBlock(string content)
     {
         var lines = content.Split('\n');