diff --git a/ClickHouse-specific.md b/ClickHouse-specific.md
new file mode 100644
index 00000000..41547def
--- /dev/null
+++ b/ClickHouse-specific.md
@@ -0,0 +1,52 @@
+## Working with Marksman and multiple repos
+
+In order to keep the docs close to the source-code at ClickHouse
+most of the reference (SQL syntax, etc.) docs are in the repo
+where the code is.  This gives us heartburn when building the
+docs with Docusaurus as the files need to be combined.  In the
+`.gitignore` file for the docs repo all of the dirs copied over
+from the ClickHouse repo are marked to be ignored; this causes the 
+wonderful Marksman LSP to ignore the reference docs, and marks
+any links to the reference docs invalid.
+
+The Marksman author came up with a great workaround, as `.ignore` gets
+processed after `.gitignore`, I negate the ignore in `.ignore` and 
+the reference docs are now eligible for linking.
+```
+# This is to reverse the .gitignore in the ClickHouse-docs repo, as
+# the marksman LSP ignores dirs in the .gitignore when checking
+# for links for markdown files.  This file (.ignore) gets processed
+# after .gitignore, so the negation (`!`) of the path fixes the issue
+# created by copying the files into the clickhouse-docs directory
+# structure
+
+# place at root dir of the markdown project, for example:
+# $GITHUB/clickhouse-docs/.ignore
+
+!docs/en/development
+!docs/en/engines
+!docs/en/getting-started
+!docs/en/interfaces
+!docs/en/operations
+!docs/en/sql-reference
+docs/ru
+docs/zh
+docs/_clients
+```
+
+## Configuring Marksman
+
+Maybe not needed, but I am not sure.  I think that `.mdx` files
+may now be considered Markdown, I should check. I don't like table of
+contents to be created, so this is disabled.
+
+```
+# Place at root directory of the markdown project, for example:
+# $GITHUB/clickhouse-docs/.marksman.toml
+[core]
+markdown.file_extensions = ["md", "mdx"]
+text_sync = "full"
+
+[code_action]
+toc.enable = false # Enable/disable "Table of Contents" code action
+```
diff --git a/my-docs-.ignore-file-for-marksman b/my-docs-.ignore-file-for-marksman
new file mode 100644
index 00000000..b458cb10
--- /dev/null
+++ b/my-docs-.ignore-file-for-marksman
@@ -0,0 +1,19 @@
+# This is to reverse the .gitignore in the ClickHouse-docs repo, as
+# the marksman LSP ignores dirs in the .gitignore when checking
+# for links for markdown files.  This file (.ignore) gets processed
+# after .gitignore, so the negation (`!`) of the path fixes the issue
+# created by copying the files into the clickhouse-docs directory
+# structure
+
+# place at root dir of the markdown project, for example:
+# $GITHUB/clickhouse-docs/.ignore
+
+!docs/en/development
+!docs/en/engines
+!docs/en/getting-started
+!docs/en/interfaces
+!docs/en/operations
+!docs/en/sql-reference
+docs/ru
+docs/zh
+docs/_clients
diff --git a/my-docs-.marksman.toml-file-for-marksman b/my-docs-.marksman.toml-file-for-marksman
new file mode 100644
index 00000000..c62376bc
--- /dev/null
+++ b/my-docs-.marksman.toml-file-for-marksman
@@ -0,0 +1,9 @@
+# place at root dir of the markdown project, for example:
+# $GITHUB/clickhouse-docs/.marksman.toml
+[core]
+markdown.file_extensions = ["md", "mdx"]
+text_sync = "full"
+
+[code_action]
+toc.enable = false # Enable/disable "Table of Contents" code action
+
diff --git a/spell/en.utf-8.add b/spell/en.utf-8.add
index 2eb29d52..2ee5fc28 100644
--- a/spell/en.utf-8.add
+++ b/spell/en.utf-8.add
@@ -222,3 +222,5 @@ chnode2
 chnode3
 marsnet
 uuid
+Docusaurus
+LSP
diff --git a/spell/en.utf-8.add.spl b/spell/en.utf-8.add.spl
index 1a53e92f..373ccaec 100644
Binary files a/spell/en.utf-8.add.spl and b/spell/en.utf-8.add.spl differ