diff --git a/docs/book/utils/markerdocs/html.go b/docs/book/utils/markerdocs/html.go
index 42f1a47e1a5..471d8a83b4f 100644
--- a/docs/book/utils/markerdocs/html.go
+++ b/docs/book/utils/markerdocs/html.go
@@ -39,10 +39,29 @@ type toHTML interface {
// Text is a chunk of text in an HTML doc.
type Text string
-// WriteHTML writes the string as HTML to the given Writer
+// WriteHTML writes the string as HTML to the given Writer while accounting for mdBook's handling
+// of backticks. Given mdBook's behavior of treating backticked content as raw text, this function
+// ensures proper rendering by preventing unnecessary HTML escaping within code snippets. Chunks
+// outside of backticks are HTML-escaped for security, while chunks inside backticks remain as raw
+// text, preserving mdBook's intended rendering of code content.
func (t Text) WriteHTML(w io.Writer) error {
- _, err := io.WriteString(w, html.EscapeString(string(t)))
- return err
+ textChunks := strings.Split(string(t), "`")
+
+ for i, chunk := range textChunks {
+ if i%2 == 0 { // Outside backticks, escape and write HTML
+ _, err := io.WriteString(w, html.EscapeString(chunk))
+ if err != nil {
+ return err
+ }
+ } else { // Inside backticks, write raw HTML
+ _, err := io.WriteString(w, "`"+chunk+"`")
+ if err != nil {
+ return err
+ }
+ }
+ }
+
+ return nil
}
// Tag is some tag with contents and attributes in an HTML doc.