diff --git a/doc/README b/doc/README
index 728481df15..ed3e95fbab 100644
--- a/doc/README
+++ b/doc/README
@@ -1 +1,3 @@
-To run the HTML documentation build, doxygen have to be installed.
+Building the documentation requires Python 3.11 or newer because the `docs`
+extra uses MyST-Parser 5.1 and Sphinx 8. Doxygen must also be installed to build
+the HTML documentation.
diff --git a/doc/backend.md b/doc/backend.md
index 9477f573ac..3e5d634ac7 100644
--- a/doc/backend.md
+++ b/doc/backend.md
@@ -45,9 +45,8 @@ The `.pd` extension is used for model checkpoint storage, which is commonly util
 
 ### DP {{ dpmodel_icon }}
 
-:::{note}
-This backend is only for development and should not take into production.
-:::
+> [!NOTE]
+> This backend is only for development and should not take into production.
 
 - Model filename extension: `.dp`, `.yaml`, `.yml`
 
diff --git a/doc/conf.py b/doc/conf.py
index d7ad2c5673..216b4d5c73 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -201,6 +201,7 @@
     "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.min.js"
 )
 myst_enable_extensions = [
+    "alert",
     "dollarmath",
     "colon_fence",
     "substitution",
diff --git a/doc/data/system.md b/doc/data/system.md
index e809016420..bfadb8887f 100644
--- a/doc/data/system.md
+++ b/doc/data/system.md
@@ -50,9 +50,8 @@ In general, we always use the following convention of units:
 
 ## Mixed type
 
-:::{note}
-Only the [DPA-1](../model/train-se-atten.md) and [DPA-2](../model/dpa2.md) descriptors support this format.
-:::
+> [!NOTE]
+> Only the [DPA-1](../model/train-se-atten.md) and [DPA-2](../model/dpa2.md) descriptors support this format.
 
 In the standard data format, only those frames with the same fingerprint (i.e. the number of atoms of different elements) can be put together as a unified system.
 This may lead to sparse frame numbers in those rare systems.
diff --git a/doc/development/create-a-model-pt.md b/doc/development/create-a-model-pt.md
index 16c973c29d..ce902fde5a 100644
--- a/doc/development/create-a-model-pt.md
+++ b/doc/development/create-a-model-pt.md
@@ -1,10 +1,9 @@
 # Create a model in other backends {{ pytorch_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-
-In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above.
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
+>
+> In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above.
 
 If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainer, etc, you may want to read this section.
 
diff --git a/doc/development/type-embedding.md b/doc/development/type-embedding.md
index f03bda0888..027864eec1 100644
--- a/doc/development/type-embedding.md
+++ b/doc/development/type-embedding.md
@@ -86,6 +86,5 @@ build -> _pass_filter -> _filter -> _filter_lower
 
 In `fitting net`, it takes the descriptor vector as input, whose dimension is \[natoms, $M_1\times M_2$\]. Because we need to involve information on the centric atom in this step, we need to generate a matrix named `atype_embed` (of dim [natoms, nchanl]), in which each row is the type embedding vector of the specific centric atom. The input is sorted by type of centric atom, we also know the number of a particular atom type (stored in `natoms[2+i]`), thus we get the type vector of the centric atom. In the build phase of the fitting net, it will check whether type embedding exists in `input_dict` and fetch them. After that, call `embed_atom_type` function to look up the embedding vector for the type vector of the centric atom to obtain `atype_embed`, and concat input with it ([input, atype_embed]). The modified input goes through `fitting` net\` to get predicted energy.
 
-:::{note}
-You can't apply the compression method while using atom-type embedding.
-:::
+> [!NOTE]
+> You can't apply the compression method while using atom-type embedding.
diff --git a/doc/env.md b/doc/env.md
index b39a4932ab..35c7177ebc 100644
--- a/doc/env.md
+++ b/doc/env.md
@@ -1,8 +1,7 @@
 # Runtime environment variables
 
-:::{note}
-For build-time environment variables, see [Install from source code](./install/install-from-source.md).
-:::
+> [!NOTE]
+> For build-time environment variables, see [Install from source code](./install/install-from-source.md).
 
 ## All interfaces
 
diff --git a/doc/environment.yml b/doc/environment.yml
index fc96b56485..0a48cdb215 100644
--- a/doc/environment.yml
+++ b/doc/environment.yml
@@ -4,7 +4,7 @@ channels:
   - defaults
 dependencies:
   - doxygen>=1.9.1
-  - python=3.10
+  - python=3.11
   - pip>=20.1
   - pip:
       - ..[docs,cpu,torch]
diff --git a/doc/freeze/compress.md b/doc/freeze/compress.md
index 5f341b08b9..1cf643a627 100644
--- a/doc/freeze/compress.md
+++ b/doc/freeze/compress.md
@@ -1,8 +1,7 @@
 # Compress a model {{ tensorflow_icon }} {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
 
 ## Theory
 
diff --git a/doc/inference/cxx.md b/doc/inference/cxx.md
index e16f359440..4af32776ff 100644
--- a/doc/inference/cxx.md
+++ b/doc/inference/cxx.md
@@ -1,8 +1,7 @@
 # C/C++ interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 ## C++ interface
 
diff --git a/doc/inference/embedding.md b/doc/inference/embedding.md
index b4509c74ee..62786ce44f 100644
--- a/doc/inference/embedding.md
+++ b/doc/inference/embedding.md
@@ -4,13 +4,12 @@ A trained model can export learned representations ("embeddings") for downstream
 analysis, such as clustering, visualization, or training auxiliary models. A
 single forward pass produces the embeddings without computing forces or virials.
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, for energy models (including
-DPA4/SeZM and DP+ZBL / linear combinations, where the embedding comes from the
-descriptor-fitting sub-model). It also works for other descriptor-fitting models
-(dipole, polarizability, dos, property), though the `structural_feature` is only
-physically meaningful for energy models. Spin models are not supported.
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, for energy models (including
+> DPA4/SeZM and DP+ZBL / linear combinations, where the embedding comes from the
+> descriptor-fitting sub-model). It also works for other descriptor-fitting models
+> (dipole, polarizability, dos, property), though the `structural_feature` is only
+> physically meaningful for energy models. Spin models are not supported.
 
 Three embeddings are produced for each frame:
 
diff --git a/doc/inference/nodejs.md b/doc/inference/nodejs.md
index a33429f270..c4f513ab1e 100644
--- a/doc/inference/nodejs.md
+++ b/doc/inference/nodejs.md
@@ -1,8 +1,7 @@
 # Node.js interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 If [Node.js interface is installed](../install/install-nodejs.md), one can use the Node.js interface for model inference, which is a wrapper of [the header-only C++ API](./cxx.md).
 
diff --git a/doc/inference/python.md b/doc/inference/python.md
index c53ade8c31..4f6ad41b39 100644
--- a/doc/inference/python.md
+++ b/doc/inference/python.md
@@ -1,8 +1,7 @@
 # Python interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 One may use the python interface of DeePMD-kit for model inference, an example is given as follows
 
@@ -34,14 +33,13 @@ descriptors = dp.eval_descriptor(coord, cell, atype)
 
 where `descriptors` is the descriptor matrix of the system. This can also be done using the command line interface `dp eval-desc` as described in the [test documentation](../test/test.md).
 
-:::{note}
-`eval_descriptor` is the descriptor-only interface supported across backends. In
-the PyTorch backend, [`eval_embedding`](embedding.md) additionally returns the
-descriptor, per-atom feature, and per-structure feature in a single forward pass.
-PyTorch descriptor/embedding APIs accept `dtype="fp32"`, `"fp64"`, or `"native"`;
-`eval_descriptor` defaults to `native`, while `eval_embedding` defaults to
-`fp32`.
-:::
+> [!NOTE]
+> `eval_descriptor` is the descriptor-only interface supported across backends. In
+> the PyTorch backend, [`eval_embedding`](embedding.md) additionally returns the
+> descriptor, per-atom feature, and per-structure feature in a single forward pass.
+> PyTorch descriptor/embedding APIs accept `dtype="fp32"`, `"fp64"`, or `"native"`;
+> `eval_descriptor` defaults to `native`, while `eval_embedding` defaults to
+> `fp32`.
 
 Furthermore, one can use the python interface to calculate model deviation.
 
@@ -62,9 +60,8 @@ Otherwise, TensorFlow or PyTorch will never release the memory, and this may lea
 
 ## External neighbor list algorithm {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 The native neighbor list algorithm of the DeePMD-kit is in $O(N^2)$ complexity ($N$ is the number of atoms).
 While this is not a problem for small systems that quantum methods can afford, the large systems for molecular dynamics have slow performance.
diff --git a/doc/install/build-conda.md b/doc/install/build-conda.md
index b6f571f47e..03dc4a06d4 100644
--- a/doc/install/build-conda.md
+++ b/doc/install/build-conda.md
@@ -1,10 +1,8 @@
 # Building conda packages
 
-::::{danger}
-
-:::{deprecated} 3.0.0
-The official channel has been deprecated since 3.0.0.
-Refer to [conda-forge documentation](https://conda-forge.org/docs/maintainer/adding_pkgs/) for how to contribute and build packages locally.
-:::
-
-::::
+> [!CAUTION]
+>
+> :::{deprecated} 3.0.0
+> The official channel has been deprecated since 3.0.0.
+> Refer to [conda-forge documentation](https://conda-forge.org/docs/maintainer/adding_pkgs/) for how to contribute and build packages locally.
+> :::
diff --git a/doc/install/easy-install-dev.md b/doc/install/easy-install-dev.md
index 9a0154320e..875bca27c0 100644
--- a/doc/install/easy-install-dev.md
+++ b/doc/install/easy-install-dev.md
@@ -22,9 +22,8 @@ pip install -U --pre deepmd-kit[gpu,cu12,lmp,torch] --extra-index-url https://de
 
 ## Download pre-compiled C Library {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 The [pre-compiled C library](./install-from-c-library.md) can be downloaded from [here](https://nightly.link/deepmodeling/deepmd-kit/workflows/package_c/master/libdeepmd_c-0-libdeepmd_c.tar.gz.zip), or via a shell command:
 
diff --git a/doc/install/easy-install.md b/doc/install/easy-install.md
index 7c6e47a67a..1eef898316 100644
--- a/doc/install/easy-install.md
+++ b/doc/install/easy-install.md
@@ -4,14 +4,12 @@ There are various easy methods to install DeePMD-kit. Choose one that you prefer
 
 After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to train models or run LAMMPS in parallel.
 
-:::{note}
-Note: The off-line packages and conda packages require the [GNU C Library](https://www.gnu.org/software/libc/) 2.17 or above. The GPU version requires [compatible NVIDIA driver](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#minor-version-compatibility) to be installed in advance. It is possible to force conda to [override detection](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html#overriding-detected-packages) when installation, but these requirements are still necessary during runtime.
-You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for more information.
-:::
+> [!NOTE]
+> Note: The off-line packages and conda packages require the [GNU C Library](https://www.gnu.org/software/libc/) 2.17 or above. The GPU version requires [compatible NVIDIA driver](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#minor-version-compatibility) to be installed in advance. It is possible to force conda to [override detection](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html#overriding-detected-packages) when installation, but these requirements are still necessary during runtime.
+> You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for more information.
 
-:::{note}
-Python 3.10 or above is required for Python interface.
-:::
+> [!NOTE]
+> Python 3.10 or above is required for Python interface.
 
 ## Install DeePMD-kit in 1s
 
@@ -57,15 +55,13 @@ Read [conda-forge FAQ](https://conda-forge.org/docs/user/tipsandtricks.html#inst
 
 ### Official channel (deprecated)
 
-::::{danger}
-
-:::{deprecated} 3.0.0
-The official channel has been deprecated since 3.0.0, due to the challenging work of building dependencies for [multiple backends](../backend.md).
-Old packages will still be available at https://conda.deepmodeling.com.
-Maintainers will build packages in the conda-forge organization together with other conda-forge members.
-:::
-
-::::
+> [!CAUTION]
+>
+> :::{deprecated} 3.0.0
+> The official channel has been deprecated since 3.0.0, due to the challenging work of building dependencies for [multiple backends](../backend.md).
+> Old packages will still be available at https://conda.deepmodeling.com.
+> Maintainers will build packages in the conda-forge organization together with other conda-forge members.
+> :::
 
 ## Install with docker
 
@@ -195,9 +191,8 @@ pip install deepmd-kit
 
 The supported platform includes Linux x86-64 and aarch64 with GNU C Library 2.28 or above, macOS x86-64 and arm64, and Windows x86-64.
 
-:::{Warning}
-If your platform is not supported, or you want to build against the installed backends, or you want to enable ROCM support, please [build from source](install-from-source.md).
-:::
+> [!WARNING]
+> If your platform is not supported, or you want to build against the installed backends, or you want to enable ROCM support, please [build from source](install-from-source.md).
 
 [The LAMMPS module](../third-party/lammps-command.md) and [the i-PI driver](../third-party/ipi.md) are provided on Linux and macOS for the TensorFlow, PyTorch, and JAX backend. The LAMMPS module loads the installed TensorFlow and/or PyTorch runtime libraries dynamically, so it does not require both backends to be installed. To install LAMMPS and/or i-PI, add `lmp` and/or `ipi` to extras:
 
diff --git a/doc/install/install-from-c-library.md b/doc/install/install-from-c-library.md
index 836ee1a712..c7b9537df1 100644
--- a/doc/install/install-from-c-library.md
+++ b/doc/install/install-from-c-library.md
@@ -1,8 +1,7 @@
 # Install from pre-compiled C library {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}
 
 DeePMD-kit provides pre-compiled C library package (`libdeepmd_c.tar.gz`) in each [release](https://github.com/deepmodeling/deepmd-kit/releases). It can be used to build the [LAMMPS plugin](./install-lammps.md) and the [i-PI driver](./install-ipi.md), as well as many [third-party software packages](../third-party/out-of-deepmd-kit.md), without building TensorFlow and DeePMD-kit on one's own.
 It can be downloaded via the shell command:
diff --git a/doc/install/install-from-source.md b/doc/install/install-from-source.md
index 11fa69baa0..8f4b933440 100644
--- a/doc/install/install-from-source.md
+++ b/doc/install/install-from-source.md
@@ -260,11 +260,10 @@ It will print the help information like
 
 ### Install horovod and mpi4py {{ tensorflow_icon }}
 
-:::{warning}
-Horovod has not released a new version for a long time.
-As of December 2025, the latest Horovod release does not support the latest TensorFlow versions.
-You can check the patches required to support the latest TensorFlow at [conda-forge/horovod-feedstock](https://github.com/conda-forge/horovod-feedstock/blob/main/recipe/meta.yaml).
-:::
+> [!WARNING]
+> Horovod has not released a new version for a long time.
+> As of December 2025, the latest Horovod release does not support the latest TensorFlow versions.
+> You can check the patches required to support the latest TensorFlow at [conda-forge/horovod-feedstock](https://github.com/conda-forge/horovod-feedstock/blob/main/recipe/meta.yaml).
 
 [Horovod](https://github.com/horovod/horovod) and [mpi4py](https://github.com/mpi4py/mpi4py) are used for parallel training. For better performance on GPU, please follow the tuning steps in [Horovod on GPU](https://github.com/horovod/horovod/blob/master/docs/gpus.rst).
 
diff --git a/doc/install/install-gromacs.md b/doc/install/install-gromacs.md
index 4857c56d84..5162be1833 100644
--- a/doc/install/install-gromacs.md
+++ b/doc/install/install-gromacs.md
@@ -4,14 +4,12 @@ orphan: true
 
 # GROMACS patch was removed from DeePMD-kit
 
-::::{danger}
-
-:::{deprecated} v3.2.0
-The in-tree GROMACS patch was removed from the DeePMD-kit repository in v3.2.0 and is no longer maintained.
-
-For supported production workflows, use the official [LAMMPS interface](./install-lammps.md).
-
-If you need a GROMACS-based workflow, see the third-party overview in [Running MD with GROMACS](../third-party/gromacs.md) and [Interfaces out of DeePMD-kit](../third-party/out-of-deepmd-kit.md).
-:::
-
-::::
+> [!CAUTION]
+>
+> :::{deprecated} v3.2.0
+> The in-tree GROMACS patch was removed from the DeePMD-kit repository in v3.2.0 and is no longer maintained.
+>
+> For supported production workflows, use the official [LAMMPS interface](./install-lammps.md).
+>
+> If you need a GROMACS-based workflow, see the third-party overview in [Running MD with GROMACS](../third-party/gromacs.md) and [Interfaces out of DeePMD-kit](../third-party/out-of-deepmd-kit.md).
+> :::
diff --git a/doc/install/install-lammps.md b/doc/install/install-lammps.md
index 35278d6493..d9fcbc4e7c 100644
--- a/doc/install/install-lammps.md
+++ b/doc/install/install-lammps.md
@@ -135,10 +135,9 @@ If everything works fine, you will end up with an executable `${deepmd_root}/bin
 ${deepmd_root}/bin/lmp -h
 ```
 
-:::{note}
-If `${tensorflow_root}`, `${deepmd_root}`, or the path to TensorFlow Python package if applicable is different from the prefix of LAMMPS, you need to append the library path to [`RUNPATH`](https://man7.org/linux/man-pages/man8/ld.so.8.html) of `liblammps.so`. For example, use patchelf >= 0.13
-
-```sh
-patchelf --add-rpath "${tensorflow_root}/lib" liblammps.so
-```
-:::
+> [!NOTE]
+> If `${tensorflow_root}`, `${deepmd_root}`, or the path to TensorFlow Python package if applicable is different from the prefix of LAMMPS, you need to append the library path to [`RUNPATH`](https://man7.org/linux/man-pages/man8/ld.so.8.html) of `liblammps.so`. For example, use patchelf >= 0.13
+>
+> ```sh
+> patchelf --add-rpath "${tensorflow_root}/lib" liblammps.so
+> ```
diff --git a/doc/model/change-bias.md b/doc/model/change-bias.md
index 13c545ae7d..310a21e83f 100644
--- a/doc/model/change-bias.md
+++ b/doc/model/change-bias.md
@@ -1,8 +1,7 @@
 # Change the model output bias for trained model {{ tensorflow_icon }} {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
 
 The output bias of a trained model typically originates from the statistical results of the training dataset.
 
diff --git a/doc/model/dpa2.md b/doc/model/dpa2.md
index 4cbbc06e2a..d5d2b9c91c 100644
--- a/doc/model/dpa2.md
+++ b/doc/model/dpa2.md
@@ -1,8 +1,7 @@
 # Descriptor DPA-2 {{ pytorch_icon }} {{ jax_icon }} {{ paddle_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
 
 The DPA-2 model implementation. See [DPA-2 paper](https://doi.org/10.1038/s41524-024-01493-2) for more details.
 
@@ -102,18 +101,16 @@ dp --pt_expt freeze -o model.pt2 --lower-kind graph
 
 As with DPA-1's graph path (see [Difference among different backends](train-se-atten.md#difference-among-different-backends)), the graph route considers all neighbors within the cutoff rather than a fixed, padded selection, so its numeric result can differ slightly (down to the AOTInductor floating-point noise floor at non-binding `sel`, larger if `sel` is binding) from the dense/`nlist` path.
 
-:::{note}
-**Default route change in pt_expt (eager & training).** For a graph-eligible DPA-2 descriptor, the pt_expt backend now defaults to the carry-all graph route not only for `--lower-kind graph` freezing but also in **eager inference/evaluation and in (compiled) training** (`neighbor_graph_method=None` resolves to the graph). This changes the numerical behavior of existing pt_expt configurations relative to the dense neighbor-list route (by the amounts described above — negligible at non-binding `sel`). The other backends (dpmodel/PyTorch/Paddle/TensorFlow/JAX) are unaffected: they keep the dense route as their only path.
+> [!NOTE]
+> **Default route change in pt_expt (eager & training).** For a graph-eligible DPA-2 descriptor, the pt_expt backend now defaults to the carry-all graph route not only for `--lower-kind graph` freezing but also in **eager inference/evaluation and in (compiled) training** (`neighbor_graph_method=None` resolves to the graph). This changes the numerical behavior of existing pt_expt configurations relative to the dense neighbor-list route (by the amounts described above — negligible at non-binding `sel`). The other backends (dpmodel/PyTorch/Paddle/TensorFlow/JAX) are unaffected: they keep the dense route as their only path.
+>
+> To retain the legacy dense route on pt_expt:
+>
+> - **Inference / evaluation:** pass `neighbor_graph_method="legacy"` to `forward_common` / `call_common` (forces the dense neighbor-list path).
+> - **Training:** call `model.atomic_model.descriptor.disable_graph_lower()` on the constructed model before training. This flips `uses_graph_lower()` to `False`, which both the eager forward and the compiled-training lower honor, so both run the dense route consistently (the same mechanism the spin model uses to stay on the dense path). A first-class training-config knob for this is planned as a follow-up.
 
-To retain the legacy dense route on pt_expt:
-
-- **Inference / evaluation:** pass `neighbor_graph_method="legacy"` to `forward_common` / `call_common` (forces the dense neighbor-list path).
-- **Training:** call `model.atomic_model.descriptor.disable_graph_lower()` on the constructed model before training. This flips `uses_graph_lower()` to `False`, which both the eager forward and the compiled-training lower honor, so both run the dense route consistently (the same mechanism the spin model uses to stay on the dense path). A first-class training-config knob for this is planned as a follow-up.
-:::
-
-:::{note}
-**Smoothness at the cutoff.** The graph route is exactly smooth at the cutoff, like the dense path. The non-attention channels (environment matrix, switch envelope, convolution, drrd/grrg, g1g1, symmetrization) are smooth by construction. The repformer *attention* channels (`update_g1_has_attn`, `update_g2_has_attn`) additionally use a fixed-phantom-count softmax: the dense smooth-attention denominator keeps exactly `sel − n_real` padding terms at $e^{-\mathrm{attnw\_shift}}$ (a geometry-independent count); the graph kernels reproduce this by excluding masked pairs from the softmax and adding $\max(\mathrm{sel} - n_\mathrm{real}, 0)$ phantom denominator terms per center. An edge entering the cutoff sphere does so at logit $-\mathrm{attnw\_shift}$ exactly while the phantom count drops by one, so the swap is value-preserving and the energy/force are continuous (verified at the float64 noise floor, $\lesssim 10^{-13}$). This also makes the carry-all graph attention agree with the dense attention term-for-term at non-binding `sel`. The only residual $e^{-20}$-scale discontinuity remains for a center with `sel` or more *real* neighbors within the block cutoff — a regime where the dense path itself suffers a far larger discontinuity from truncating a real neighbor, i.e. where `sel` is misconfigured.
-:::
+> [!NOTE]
+> **Smoothness at the cutoff.** The graph route is exactly smooth at the cutoff, like the dense path. The non-attention channels (environment matrix, switch envelope, convolution, drrd/grrg, g1g1, symmetrization) are smooth by construction. The repformer *attention* channels (`update_g1_has_attn`, `update_g2_has_attn`) additionally use a fixed-phantom-count softmax: the dense smooth-attention denominator keeps exactly `sel − n_real` padding terms at $e^{-\mathrm{attnw\_shift}}$ (a geometry-independent count); the graph kernels reproduce this by excluding masked pairs from the softmax and adding $\max(\mathrm{sel} - n_\mathrm{real}, 0)$ phantom denominator terms per center. An edge entering the cutoff sphere does so at logit $-\mathrm{attnw\_shift}$ exactly while the phantom count drops by one, so the swap is value-preserving and the energy/force are continuous (verified at the float64 noise floor, $\lesssim 10^{-13}$). This also makes the carry-all graph attention agree with the dense attention term-for-term at non-binding `sel`. The only residual $e^{-20}$-scale discontinuity remains for a center with `sel` or more *real* neighbors within the block cutoff — a regime where the dense path itself suffers a far larger discontinuity from truncating a real neighbor, i.e. where `sel` is misconfigured.
 
 DPA-2's repformer block performs message passing (per-layer neighbor feature aggregation), so a graph-frozen `.pt2` archive additionally embeds a with-comm AOTInductor artifact. Multi-rank LAMMPS runs dispatch to this artifact and drive an MPI ghost-atom exchange (`border_op`) once per repformer layer, instead of folding ghosts onto local owners as the non-message-passing (e.g. DPA-1) graph path does. `.pt2` archives frozen with `--lower-kind graph` before this artifact was introduced do not carry it and must be re-frozen to support multi-rank inference.
 
diff --git a/doc/model/dpa3.md b/doc/model/dpa3.md
index f33b2a6208..f52cfbdc1f 100644
--- a/doc/model/dpa3.md
+++ b/doc/model/dpa3.md
@@ -1,8 +1,7 @@
 # Descriptor DPA3 {{ pytorch_icon }} {{ jax_icon }} {{ paddle_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 DPA3 is an advanced interatomic potential based on message passing.
 As a large atomic model (LAM), it is designed to integrate and jointly train on datasets from different domains,
diff --git a/doc/model/dpa4.md b/doc/model/dpa4.md
index 94270a8098..bed5d58b95 100644
--- a/doc/model/dpa4.md
+++ b/doc/model/dpa4.md
@@ -1,8 +1,7 @@
 # Descriptor DPA4 {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}
 
 DPA4 is the DeePMD-kit implementation of the SeZM (Smooth Equivariant
 Zone-bridging Model) architecture: an SO(3)-equivariant message-passing model
@@ -74,16 +73,15 @@ DPA4/SeZM defaults to `float32`
 ({ref}`precision <model[dpa4]/descriptor[dpa4]/precision>`); double precision is
 unnecessary and not recommended (see [Hardware selection](#hardware-selection)).
 
-:::{note}
-{ref}`sel <model[dpa4]/descriptor[dpa4]/sel>` behaves differently from classic
-descriptors. On the conservative **energy** path it is only an initial
-neighbor-search capacity that grows on demand, so it never truncates the
-neighbor list and you do not need to size it to the true maximum neighbor count.
-The native spin scheme shares this energy path, so it grows on demand too; only
-the denoising (`dens`) path and the `deepspin` spin scheme cap the list at
-`sum(sel)`. You can also set `sel` to `auto` or `auto:factor` to size it from
-the training data.
-:::
+> [!NOTE]
+> {ref}`sel <model[dpa4]/descriptor[dpa4]/sel>` behaves differently from classic
+> descriptors. On the conservative **energy** path it is only an initial
+> neighbor-search capacity that grows on demand, so it never truncates the
+> neighbor list and you do not need to size it to the true maximum neighbor count.
+> The native spin scheme shares this energy path, so it grows on demand too; only
+> the denoising (`dens`) path and the `deepspin` spin scheme cap the list at
+> `sum(sel)`. You can also set `sel` to `auto` or `auto:factor` to size it from
+> the training data.
 
 ### Main options
 
@@ -390,14 +388,13 @@ level `3` perturbs forces at the 2^-22 rounding scale (three orders of
 magnitude finer than TF32) and is the recommended fast setting once validated
 for the target system.
 
-:::{important}
-Set these variables **before** running `dp --pt freeze`. The exported `.pt2` is
-an AOTInductor artifact, so the SO(2) rotation branch (`DP_TRITON_INFER`), the
-matmul precision (`DP_TF32_INFER`), and inference AMP (`DP_AMP_INFER`) are
-captured into the graph at export time and are **not** re-evaluated when the
-`.pt2` is later loaded by ASE or LAMMPS. A frozen `.pt2` runs a forward-only
-package, so training-time memory-saving switches do not apply to it.
-:::
+> [!IMPORTANT]
+> Set these variables **before** running `dp --pt freeze`. The exported `.pt2` is
+> an AOTInductor artifact, so the SO(2) rotation branch (`DP_TRITON_INFER`), the
+> matmul precision (`DP_TF32_INFER`), and inference AMP (`DP_AMP_INFER`) are
+> captured into the graph at export time and are **not** re-evaluated when the
+> `.pt2` is later loaded by ASE or LAMMPS. A frozen `.pt2` runs a forward-only
+> package, so training-time memory-saving switches do not apply to it.
 
 ### Hardware selection
 
diff --git a/doc/model/dplr.md b/doc/model/dplr.md
index 64d7006dd2..94d1612c11 100644
--- a/doc/model/dplr.md
+++ b/doc/model/dplr.md
@@ -1,8 +1,7 @@
 # Deep potential long-range (DPLR) {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 Notice: **The interfaces of DPLR are not stable and subject to change**
 
diff --git a/doc/model/dprc.md b/doc/model/dprc.md
index 20880be2af..7b24b0bb6d 100644
--- a/doc/model/dprc.md
+++ b/doc/model/dprc.md
@@ -1,8 +1,7 @@
 # Deep Potential - Range Correction (DPRc) {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
 
 Deep Potential - Range Correction (DPRc) is designed to combine with QM/MM method, and corrects energies from a low-level QM/MM method to a high-level QM/MM method:
 
@@ -177,9 +176,8 @@ The DPRc model has the best practices with the [AMBER](../third-party/out-of-dee
 
 ## Pairwise DPRc
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 If one wants to correct from a low-level method into a full DFT level, and the system is too large to do full DFT calculation, one may try the experimental pairwise DPRc model.
 In a pairwise DPRc model, the total energy is divided into QM internal energy and the sum of QM/MM energy for each MM residue $l$:
diff --git a/doc/model/linear.md b/doc/model/linear.md
index 47fdd1750b..275e08c568 100644
--- a/doc/model/linear.md
+++ b/doc/model/linear.md
@@ -1,8 +1,7 @@
 ## Linear model {{ tensorflow_icon }} {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
 
 One can linearly combine existing models with arbitrary coefficients:
 
diff --git a/doc/model/overall.md b/doc/model/overall.md
index 2922cc9ccf..37470f44cb 100644
--- a/doc/model/overall.md
+++ b/doc/model/overall.md
@@ -57,9 +57,8 @@ The fitting of the following physical properties is supported
 
 1. [`ener`](train-energy.md): Fit the energy of the system. The force (derivative with atom positions), the virial (derivative with the box tensor) and the hessian (second-order derivative with atom positions) can also be trained.
 
-:::{warning}
-Due to the restrictions of torch jit script, the models trained with hessian are not jitable so that the frozen models cannot output hessians.
-:::
+> [!WARNING]
+> Due to the restrictions of torch jit script, the models trained with hessian are not jitable so that the frozen models cannot output hessians.
 
 2. [`dipole`](train-fitting-tensor.md): The dipole moment.
 1. [`polar`](train-fitting-tensor.md): The polarizability.
diff --git a/doc/model/pairtab.md b/doc/model/pairtab.md
index 106134ab06..3cb6cf12f3 100644
--- a/doc/model/pairtab.md
+++ b/doc/model/pairtab.md
@@ -1,8 +1,7 @@
 # Interpolation or combination with a pairwise potential {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
 
 ## Theory
 
@@ -60,9 +59,8 @@ in the order of Type_0-Type_0, Type_0-Type_1, ..., Type_0-Type_N, Type_1-Type_1,
 
 The interaction should be smooth at the cut-off distance.
 
-:::{note}
-In instances where the interaction at the cut-off distance is not delineated within the table file, extrapolation will be conducted utilizing the available interaction data. This extrapolative procedure guarantees a smooth transition from the table-provided value to `0` whenever feasible.
-:::
+> [!NOTE]
+> In instances where the interaction at the cut-off distance is not delineated within the table file, extrapolation will be conducted utilizing the available interaction data. This extrapolative procedure guarantees a smooth transition from the table-provided value to `0` whenever feasible.
 
 ## Interpolation with a short-range pairwise potential
 
@@ -102,11 +100,10 @@ To combine with a pairwise potential, use the [linear model](./linear.md):
 
 The {ref}`rcut <model[pairtab]/rcut>` can be larger than that of the DP model.
 
-:::{note}
-The above example shows a example of combining D3 dispersion.
-However, it is more efficient to train a model using plain DFT calculations without the dispersion correction, and add the dispersion correction during the simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command).
-Training against data with dispersion directly is discouraged.
-See the [D3 dispersion section](../third-party/lammps-command.md#d3-dispersion) for details.
-:::
+> [!NOTE]
+> The above example shows an example of combining D3 dispersion.
+> However, it is more efficient to train a model using plain DFT calculations without the dispersion correction, and add the dispersion correction during the simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command).
+> Training against data with dispersion directly is discouraged.
+> See the [D3 dispersion section](../third-party/lammps-command.md#d3-dispersion) for details.
 
 [^1]: This section is built upon Jinzhe Zeng, Duo Zhang, Denghui Lu, Pinghui Mo, Zeyu Li, Yixiao Chen, Marián Rynik, Li'ang Huang, Ziyao Li, Shaochen Shi, Yingze Wang, Haotian Ye, Ping Tuo, Jiabin Yang, Ye Ding, Yifan Li, Davide Tisi, Qiyu Zeng, Han Bao, Yu Xia, Jiameng Huang, Koki Muraoka, Yibo Wang, Junhan Chang, Fengbo Yuan, Sigbjørn Løland Bore, Chun Cai, Yinnian Lin, Bo Wang, Jiayan Xu, Jia-Xin Zhu, Chenxing Luo, Yuzhi Zhang, Rhys E. A. Goodall, Wenshuo Liang, Anurag Kumar Singh, Sikai Yao, Jingchao Zhang, Renata Wentzcovitch, Jiequn Han, Jie Liu, Weile Jia, Darrin M. York, Weinan E, Roberto Car, Linfeng Zhang, Han Wang, [J. Chem. Phys. 159, 054801 (2023)](https://doi.org/10.1063/5.0155600) licensed under a [Creative Commons Attribution (CC BY) license](http://creativecommons.org/licenses/by/4.0/).
diff --git a/doc/model/train-energy-hessian.md b/doc/model/train-energy-hessian.md
index 092f8d30e3..dc1ca38fe8 100644
--- a/doc/model/train-energy-hessian.md
+++ b/doc/model/train-energy-hessian.md
@@ -1,8 +1,7 @@
 # Fit energy Hessian {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}
 
 To train a model that takes Hessian matrices, i.e., the second order derivatives of energies w.r.t coordinates as input, you only need to prepare full Hessian matrices and modify the `loss` section to define the Hessian-specific settings, keeping other sections the same as the normal energy model's input script.
 
@@ -91,9 +90,8 @@ The detailed loss can be found in `lcurve.out`:
 
 ## Test the Model
 
-:::{warning}
-A model trained with Hessian cannot be frozen. If freezing is enforced, the model will be treated as a standard energy model, and the frozen one will no longer be able to output Hessian predictions.
-:::
+> [!WARNING]
+> A model trained with Hessian cannot be frozen. If freezing is enforced, the model will be treated as a standard energy model, and the frozen one will no longer be able to output Hessian predictions.
 
 If one do freeze and test a Hessian model using the commands:
 
diff --git a/doc/model/train-energy-spin.md b/doc/model/train-energy-spin.md
index eebc33fe33..e71ff743fa 100644
--- a/doc/model/train-energy-spin.md
+++ b/doc/model/train-energy-spin.md
@@ -1,31 +1,28 @@
 # Fit spin energy {{ tensorflow_icon }} {{ pytorch_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
 
 To train a model that takes additional spin information as input, you only need to modify the following sections to define the spin-specific settings,
 keeping other sections the same as the normal energy model's input script.
 
-:::{warning}
-Note that when adding spin into the model, there will be some implicit modifications automatically done by the program:
-
-- In the TensorFlow backend, the `se_e2_a` descriptor will treat those atom types with spin as new (virtual) types,
-  and duplicate their corresponding selected numbers of neighbors ({ref}`sel <model[standard]/descriptor[se_e2_a]/sel>`) from their real atom types.
-- In the PyTorch backend, if spin settings are added, all the types (with or without spin) will have their virtual types.
-  The `se_e2_a` descriptor will thus double the {ref}`sel <model[standard]/descriptor[se_e2_a]/sel>` list,
-  while in other descriptors with mixed types (such as `dpa1` or `dpa2`), the sel number will not be changed for clarity.
-  If you are using descriptors with mixed types, to achieve better performance,
-  you should manually extend your sel number (maybe double) depending on the balance between performance and efficiency.
-:::
+> [!WARNING]
+> Note that when adding spin into the model, there will be some implicit modifications automatically done by the program:
+>
+> - In the TensorFlow backend, the `se_e2_a` descriptor will treat those atom types with spin as new (virtual) types,
+>   and duplicate their corresponding selected numbers of neighbors ({ref}`sel <model[standard]/descriptor[se_e2_a]/sel>`) from their real atom types.
+> - In the PyTorch backend, if spin settings are added, all the types (with or without spin) will have their virtual types.
+>   The `se_e2_a` descriptor will thus double the {ref}`sel <model[standard]/descriptor[se_e2_a]/sel>` list,
+>   while in other descriptors with mixed types (such as `dpa1` or `dpa2`), the sel number will not be changed for clarity.
+>   If you are using descriptors with mixed types, to achieve better performance,
+>   you should manually extend your sel number (maybe double) depending on the balance between performance and efficiency.
 
 ## Spin
 
 The spin settings are given by the {ref}`spin <model/spin>` section, which sets the magnetism for each type of atoms as described in the following sections.
 
-:::{note}
-Note that the construction of spin settings is different between TensorFlow and PyTorch/DP.
-:::
+> [!NOTE]
+> Note that the construction of spin settings is different between TensorFlow and PyTorch/DP.
 
 ### Spin settings in TensorFlow
 
@@ -72,13 +69,12 @@ See `se_e2_a` examples in `$deepmd_source_dir/examples/spin/se_e2_a/input_torch.
   List of float values with shape of `ntypes` or `ntypes_spin` or one single float value for all types,
   only used when {ref}`use_spin <model/spin[ener_spin]/use_spin>` is True for each atom type.
 
-:::{note}
-It should be noted that the spin models in PyTorch/DP are capable of addressing scenarios where the spin approaches zero
-(indicating the virtual atom is in close proximity to the real atom) by adjusting the non-zero
-{ref}`env_protection <model[standard]/descriptor[se_e2_a]/env_protection>` parameter within the descriptor.
-This parameter is set to 0.01 by default in the spin model. It appears that a value of 0.01 is generally sufficient for maintaining model stability.
-For systems with nearly zero spin, users can also consider tuning this parameter to potentially enhance stability.
-:::
+> [!NOTE]
+> It should be noted that the spin models in PyTorch/DP are capable of addressing scenarios where the spin approaches zero
+> (indicating the virtual atom is in close proximity to the real atom) by adjusting the non-zero
+> {ref}`env_protection <model[standard]/descriptor[se_e2_a]/env_protection>` parameter within the descriptor.
+> This parameter is set to 0.01 by default in the spin model. It appears that a value of 0.01 is generally sufficient for maintaining model stability.
+> For systems with nearly zero spin, users can also consider tuning this parameter to potentially enhance stability.
 
 ## Spin Loss
 
@@ -146,9 +142,8 @@ If one does not want to train with virial, then he/she may set the virial prefac
 
 ## Data format
 
-:::{note}
-Note that the spin data format is different between TensorFlow and PyTorch/DP.
-:::
+> [!NOTE]
+> Note that the spin data format is different between TensorFlow and PyTorch/DP.
 
 ### Spin data format in TensorFlow
 
diff --git a/doc/model/train-energy.md b/doc/model/train-energy.md
index 3c053ac535..e2d380e6f0 100644
--- a/doc/model/train-energy.md
+++ b/doc/model/train-energy.md
@@ -1,8 +1,7 @@
 # Fit energy {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ paddle_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
 
 In this section, we will take `$deepmd_source_dir/examples/water/se_e2_a/input.json` as an example of the input file.
 
@@ -152,9 +151,8 @@ If one does not want to train with virial, then he/she may set the virial prefac
 
 ### Prefactor force loss with default atom preference
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
 
 When using the prefactor force loss (controlled by {ref}`start_pref_pf <loss[ener]/start_pref_pf>` and {ref}`limit_pref_pf <loss[ener]/limit_pref_pf>`), the training data typically requires an `atom_pref.npy` file in each system directory to specify per-atom prefactors $q_k$. If `atom_pref.npy` is not provided, the {ref}`use_default_pf <loss[ener]/use_default_pf>` option can be set to `true` to use a default atom preference of 1.0 for all atoms:
 
diff --git a/doc/model/train-fitting-dos.md b/doc/model/train-fitting-dos.md
index 386479acc3..357c045006 100644
--- a/doc/model/train-fitting-dos.md
+++ b/doc/model/train-fitting-dos.md
@@ -1,8 +1,7 @@
 # Fit electronic density of states (DOS) {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 Here we present an API to DeepDOS model, which can be used to fit electronic density of state (DOS) (which is a vector).
 
diff --git a/doc/model/train-fitting-population.md b/doc/model/train-fitting-population.md
index 0d1bb3ece2..e00bfbc9bb 100644
--- a/doc/model/train-fitting-population.md
+++ b/doc/model/train-fitting-population.md
@@ -1,8 +1,7 @@
 # Fit atomic charge population {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}
 
 Here we present an API to DeepPopulation model, which can be used to fit the atomic charge population.
 
diff --git a/doc/model/train-fitting-property.md b/doc/model/train-fitting-property.md
index 6517658b7a..b71a0c7522 100644
--- a/doc/model/train-fitting-property.md
+++ b/doc/model/train-fitting-property.md
@@ -1,8 +1,7 @@
 # Fit other properties {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 Here we present an API to DeepProperty model, which can be used to fit other properties like band gap, bulk modulus, critical temperature, etc.
 
diff --git a/doc/model/train-fitting-tensor.md b/doc/model/train-fitting-tensor.md
index 96c7324d7e..5df31bca0a 100644
--- a/doc/model/train-fitting-tensor.md
+++ b/doc/model/train-fitting-tensor.md
@@ -1,8 +1,7 @@
 # Fit `tensor` like `Dipole` and `Polarizability` {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 Unlike `energy`, which is a scalar, one may want to fit some high dimensional physical quantity, like `dipole` (vector) and `polarizability` (matrix, shorted as `polar`). Deep Potential has provided different APIs to do this. In this example, we will show you how to train a model to fit a water system. A complete training input script of the examples can be found in
 
diff --git a/doc/model/train-hybrid.md b/doc/model/train-hybrid.md
index ca4b285c3a..06f5daf481 100644
--- a/doc/model/train-hybrid.md
+++ b/doc/model/train-hybrid.md
@@ -1,8 +1,7 @@
 # Descriptor `"hybrid"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 This descriptor hybridizes multiple descriptors to form a new descriptor. For example, we have a list of descriptors denoted by $\mathcal D_1$, $\mathcal D_2$, ..., $\mathcal D_N$, the hybrid descriptor this the concatenation of the list, i.e. $\mathcal D = (\mathcal D_1, \mathcal D_2, \cdots, \mathcal D_N)$.
 
diff --git a/doc/model/train-se-a-mask.md b/doc/model/train-se-a-mask.md
index c47759e69c..eae5526409 100644
--- a/doc/model/train-se-a-mask.md
+++ b/doc/model/train-se-a-mask.md
@@ -1,8 +1,7 @@
 # Descriptor `"se_a_mask"` {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 Descriptor `se_a_mask` is a concise implementation of the descriptor `se_e2_a`,
 but functions slightly differently.
diff --git a/doc/model/train-se-atten.md b/doc/model/train-se-atten.md
index 56bde5dbdc..05881436a1 100644
--- a/doc/model/train-se-atten.md
+++ b/doc/model/train-se-atten.md
@@ -1,8 +1,7 @@
 # Descriptor `"se_atten"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ paddle_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
 
 ![ALT](../images/model_se_atten.png "model_se_atten")
 
@@ -132,9 +131,8 @@ You can use descriptor `"se_atten_v2"` and is not allowed to set `tebd_input_mod
 
 Practical evidence demonstrates that `"se_atten_v2"` offers better and more stable performance compared to `"se_atten"`.
 
-:::{note}
-Model compression support differs across backends. See [Model compression](#model-compression) for backend-specific requirements.
-:::
+> [!NOTE]
+> Model compression support differs across backends. See [Model compression](#model-compression) for backend-specific requirements.
 
 ## Type embedding
 
diff --git a/doc/model/train-se-e2-a-tebd.md b/doc/model/train-se-e2-a-tebd.md
index a97eae5499..01bb0d1ad9 100644
--- a/doc/model/train-se-e2-a-tebd.md
+++ b/doc/model/train-se-e2-a-tebd.md
@@ -1,8 +1,7 @@
 # Type embedding approach {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 We generate specific a type embedding vector for each atom type so that we can share one descriptor embedding net and one fitting net in total, which decline training complexity largely.
 
diff --git a/doc/model/train-se-e2-a.md b/doc/model/train-se-e2-a.md
index e972f2614b..7a7186590c 100644
--- a/doc/model/train-se-e2-a.md
+++ b/doc/model/train-se-e2-a.md
@@ -1,8 +1,7 @@
 # Descriptor `"se_e2_a"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ paddle_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, Paddle {{ paddle_icon }}, DP {{ dpmodel_icon }}
 
 The notation of `se_e2_a` is short for the Deep Potential Smooth Edition (DeepPot-SE) constructed from all information (both angular and radial) of atomic configurations. The `e2` stands for the embedding with two-atoms information. This descriptor was described in detail in [the DeepPot-SE paper](https://arxiv.org/abs/1805.09003).
 
diff --git a/doc/model/train-se-e2-r.md b/doc/model/train-se-e2-r.md
index 6e310f4a20..d5b8804788 100644
--- a/doc/model/train-se-e2-r.md
+++ b/doc/model/train-se-e2-r.md
@@ -1,8 +1,7 @@
 # Descriptor `"se_e2_r"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 The notation of `se_e2_r` is short for the Deep Potential Smooth Edition (DeepPot-SE) constructed from the radial information of atomic configurations. The `e2` stands for the embedding with two-atom information.
 
diff --git a/doc/model/train-se-e3-tebd.md b/doc/model/train-se-e3-tebd.md
index f0001f4e67..55295e6e86 100644
--- a/doc/model/train-se-e3-tebd.md
+++ b/doc/model/train-se-e3-tebd.md
@@ -1,8 +1,7 @@
 # Descriptor `"se_e3_tebd"` {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 The notation of `se_e3_tebd` is short for the three-body embedding descriptor with type embeddings, where the notation `se` denotes the Deep Potential Smooth Edition (DeepPot-SE).
 The embedding takes bond angles between a central atom and its two neighboring atoms (denoted by `e3`) and their type embeddings (denoted by `tebd`) as input.
diff --git a/doc/model/train-se-e3.md b/doc/model/train-se-e3.md
index 1eda986392..bac09dcced 100644
--- a/doc/model/train-se-e3.md
+++ b/doc/model/train-se-e3.md
@@ -1,8 +1,7 @@
 # Descriptor `"se_e3"` {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}, DP {{ dpmodel_icon }}
 
 The notation of `se_e3` is short for three-body embedding DeepPot-SE, which incorporates embedded bond-angle information.
 The embedding takes bond angles between a central atom and its two neighboring atoms as input (denoted by `e3`).
diff --git a/doc/nvnmd/nvnmd.md b/doc/nvnmd/nvnmd.md
index bd14b5a25e..4c1c97c6ce 100644
--- a/doc/nvnmd/nvnmd.md
+++ b/doc/nvnmd/nvnmd.md
@@ -1,8 +1,7 @@
 # Introduction {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 NVNMD stands for non-von Neumann molecular dynamics.
 
diff --git a/doc/requirements.txt b/doc/requirements.txt
index c8a8e2d868..4dbea5099c 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,4 +1,4 @@
 .[docs,cpu,torch]
 # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309
 docutils!=0.18.*,!=0.19.*
-sphinx>=7
+sphinx>=8
diff --git a/doc/third-party/ase.md b/doc/third-party/ase.md
index 111dbe80cb..c1e9929648 100644
--- a/doc/third-party/ase.md
+++ b/doc/third-party/ase.md
@@ -1,8 +1,7 @@
 # Use deep potential with ASE
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 Deep potential can be set up as a calculator with ASE to obtain potential energies and forces.
 
diff --git a/doc/third-party/dpdata.md b/doc/third-party/dpdata.md
index ddb8f13aad..a2fa7b216d 100644
--- a/doc/third-party/dpdata.md
+++ b/doc/third-party/dpdata.md
@@ -1,8 +1,7 @@
 # Use deep potential with dpdata
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 DeePMD-kit provides a driver for [dpdata](https://github.com/deepmodeling/dpdata) >=0.2.7 via the plugin mechanism, making it possible to call the `predict` method for `System` class:
 
diff --git a/doc/third-party/gromacs.md b/doc/third-party/gromacs.md
index d4da93a97a..056fb25513 100644
--- a/doc/third-party/gromacs.md
+++ b/doc/third-party/gromacs.md
@@ -1,12 +1,10 @@
 # Running MD with GROMACS
 
-::::{important}
-
-:::{deprecated} v3.2.0
-The official in-tree GROMACS patch was removed from DeePMD-kit in v3.2.0 and is no longer maintained.
-:::
-
-::::
+> [!IMPORTANT]
+>
+> :::{deprecated} v3.2.0
+> The official in-tree GROMACS patch was removed from DeePMD-kit in v3.2.0 and is no longer maintained.
+> :::
 
 DeePMD-kit may still be used with GROMACS through third-party integrations maintained outside this repository.
 
diff --git a/doc/third-party/ipi.md b/doc/third-party/ipi.md
index 117512138e..33a90c56c8 100644
--- a/doc/third-party/ipi.md
+++ b/doc/third-party/ipi.md
@@ -1,8 +1,7 @@
 # Run path-integral MD with i-PI
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 The i-PI works in a client-server model. The i-PI provides the server for integrating the replica positions of atoms, while the DeePMD-kit provides a client named `dp_ipi` that computes the interactions (including energy, forces and virials). The server and client communicate via the Unix domain socket or the Internet socket. Installation instructions for i-PI can be found [here](../install/install-ipi.md). The client can be started by
 
diff --git a/doc/third-party/jaxmd.md b/doc/third-party/jaxmd.md
index 0b7cf2c2fd..6d594d6779 100644
--- a/doc/third-party/jaxmd.md
+++ b/doc/third-party/jaxmd.md
@@ -1,8 +1,7 @@
 # Run MD with JAX-MD
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 DeePMD-kit provides a JAX-MD compatible interface for DeePMD models trained with
 the JAX backend. The interface adapts a DeePMD model to the usual JAX-MD style,
diff --git a/doc/third-party/lammps-command.md b/doc/third-party/lammps-command.md
index 94632e4b65..2319376d95 100644
--- a/doc/third-party/lammps-command.md
+++ b/doc/third-party/lammps-command.md
@@ -1,13 +1,11 @@
 # Run MD with LAMMPS
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
-:::{note}
-Each MPI rank can only use at most one GPU card.
-See [How to control the parallelism of a job](../troubleshooting/howtoset_num_nodes.md) for details.
-:::
+> [!NOTE]
+> Each MPI rank can only use at most one GPU card.
+> See [How to control the parallelism of a job](../troubleshooting/howtoset_num_nodes.md) for details.
 
 ## units
 
@@ -147,9 +145,8 @@ pair_style deepspin models ... keyword value ...
   and the model deviation will be computed among all models every `out_freq` timesteps.
 - keyword = _out_file_ or _out_freq_ or _fparam_ or _fparam_from_compute_ or _aparam_from_compute_ or _atomic_ or _relative_ or _aparam_ or _ttm_
 
-:::{note}
-Please note that the virial and atomic virial are not currently supported in spin models.
-:::
+> [!NOTE]
+> Please note that the virial and atomic virial are not currently supported in spin models.
 
 <pre>
     <i>out_file</i> value = filename
@@ -199,9 +196,8 @@ The unit follows [LAMMPS units](#units) and the [scale factor](https://docs.lamm
 
 Other settings and output for this pair style is the same as `deepmd` pair style, please see the detailed description [above](#pair_style-deepmd).
 
-:::{note}
-Please note that the virial and atomic virial are not currently supported in spin models.
-:::
+> [!NOTE]
+> Please note that the virial and atomic virial are not currently supported in spin models.
 
 ### Restrictions
 
@@ -333,9 +329,8 @@ If you use these features please cite [D. Tisi, L. Zhang, R. Bertossa, H. Wang,
 
 ### D3 dispersion
 
-:::{note}
-Requires LAMMPS version 4Feb2025 or newer.
-:::
+> [!NOTE]
+> Requires LAMMPS version 4Feb2025 or newer.
 
 The DP model can be trained using plain DFT calculations without the dispersion correction, and the dispersion correction can be added during the simulation via the [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command).
 For example, when `water.pb` is trained against the PBE0 functional, the simulation can be performed under the PBE0-D3 level with the following commands:
diff --git a/doc/third-party/nvalchemi.md b/doc/third-party/nvalchemi.md
index ac2af9846a..b08d756308 100644
--- a/doc/third-party/nvalchemi.md
+++ b/doc/third-party/nvalchemi.md
@@ -8,12 +8,11 @@ thin adapter, `DPA4Wrapper`, that exposes a trained DPA-4 / SeZM model to any
 unmodified; the wrapper only translates between the `nvalchemi` graph batch and
 the model's internal interface.
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, for DPA-4 / SeZM energy
-models. `nvalchemi-toolkit` is an optional dependency and must be installed
-separately. A CUDA device is recommended, since `nvalchemi`'s neighbour-list and
-integrator kernels are GPU-accelerated.
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, for DPA-4 / SeZM energy
+> models. `nvalchemi-toolkit` is an optional dependency and must be installed
+> separately. A CUDA device is recommended, since `nvalchemi`'s neighbour-list and
+> integrator kernels are GPU-accelerated.
 
 ## Installation
 
diff --git a/doc/train/finetuning.md b/doc/train/finetuning.md
index 563aa76e08..f6d167ac6e 100644
--- a/doc/train/finetuning.md
+++ b/doc/train/finetuning.md
@@ -1,8 +1,7 @@
 # Finetune the pre-trained model {{ tensorflow_icon }} {{ pytorch_icon }} {{ paddle_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, Paddle {{ paddle_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, Paddle {{ paddle_icon }}
 
 Pretraining-and-finetuning is a widely used approach in other fields such as Computer Vision (CV) or Natural Language Processing (NLP)
 to vastly reduce the training cost, while it's not trivial in potential models.
@@ -28,11 +27,10 @@ $ dp train input.json --finetune pretrained.pb
 The command above will change the energy bias in the last layer of the fitting net in `pretrained.pb`,
 according to the training dataset in input.json.
 
-:::{warning}
-Note that in TensorFlow, model parameters including the `type_map` will be overwritten based on those in the pre-trained model.
-Please ensure you are familiar with the configurations in the pre-trained model, especially `type_map`, before starting the fine-tuning process.
-The elements in the training dataset must be contained in the pre-trained dataset.
-:::
+> [!WARNING]
+> Note that in TensorFlow, model parameters including the `type_map` will be overwritten based on those in the pre-trained model.
+> Please ensure you are familiar with the configurations in the pre-trained model, especially `type_map`, before starting the fine-tuning process.
+> The elements in the training dataset must be contained in the pre-trained dataset.
 
 The finetune procedure will inherit the model structures in `pretrained.pb`,
 and thus it will ignore the model parameters in `input.json`,
@@ -105,13 +103,12 @@ one can select a specific branch (e.g., `CHOOSEN_BRANCH`) included in `multitask
 $ dp --pt train input.json --finetune multitask_pretrained.pt --model-branch CHOOSEN_BRANCH
 ```
 
-:::{note}
-One can check the available model branches in multi-task pre-trained model by referring to the documentation of the pre-trained model or by using the following command:
-
-```bash
-$ dp --pt show multitask_pretrained.pt model-branch
-```
-:::
+> [!NOTE]
+> One can check the available model branches in multi-task pre-trained model by referring to the documentation of the pre-trained model or by using the following command:
+>
+> ```bash
+> dp --pt show multitask_pretrained.pt model-branch
+> ```
 
 This command will start fine-tuning based on the pre-trained model's descriptor and the selected branch's fitting net.
 If --model-branch is not set or set to "RANDOM", a randomly initialized fitting net will be used.
@@ -250,13 +247,12 @@ one can select a specific branch (e.g., `CHOOSEN_BRANCH`) included in `multitask
 $ dp --pd train input.json --finetune multitask_pretrained.pd --model-branch CHOOSEN_BRANCH
 ```
 
-:::{note}
-One can check the available model branches in multi-task pre-trained model by refering to the documentation of the pre-trained model or by using the following command:
-
-```bash
-$ dp --pd show multitask_pretrained.pd model-branch
-```
-:::
+> [!NOTE]
+> One can check the available model branches in multi-task pre-trained model by referring to the documentation of the pre-trained model or by using the following command:
+>
+> ```bash
+> dp --pd show multitask_pretrained.pd model-branch
+> ```
 
 This command will start fine-tuning based on the pre-trained model's descriptor and the selected branch's fitting net.
 If --model-branch is not set or set to "RANDOM", a randomly initialized fitting net will be used.
diff --git a/doc/train/multi-task-training.md b/doc/train/multi-task-training.md
index 515eeeaa79..6ebe5b4fbb 100644
--- a/doc/train/multi-task-training.md
+++ b/doc/train/multi-task-training.md
@@ -1,12 +1,10 @@
 # Multi-task training {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}
 
-:::{warning}
-We have deprecated TensorFlow backend multi-task training, please use the PyTorch one.
-:::
+> [!WARNING]
+> We have deprecated TensorFlow backend multi-task training, please use the PyTorch one.
 
 ## Theory
 
@@ -104,9 +102,8 @@ users can refer to [this section](./finetuning.md#fine-tuning-from-a-multi-task-
 
 ## Multi-task specific parameters
 
-:::{note}
-Details of some parameters that are the same as [the regular parameters](./train-input.rst) are not shown below.
-:::
+> [!NOTE]
+> Details of some parameters that are the same as [the regular parameters](./train-input.rst) are not shown below.
 
 ```{eval-rst}
 .. dargs::
diff --git a/doc/train/parallel-training.md b/doc/train/parallel-training.md
index 08a46b3284..7c032179c7 100644
--- a/doc/train/parallel-training.md
+++ b/doc/train/parallel-training.md
@@ -1,8 +1,7 @@
 # Parallel training {{ tensorflow_icon }} {{ pytorch_icon }} {{ paddle_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, Paddle {{ paddle_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, Paddle {{ paddle_icon }}
 
 ## TensorFlow Implementation {{ tensorflow_icon }}
 
@@ -282,8 +281,7 @@ Then, run the script on the first node with:
 mpirun run_pp.sh
 ```
 
-:::{note}
-
-If `NUM_WORKERS` is too large, it may cause the program to be terminated by the system;
-if it is too small, it may slow down data reading. You can try adjusting it to an appropriate size.
-:::
+> [!NOTE]
+>
+> If `NUM_WORKERS` is too large, it may cause the program to be terminated by the system;
+> if it is too small, it may slow down data reading. You can try adjusting it to an appropriate size.
diff --git a/doc/train/tensorboard.md b/doc/train/tensorboard.md
index 3c45ebba34..3631aa8d73 100644
--- a/doc/train/tensorboard.md
+++ b/doc/train/tensorboard.md
@@ -1,8 +1,7 @@
 # TensorBoard Usage {{ tensorflow_icon }} {{ pytorch_icon }} {{ paddle_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, Paddle {{ paddle_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, Paddle {{ paddle_icon }}
 
 TensorBoard provides the visualization and tooling needed for machine learning
 experimentation. Full instructions for TensorBoard can be found
diff --git a/doc/train/training.md b/doc/train/training.md
index 306c396504..df1341b4ee 100644
--- a/doc/train/training.md
+++ b/doc/train/training.md
@@ -94,6 +94,5 @@ plt.show()
 
 Checkpoints will be written to files with the prefix {ref}`save_ckpt <training/save_ckpt>` every {ref}`save_freq <training/save_freq>` training steps.
 
-:::{warning}
-It is warned that the example water data (in folder `examples/water/data`) is of very limited amount, is provided only for testing purposes, and should not be used to train a production model.
-:::
+> [!WARNING]
+> It is warned that the example water data (in folder `examples/water/data`) is of very limited amount, is provided only for testing purposes, and should not be used to train a production model.
diff --git a/pyproject.toml b/pyproject.toml
index 6216438ac4..4307833ca7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -104,10 +104,10 @@ dpa-adapt = [
     "e3nn",
 ]
 docs = [
-    "sphinx>=3.1.1",
+    "sphinx>=8",
     "sphinx-book-theme",
-    "myst-nb>=1.0.0",
-    "myst-parser>=0.19.2",
+    "myst-nb>=1.4.0",
+    "myst-parser>=5.1.0",
     "sphinx-design",
     "breathe",
     "exhale>=0.3.7",