diff --git a/libs/core/langchain_core/_api/deprecation.py b/libs/core/langchain_core/_api/deprecation.py
index b5105db7f8b..fa025b08e44 100644
--- a/libs/core/langchain_core/_api/deprecation.py
+++ b/libs/core/langchain_core/_api/deprecation.py
@@ -279,23 +279,22 @@ def deprecated(
             old_doc = ""
 
         # Modify the docstring to include a deprecation notice.
-        notes_header = "\nNotes\n-----"
         components = [
-            message,
-            f"Use {alternative} instead." if alternative else "",
-            addendum,
+            _message,
+            f"Use ``{_alternative}`` instead." if _alternative else "",
+            f"Use ``{_alternative_import}`` instead." if _alternative_import else "",
+            _addendum,
         ]
         details = " ".join([component.strip() for component in components if component])
         package = (
             _package or _name.split(".")[0].replace("_", "-") if "." in _name else None
         )
         since_str = f"{package}=={since}" if package else since
-        new_doc = (
-            f"[*Deprecated*] {old_doc}\n"
-            f"{notes_header if notes_header not in old_doc else ''}\n"
-            f".. deprecated:: {since_str}\n"
-            f"   {details}"
-        )
+        new_doc = f"""\
+.. deprecated:: {since_str} {details}
+
+{old_doc}\
+"""
 
         if inspect.iscoroutinefunction(obj):
             finalized = finalize(awarning_emitting_wrapper, new_doc)
diff --git a/libs/core/tests/unit_tests/_api/test_deprecation.py b/libs/core/tests/unit_tests/_api/test_deprecation.py
index a34cbcffbc8..6888fb1bb21 100644
--- a/libs/core/tests/unit_tests/_api/test_deprecation.py
+++ b/libs/core/tests/unit_tests/_api/test_deprecation.py
@@ -129,7 +129,7 @@ def test_deprecated_function() -> None:
 
         doc = deprecated_function.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
     assert not inspect.iscoroutinefunction(deprecated_function)
 
@@ -151,7 +151,7 @@ async def test_deprecated_async_function() -> None:
 
         doc = deprecated_function.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
     assert inspect.iscoroutinefunction(deprecated_async_function)
 
@@ -171,7 +171,7 @@ def test_deprecated_method() -> None:
 
         doc = obj.deprecated_method.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
     assert not inspect.iscoroutinefunction(obj.deprecated_method)
 
@@ -194,7 +194,7 @@ async def test_deprecated_async_method() -> None:
 
         doc = obj.deprecated_method.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
     assert inspect.iscoroutinefunction(obj.deprecated_async_method)
 
@@ -213,7 +213,7 @@ def test_deprecated_classmethod() -> None:
 
         doc = ClassWithDeprecatedMethods.deprecated_classmethod.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
 
 def test_deprecated_staticmethod() -> None:
@@ -233,7 +233,7 @@ def test_deprecated_staticmethod() -> None:
         )
         doc = ClassWithDeprecatedMethods.deprecated_staticmethod.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
 
 def test_deprecated_property() -> None:
@@ -253,7 +253,7 @@ def test_deprecated_property() -> None:
         )
         doc = ClassWithDeprecatedMethods.deprecated_property.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
 
 def test_whole_class_deprecation() -> None:
@@ -292,7 +292,7 @@ def test_whole_class_deprecation() -> None:
         )
         # [*Deprecated*] should be inserted only once:
         if obj.__doc__ is not None:
-            assert obj.__doc__.count("[*Deprecated*]") == 1
+            assert obj.__doc__.count(".. deprecated") == 1
 
 
 def test_whole_class_inherited_deprecation() -> None:
@@ -349,7 +349,7 @@ def test_whole_class_inherited_deprecation() -> None:
         )
         # if [*Deprecated*] was inserted only once:
         if obj.__doc__ is not None:
-            assert obj.__doc__.count("[*Deprecated*]") == 1
+            assert obj.__doc__.count(".. deprecated") == 1
 
     with warnings.catch_warnings(record=True) as warning_list:
         warnings.simplefilter("always")
@@ -373,8 +373,8 @@ def test_whole_class_inherited_deprecation() -> None:
         )
         # if [*Deprecated*] was inserted only once:
         if obj.__doc__ is not None:
-            assert obj.__doc__.count("[*Deprecated*]") == 1
-            assert "[*Deprecated*] Inherited deprecated class." in obj.__doc__
+            assert obj.__doc__.count(".. deprecated::") == 1
+            assert ".. deprecated::" in obj.__doc__
 
 
 # Tests with pydantic models
@@ -400,7 +400,7 @@ def test_deprecated_method_pydantic() -> None:
 
         doc = obj.deprecated_method.__doc__
         assert isinstance(doc, str)
-        assert doc.startswith("[*Deprecated*] original doc")
+        assert doc.startswith(".. deprecated::")
 
 
 def test_raise_error_for_bad_decorator() -> None: