From 21d8ab005e0f4350b8c1ee454e5b9caef16d420d Mon Sep 17 00:00:00 2001
From: Artem Sierikov <sierikov@pm.me>
Date: Thu, 9 May 2024 20:06:12 +0200
Subject: [PATCH] Add docs for `ignore` keyword in snippets in md (#2898)

---
 website/docs/guides/power/markdown.md | 40 +++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/website/docs/guides/power/markdown.md b/website/docs/guides/power/markdown.md
index ec85f1c107..7ea2aa7958 100644
--- a/website/docs/guides/power/markdown.md
+++ b/website/docs/guides/power/markdown.md
@@ -345,6 +345,46 @@ world
 
 </ChainedSnippets>
 
+### `ignore` in `scala` snippets
+
+You can mark a `scala` code block with the `ignore` keyword, indicating that this snippet should not be run. This block will be ignored completely and will not be compiled or executed.
+
+Below is an example of an `.md` file with an ignored `scala` snippet:
+
+````markdown title=IgnoreExample.md
+# `ignore` example
+## Normal snippet
+```scala
+val message = "Hello world!"
+println(message)
+```
+
+## Ignored snippet
+```scala ignore
+val message = "This must be ignored"
+println(message)
+1 / 0
+```
+
+````
+
+<ChainedSnippets>
+
+```bash
+scala-cli --power IgnoreExample.md
+```
+
+We see output only from the `scala` snippet:
+
+```text
+Hello world!
+```
+
+</ChainedSnippets>
+
+After execution of the above example, you can see that the ignored snippet was not run.
+All errors and exceptions that would have been thrown by the `ignore` snippet are also absent.
+
 ## `shebang` header and Markdown code blocks
 The `shebang` line in `scala` code blocks inside a markdown input are always ignored.
 You can use them (i.e. to give an example of their usage), but they do not change how the code is handled.