diff --git a/misc_docs/syntax/decorator_expression_deprecated.mdx b/misc_docs/syntax/decorator_expression_deprecated.mdx
new file mode 100644
index 000000000..91f5b99e1
--- /dev/null
+++ b/misc_docs/syntax/decorator_expression_deprecated.mdx
@@ -0,0 +1,45 @@
+---
+id: "expression-deprecated-decorator"
+keywords: ["deprecated", "decorator"]
+name: "@deprecated"
+summary: "This is the `@deprecated` decorator."
+category: "decorators"
+---
+
+The `@deprecated` decorator is used to add deprecation notes to types, values and submodules. The compiler and editor tooling will yield a warning whenever a deprecated entity is being used.
+
+Alternatively, use the `@@deprecated` decorator to add a deprecation warning to the file level.
+
+### Examples
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+@deprecated
+type person = {id: int, name: string}
+
+@deprecated
+let customDouble = n => n * 2
+
+@deprecated("Use OtherModule.customTriple instead")
+let customTriple = n => n * 3
+
+@deprecated("Use OtherModule instead")
+module MyModule = {
+  type t
+}
+```
+
+```js
+function customDouble(n) {
+  return n << 1;
+}
+
+function customTriple(n) {
+  return Math.imul(n, 3);
+}
+
+var MyModule = {};
+```
+
+</CodeTab>
diff --git a/misc_docs/syntax/decorator_module_deprecated.mdx b/misc_docs/syntax/decorator_module_deprecated.mdx
new file mode 100644
index 000000000..387a4b2cf
--- /dev/null
+++ b/misc_docs/syntax/decorator_module_deprecated.mdx
@@ -0,0 +1,28 @@
+---
+id: "module-deprecated-decorator"
+keywords: ["deprecated", "decorator"]
+name: "@@deprecated"
+summary: "This is the `@@deprecated` decorator."
+category: "decorators"
+---
+
+The `@@deprecated` decorator is used to add a deprecation note to the file-level of a module. The compiler and editor tooling will yield a warning whenever a deprecated file module is being used.
+
+For more fine-grained control, use the `@deprecated` decorator to add deprecation warnings to specific types, values and submodules.
+
+### Examples
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+// Indicate whole module is deprecated
+@@deprecated
+
+// Indicate whole module is deprecated, with a comment
+@@deprecated("Use OtherModule instead")
+```
+
+```js
+```
+
+</CodeTab>