diff --git a/doc/bufferline.txt b/doc/bufferline.txt
index 2e27e21c..b3d5beec 100644
--- a/doc/bufferline.txt
+++ b/doc/bufferline.txt
@@ -1125,26 +1125,37 @@ to be shown in a list of tables. For example:
         local info = #vim.diagnostic.get(0, {severity = seve.INFO})
         local hint = #vim.diagnostic.get(0, {severity = seve.HINT})
 
+        table.insert(result, {text = "", fg = "#EC5241"})
+        table.insert(result, {text = "", fg = "#EFB839"})
+        table.insert(result, {text = "", fg = "#A3BA5E"})
+        table.insert(result, {text = "", fg = "#7EA9A7"})
+
         if error ~= 0 then
-            table.insert(result, {text = "  " .. error, fg = "#EC5241"})
+            result[1].text = "  " .. error
         end
 
         if warning ~= 0 then
-            table.insert(result, {text = "  " .. warning, fg = "#EFB839"})
+            result[2].text = "  " .. warning
         end
 
         if hint ~= 0 then
-            table.insert(result, {text = "  " .. hint, fg = "#A3BA5E"})
+            result[3].text = "  " .. hint
         end
 
         if info ~= 0 then
-            table.insert(result, {text = "  " .. info, fg = "#7EA9A7"})
+            result[4].text = "  " .. info
         end
+
         return result
     end,
     }
 <
 
+
+This option will create a highlight groups for each table insert whether defined or not. For best experience,
+define all of your highlights if you are conditionally displaying text, otherwise your text may appear
+under unexpected highlight groups.
+
 Please note that this function will be called a lot and should be as inexpensive as possible so it does
 not block rendering the tabline.