diff --git a/docs/docset.yml b/docs/docset.yml
index e89280629..637f4abf5 100644
--- a/docs/docset.yml
+++ b/docs/docset.yml
@@ -68,6 +68,7 @@ toc:
       - file: file_inclusion.md
       - file: frontmatter.md
       - file: images.md
+      - file: lists.md
       - file: line_breaks.md
       - file: links.md
       - file: passthrough.md
diff --git a/docs/syntax/lists.md b/docs/syntax/lists.md
new file mode 100644
index 000000000..0b9633e2d
--- /dev/null
+++ b/docs/syntax/lists.md
@@ -0,0 +1,242 @@
+# Lists
+
+You can organize items into ordered and unordered lists.
+
+## Basic Lists
+
+### Unordered List
+
+Unordered lists are created by starting each line with a hyphen `-`, asterisk `*`, or plus sign `+`.
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+- Item 1
+- Item 2 
+- Item 3
+
+:::
+
+
+:::{tab-item} Markdown
+
+```markdown
+- Item 1
+- Item 2
+- Item 3
+```
+
+:::
+
+
+::::
+
+### Ordered List
+
+Ordered lists are created by starting each line with a number followed by a period.
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+1. Item 1
+2. Item 2
+3. Item 3
+
+:::
+
+
+:::{tab-item} Markdown
+
+```markdown
+1. Item 1
+2. Item 2
+3. Item 3
+```
+
+:::
+
+
+::::
+
+
+## Nested Lists
+
+When you want to create a nested list within a list item, indent the nested list by four spaces.
+
+### Nested Unordered List
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+- Item 1
+- Item 2
+    - Subitem 1
+    - Subitem 2
+        - Subsubitem 1
+        - Subsubitem 2
+- Item 3
+
+:::
+
+
+:::{tab-item} Markdown
+
+```markdown
+- Item 1
+- Item 2
+    - Subitem 1
+    - Subitem 2
+        - Subsubitem 1
+        - Subsubitem 2
+- Item 3
+```
+
+:::
+
+
+::::
+
+### Nested Ordered Lists
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+1. Item 1
+2. Item 2
+    1. Subitem 1
+    2. Subitem 2
+        1. Subsubitem 1
+        2. Subsubitem 2
+3. Item 3
+
+:::
+
+
+:::{tab-item} Markdown
+
+```markdown
+1. Item 1
+2. Item 2
+    1. Subitem 1
+    2. Subitem 2
+        1. Subsubitem 1
+        2. Subsubitem 2
+3. Item 3
+```
+
+:::
+
+
+::::
+
+### Nested Mixed Lists
+
+::::{tab-set}
+
+:::{tab-item} Output
+
+1. Item 1
+2. Item 2
+    - Subitem 1
+    - Subitem 2
+        1. Subsubitem 1
+        2. Subsubitem 2
+            1. Subsubsubitem 1
+            2. Subsubsubitem 2
+3. Item 3
+    - Subitem 1
+    - Subitem 2
+        - Subsubitem 1
+        - Subsubitem 2
+        - Subsubsubitem 1
+        - Subsubsubitem 2
+
+:::
+
+
+:::{tab-item} Markdown
+
+```markdown
+1. Item 1
+2. Item 2
+    - Subitem 1
+    - Subitem 2
+        1. Subsubitem 1
+        2. Subsubitem 2
+            1. Subsubsubitem 1
+            2. Subsubsubitem 2
+3. Item 3
+    - Subitem 1
+    - Subitem 2
+        - Subsubitem 1
+        - Subsubitem 2
+            - Subsubsubitem 1
+            - Subsubsubitem 2
+```
+
+:::
+
+
+::::
+
+
+## Content within a List Item
+
+You can include any type of content within a list item, such as paragraphs, code blocks, or images.
+To include a paragraph of text within a list item, indent the content by four spaces.
+
+::::::{tab-set}
+
+::::{tab-item} Output
+
+1. This is a list item with a paragraph of text.
+    
+    This is a `paragraph` of text within a list item.
+
+2. This is a list item with a code block:
+
+    ```bash
+    echo "Hello, World!"
+    ```
+
+3. This is a list item with an image:
+
+    ![Image](./img/apm.png)
+
+4. This is a list item with an admonition:
+
+    :::{note}
+    This is a note within a list item.
+    :::
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+1. This is a list item with a paragraph of text.
+
+    This is a `paragraph` of text within a list item.
+
+2. This is a list item with a code block:
+
+    ```bash
+    echo "Hello, World!"
+    ```
+
+3. This is a list item with an image:
+
+    ![Image](./img/apm.png)
+
+4. This is a list item with an admonition:
+
+    :::{note}
+    This is a note within a list item.
+    :::
+```
+::::
+
+:::::
diff --git a/src/Elastic.Markdown/Assets/markdown/list.css b/src/Elastic.Markdown/Assets/markdown/list.css
index bdc4e39b3..262ed7e22 100644
--- a/src/Elastic.Markdown/Assets/markdown/list.css
+++ b/src/Elastic.Markdown/Assets/markdown/list.css
@@ -1,25 +1,47 @@
 .markdown-content {
 	ol,ul {
 		font-family: "Inter", sans-serif;
-		@apply text-base text-body mt-6;
+		@apply mt-4;
 		line-height: 1.5em;
 		letter-spacing: 0;
 		margin-left: 1.5em;
+		/*list-style-position: inside;*/
+		li::marker {
+			@apply font-mono text-grey-80;
+		}
 	}
 	
-	ol {
-		list-style-type: decimal;
+	ul li {
+		@apply pl-[.5ch];
 	}
 	
-	ul {
-		list-style-type: disc;
+	li>ul, li>ol {
+		@apply mt-1;
 	}
-
+	
 	li {
-		@apply first:mt-0  mt-2;
-
-		p {
-			margin-bottom: 0;
-		}
+		@apply first:mt-0 mt-1;
+	}
+	
+	ul {list-style-type: disc; }
+	ul>li>ul { list-style-type: square; }
+	ul>li>ul>li>ul { list-style-type: circle; }
+	ul>li>ul>li>ul>li>ul { list-style-type: disc; }
+	ul>li>ul>li>ul>li>ul>li>ul { list-style-type: square; }
+	ul>li>ul>li>ul>li>ul>li>ul>li>ul { list-style-type: circle; }
+	
+	ol { list-style-type: decimal; }
+	ol>li>ol { list-style-type: lower-alpha; }
+	ol>li>ol>li>ol { list-style-type: lower-roman; }
+	ol>li>ol>li>ol>li>ol { list-style-type: decimal; }
+	ol>li>ol>li>ol>li>ol>li>ol { list-style-type: lower-alpha; }
+	ol>li>ol>li>ol>li>ol>li>ol>li>ol { list-style-type: lower-roman; }
+	
+	/* Special handling of elements within a list item */
+	li>p:nth-child(2),
+	li>div>.highlight,
+	li>.admonition
+	{
+		@apply mt-1;
 	}
 }