diff --git a/.gitignore b/.gitignore
index 59fa1a1de3..9e8cf66a91 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ venvs
 pdf_build_src/bids-spec.pdf
 pdf_build_src/bids-spec_pandoc_log.json
 pdf_build_src/src_copy
+pdf_build_src/tests/data/output
 
 # JS/NPM
 package-lock.json
diff --git a/mkdocs.yml b/mkdocs.yml
index 82badc4288..8e7dab5cda 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -97,6 +97,8 @@ markdown_extensions:
   - toc:
       anchorlink: true
   - pymdownx.superfences
+  - admonition
+  - pymdownx.details
 plugins:
   - search
   - branchcustomization:
diff --git a/pdf_build_src/process_markdowns.py b/pdf_build_src/process_markdowns.py
index 5d30aabc21..cd114b317f 100644
--- a/pdf_build_src/process_markdowns.py
+++ b/pdf_build_src/process_markdowns.py
@@ -17,6 +17,8 @@
 
 import numpy as np
 
+from remove_admonitions import remove_admonitions
+
 sys.path.append("../tools/")
 # functions from module macros are called by eval() later on
 from mkdocs_macros_bids import macros  # noqa: F401
@@ -679,33 +681,37 @@ def process_macros(duplicated_src_dir_path):
 
     duplicated_src_dir_path = "src_copy/src"
 
-    # Step 1: make a copy of the src directory in the current directory
+    # make a copy of the src directory in the current directory
     copy_src()
 
-    # Step 2: run mkdocs macros embedded in markdown files
+    # run mkdocs macros embedded in markdown files
     process_macros(duplicated_src_dir_path)
 
-    # Step 3: copy BIDS_logo to images directory of the src_copy directory
+    # remove mkdocs admonition
+    remove_admonitions(input_folder=duplicated_src_dir_path,
+                       output_folder=duplicated_src_dir_path)
+
+    # copy BIDS_logo to images directory of the src_copy directory
     copy_bids_logo()
 
-    # Step 4: copy images from subdirectories of src_copy directory
+    # copy images from subdirectories of src_copy directory
     copy_images(duplicated_src_dir_path)
     subprocess.call("mv src_copy/src/images/images/* src_copy/src/images/", shell=True)
 
-    # Step 5: extract the latest version number, date and title
+    # extract the latest version number, date and title
     extract_header_string()
     add_header()
 
     edit_titlepage()
 
-    # Step 6: modify changelog to be a level 1 heading to facilitate section
+    # modify changelog to be a level 1 heading to facilitate section
     # separation
     modify_changelog()
 
-    # Step 7: remove all internal links
+    # remove all internal links
     assert_no_multiline_links(duplicated_src_dir_path)
     remove_internal_links_inline(duplicated_src_dir_path)
     remove_internal_links_reference(duplicated_src_dir_path)
 
-    # Step 8: correct number of dashes and fences alignment for rendering tables in PDF
+    # correct number of dashes and fences alignment for rendering tables in PDF
     correct_tables(duplicated_src_dir_path)
diff --git a/pdf_build_src/remove_admonitions.py b/pdf_build_src/remove_admonitions.py
new file mode 100644
index 0000000000..2639e67c6f
--- /dev/null
+++ b/pdf_build_src/remove_admonitions.py
@@ -0,0 +1,55 @@
+"""Script to remove all mkdocs admonition from the markdown files in a directory."""
+from __future__ import annotations
+from pathlib import Path
+from rich import print
+import shutil
+
+INDENT = "    "
+
+
+def remove_admonitions(input_folder: str | Path, output_folder: str | Path, indent: str = None):
+
+    if indent is None:
+        indent = INDENT
+
+    md_files = Path(input_folder).glob("**/*.md")
+
+    for file in md_files:
+
+        with open(file, "r", encoding="utf8") as f:
+            content = f.readlines()
+
+        output_file = Path(output_folder) / file.relative_to(input_folder)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        print(f"processing: {file}\n to: {output_file}")
+
+        with open(output_file, "w", encoding="utf8") as f:
+
+            is_admonition = False
+            counter = 0
+            for line in content:
+
+                if line.startswith("!!!"):
+                    is_admonition = True
+                    counter = 0
+                    continue
+
+                # skip first line after admonition
+                if is_admonition and counter == 0:
+                    counter += 1
+                    continue
+
+                if not line.startswith(indent):
+                    is_admonition = False
+
+                if is_admonition:
+                    line = line.lstrip(indent)
+
+                f.write(line)
+
+
+if __name__ == "__main__":
+    input_folder = Path(__file__).parent / "tests" / "data" / "input"
+    output_folder = Path(__file__).parent / "tests" / "data" / "output"
+    shutil.rmtree(output_folder)
+    remove_admonitions(input_folder, output_folder)
diff --git a/pdf_build_src/tests/data/expected/README.md b/pdf_build_src/tests/data/expected/README.md
new file mode 100644
index 0000000000..fbddfe6ea4
--- /dev/null
+++ b/pdf_build_src/tests/data/expected/README.md
@@ -0,0 +1,13 @@
+# Test inputs
+
+This input directory contains data to use for testing the pdf build code of the BIDS specification.
+
+For example the following admonition should be removed by `pdf_build_src/remove_admonitions.py`.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Nulla et euismod nulla.
+Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+nec semper lorem quam in massa.
+
+The `expected` directory should contain the documents
+as they should look like after processing.
diff --git a/pdf_build_src/tests/data/input/README.md b/pdf_build_src/tests/data/input/README.md
new file mode 100644
index 0000000000..207152d349
--- /dev/null
+++ b/pdf_build_src/tests/data/input/README.md
@@ -0,0 +1,15 @@
+# Test inputs
+
+This input directory contains data to use for testing the pdf build code of the BIDS specification.
+
+For example the following admonition should be removed by `pdf_build_src/remove_admonitions.py`.
+
+!!! note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    Nulla et euismod nulla.
+    Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+    nec semper lorem quam in massa.
+
+The `expected` directory should contain the documents
+as they should look like after processing.
diff --git a/pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md b/pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md
new file mode 100644
index 0000000000..bfc1b8509a
--- /dev/null
+++ b/pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md
@@ -0,0 +1,10 @@
+# Magnetic Resonance Imaging
+
+## Common metadata fields
+
+!!! warning "foo bar"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    Nulla et euismod nulla.
+    Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+    nec semper lorem quam in massa.
diff --git a/src/modality-specific-files/near-infrared-spectroscopy.md b/src/modality-specific-files/near-infrared-spectroscopy.md
index 1947836c17..d1552a0740 100644
--- a/src/modality-specific-files/near-infrared-spectroscopy.md
+++ b/src/modality-specific-files/near-infrared-spectroscopy.md
@@ -6,8 +6,10 @@ Please see [Citing BIDS](../introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 
-Several [example NIRS datasets](https://bids-standard.github.io/bids-examples/#nirs)
-have been formatted using this specification and can be used for practical guidance when curating a new dataset.
+!!! example "Example datasets"
+
+    Several [example NIRS datasets](https://bids-standard.github.io/bids-examples/#nirs)
+    have been formatted using this specification and can be used for practical guidance when curating a new dataset.
 
 ## NIRS recording data