From b57484587f7dc3b9abf2f01cb147761eaf624406 Mon Sep 17 00:00:00 2001
From: wuyangfan <1102042793@qq.com>
Date: Mon, 18 May 2026 00:52:55 +0800
Subject: [PATCH] docs: clarify ignore handler in FAQ and exceptions pages

Align UTF-8 error-handler guidance with dump/error_handler_t docs (#4552).
---
 docs/mkdocs/docs/home/exceptions.md | 4 ++--
 docs/mkdocs/docs/home/faq.md        | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/mkdocs/docs/home/exceptions.md b/docs/mkdocs/docs/home/exceptions.md
index cfa4f57a21..d07d53e395 100644
--- a/docs/mkdocs/docs/home/exceptions.md
+++ b/docs/mkdocs/docs/home/exceptions.md
@@ -735,8 +735,8 @@ The `dump()` function only works with UTF-8 encoded strings; that is, if you ass
 
     - Store the source file with UTF-8 encoding.
     - Pass an error handler as last parameter to the `dump()` function to avoid this exception:
-        - `json::error_handler_t::replace` will replace invalid bytes sequences with `U+FFFD` 
-        - `json::error_handler_t::ignore` will silently ignore invalid byte sequences
+        - [`error_handler_t::replace`](../api/basic_json/error_handler_t.md) replaces invalid byte sequences with `U+FFFD`
+        - [`error_handler_t::ignore`](../api/basic_json/error_handler_t.md) skips invalid UTF-8 during serialization (invalid bytes do not appear in the output)
 
 ### json.exception.type_error.317
 
diff --git a/docs/mkdocs/docs/home/faq.md b/docs/mkdocs/docs/home/faq.md
index 92cc935810..eab1081cfd 100644
--- a/docs/mkdocs/docs/home/faq.md
+++ b/docs/mkdocs/docs/home/faq.md
@@ -85,7 +85,7 @@ The library supports **Unicode input** as follows:
 - The library will not replace [Unicode noncharacters](http://www.unicode.org/faq/private_use.html#nonchar1).
 - Invalid surrogates (e.g., incomplete pairs such as `\uDEAD`) will yield parse errors.
 - The strings stored in the library are UTF-8 encoded. When using the default string type (`std::string`), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
-- When you store strings with different encodings in the library, calling [`dump()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a50ec80b02d0f3f51130d4abb5d1cfdc5.html#a50ec80b02d0f3f51130d4abb5d1cfdc5) may throw an exception unless `json::error_handler_t::replace` or `json::error_handler_t::ignore` are used as error handlers.
+- When you store strings with different encodings in the library, calling [`dump()`](../api/basic_json/dump.md) may throw an exception unless [`error_handler_t::replace`](../api/basic_json/error_handler_t.md) or [`error_handler_t::ignore`](../api/basic_json/error_handler_t.md) are used. With `ignore`, invalid UTF-8 sequences are **skipped** during serialization rather than copied byte-for-byte to the output (see [#4552](https://github.com/nlohmann/json/issues/4552)).
 
 In most cases, the parser is right to complain, because the input is not UTF-8 encoded. This is especially true for Microsoft Windows, where Latin-1 or ISO 8859-1 is often the standard encoding.