diff --git a/src/elements/DropDown.lua b/src/elements/DropDown.lua
index fc7432c..5967bc7 100644
--- a/src/elements/DropDown.lua
+++ b/src/elements/DropDown.lua
@@ -14,7 +14,7 @@ local tHex = require("libraries/colorHex")
 ---@tableField selectedBg color Background when selected
 
 --- A collapsible selection menu that expands to show multiple options when clicked. Supports single and multi-selection modes, custom item styling, separators, and item callbacks.
---- @usage [[
+--- @run [[
 --- -- Create a styled dropdown menu
 --- local dropdown = main:addDropDown()
 ---     :setPosition(5, 5)
diff --git a/tools/BasaltDoc/init.lua b/tools/BasaltDoc/init.lua
index cdfac69..41a8db1 100644
--- a/tools/BasaltDoc/init.lua
+++ b/tools/BasaltDoc/init.lua
@@ -141,6 +141,11 @@ BasaltDoc.registerAnnotation("@skip", function(target, args)
     target.skip = true
 end)
 
+BasaltDoc.registerAnnotation("@note", function(target, args)
+    if not target.notes then target.notes = {} end
+    table.insert(target.notes, args)
+end)
+
 BasaltDoc.registerAnnotation("@globalDescription", function(target, args)
     if args and args ~= "" then
         target.description = args
diff --git a/tools/BasaltDoc/utils/markdownGenerator.lua b/tools/BasaltDoc/utils/markdownGenerator.lua
index c130438..528a4e7 100644
--- a/tools/BasaltDoc/utils/markdownGenerator.lua
+++ b/tools/BasaltDoc/utils/markdownGenerator.lua
@@ -73,14 +73,11 @@ local function generateFunctionMarkdown(class, functions)
         if f.usage then
             table.insert(md, "### Usage")
             for _, usageBlock in ipairs(f.usage) do
-                table.insert(md, "```lua run")
-                -- Check if usageBlock is already multi-line
+                table.insert(md, "```lua")
                 if type(usageBlock) == "string" then
                     if usageBlock:match("\n") then
-                        -- Multi-line block
                         table.insert(md, usageBlock)
                     else
-                        -- Single line
                         table.insert(md, usageBlock)
                     end
                 end
@@ -165,7 +162,7 @@ function markdownGenerator.generate(ast)
             if class.usage then
                 table.insert(md, "## Usage")
                 for _, usageBlock in ipairs(class.usage) do
-                    table.insert(md, "```lua run")
+                    table.insert(md, "```lua")
                     if type(usageBlock) == "string" then
                         table.insert(md, usageBlock)
                     end
@@ -174,6 +171,25 @@ function markdownGenerator.generate(ast)
                 end
             end
 
+            if class.run then
+                table.insert(md, "## Examples (Executable)")
+                for _, runBlock in ipairs(class.run) do
+                    table.insert(md, "```lua run")
+                    if type(runBlock) == "string" then
+                        table.insert(md, runBlock)
+                    end
+                    table.insert(md, "```")
+                    table.insert(md, "")
+                end
+            end
+
+            if class.notes then
+                for _, note in ipairs(class.notes) do
+                    table.insert(md, "> **Note:** " .. note)
+                    table.insert(md, "")
+                end
+            end
+
             if #class.tableTypes > 0 then
                 table.insert(md, "## Table Types")
                 table.insert(md, "")