Add fallback for potentially missing items to ItemLink

docs/docs/30-authoring/index.md

@@ -155,6 +155,9 @@ If the link targets an item from the same namespace as the page, an error will b
 You can opt out of this behavior by adding `optional={true}` or just `optional` to the link, or opt in for items of other mods by 
 adding `optional={false}`.
 
+If you're linking to items from another mod and want to account for cases where the item doesn't exist at all,
+you can specify a `fallback="text"` attribute to show a fallback text instead of an error.
+
 ### Command Links
 
 You can make links that run a command when clicked using `<CommandLink command="/command">text text</CommandLink>`.

src/main/java/guideme/compiler/tags/ItemLinkCompiler.java

@@ -3,11 +3,15 @@
 import guideme.compiler.PageCompiler;
 import guideme.document.flow.LytFlowLink;
 import guideme.document.flow.LytFlowParent;
+import guideme.document.flow.LytFlowSpan;
 import guideme.document.flow.LytTooltipSpan;
 import guideme.document.interaction.ItemTooltip;
 import guideme.indices.ItemIndex;
 import guideme.libs.mdast.mdx.model.MdxJsxElementFields;
 import java.util.Set;
+import net.minecraft.resources.Identifier;
+import net.minecraft.world.item.ItemStack;
+import org.apache.commons.lang3.tuple.Pair;
 
 public class ItemLinkCompiler extends FlowTagCompiler {
     @Override
@@ -17,8 +21,20 @@ public Set<String> getTagNames() {
 
     @Override
     public void compile(PageCompiler compiler, LytFlowParent parent, MdxJsxElementFields el) {
-        var itemAndId = MdxAttrs.getRequiredItemStackAndId(compiler, parent, el);
+        var fallback = MdxAttrs.getString(compiler, parent, el, "fallback", null);
+        Pair<Identifier, ItemStack> itemAndId;
+        if (fallback != null) {
+            itemAndId = MdxAttrs.getItemStackAndId(compiler, parent, el);
+        } else {
+            itemAndId = MdxAttrs.getRequiredItemStackAndId(compiler, parent, el);
+        }
         if (itemAndId == null) {
+            if (fallback != null) {
+                var span = new LytFlowSpan();
+                span.modifyStyle(style -> style.italic(true));
+                span.appendText(fallback);
+                parent.append(span);
+            }
             return;
         }
         var id = itemAndId.getLeft();

src/main/java/guideme/compiler/tags/MdxAttrs.java

@@ -138,6 +138,15 @@ public static Pair<Identifier, Item> getRequiredItemAndId(PageCompiler compiler,
         return Pair.of(itemId, resultItem);
     }
 
+    @Nullable
+    public static Pair<Identifier, Item> getItemAndId(PageCompiler compiler, LytErrorSink errorSink,
+            MdxJsxElementFields el, String attribute) {
+        var itemId = getRequiredId(compiler, errorSink, el, attribute);
+
+        var resultItem = BuiltInRegistries.ITEM.getOptional(itemId).orElse(null);
+        return resultItem == null ? null : Pair.of(itemId, resultItem);
+    }
+
     @Nullable
     public static Pair<Identifier, EntityType<?>> getRequiredEntityTypeAndId(PageCompiler compiler,
             LytErrorSink errorSink,
@@ -175,10 +184,19 @@ public static Pair<Identifier, ItemStack> getRequiredItemStackAndId(PageCompiler
             LytErrorSink errorSink,
             MdxJsxElementFields el) {
         var itemAndId = getRequiredItemAndId(compiler, errorSink, el, "id");
-        if (itemAndId == null) {
-            return null;
-        }
+        return itemAndId == null ? null : getItemStackAndId(compiler, errorSink, el, itemAndId);
+    }
 
+    @Nullable
+    public static Pair<Identifier, ItemStack> getItemStackAndId(PageCompiler compiler, LytErrorSink errorSink,
+            MdxJsxElementFields el) {
+        var itemAndId = getItemAndId(compiler, errorSink, el, "id");
+        return itemAndId == null ? null : getItemStackAndId(compiler, errorSink, el, itemAndId);
+    }
+
+    @Nullable
+    private static Pair<Identifier, ItemStack> getItemStackAndId(PageCompiler compiler, LytErrorSink errorSink,
+            MdxJsxElementFields el, Pair<Identifier, Item> itemAndId) {
         var stack = new ItemStack(itemAndId.getRight());
         var componentsString = MdxAttrs.getString(compiler, errorSink, el, "components", null);
         if (componentsString != null) {

src/testmod/resources/assets/testmod/guides/testmod/guide/index.md

@@ -25,6 +25,8 @@ You may ~~need~~ a <Color color="#ff0000">door</Color> <Color id="test_color">do
 
 <ItemLink id="minecraft:stick" components="rarity=epic" />
 
+<ItemLink id="not_installed:doesnt_exist" fallback="Fallback for non-existent item" />
+
 <GameScene zoom={4} interactive={true}>
     <Entity id="minecraft:sheep" data="{Color: 2}" />
     <Block id="minecraft:water" />