From ef0b3289c4fc4e3cc45f2a75bf2440529fec18bf Mon Sep 17 00:00:00 2001 From: maliming Date: Thu, 1 Oct 2026 09:37:05 +0800 Subject: [PATCH] Break only long words in the Docs PDF renderer --- .../Pdf/DocsProjectPdfGeneratorOptions.cs | 7 +-- .../Projects/Pdf/PdfSharpHtmlToPdfRenderer.cs | 59 +++++++++++++++++++ .../Pdf/PdfSharpHtmlToPdfRenderer_Tests.cs | 23 ++++++++ 3 files changed, 85 insertions(+), 4 deletions(-) diff --git a/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/DocsProjectPdfGeneratorOptions.cs b/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/DocsProjectPdfGeneratorOptions.cs index a7ff7ce02b..0a4d085e1c 100644 --- a/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/DocsProjectPdfGeneratorOptions.cs +++ b/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/DocsProjectPdfGeneratorOptions.cs @@ -60,8 +60,8 @@ public class DocsProjectPdfGeneratorOptions HtmlStyle = @" body { margin: 15px; line-height: 1.5; font-family: Arial, 'Liberation Sans', 'DejaVu Sans', sans-serif;} - a { text-decoration: none; word-break: break-all; overflow-wrap: break-word;} - li { word-break: break-all; overflow-wrap: break-word; } + a { text-decoration: none; overflow-wrap: break-word;} + li { overflow-wrap: break-word; } .page { page-break-after: always; margin-bottom: 30px; @@ -77,7 +77,6 @@ public class DocsProjectPdfGeneratorOptions background: #f8fafc; white-space: pre-wrap; word-wrap: break-word; - word-break: break-all; } pre code { padding: 0; border: none; } code { @@ -88,6 +87,7 @@ public class DocsProjectPdfGeneratorOptions } pre { position: relative; + word-break: break-all; padding: 16px; border-radius: 8px; border: 1px solid #e2e8f0; @@ -104,7 +104,6 @@ public class DocsProjectPdfGeneratorOptions th, td { border: 1px solid #333; padding: 6px 10px; - word-break: break-all; overflow-wrap: break-word; }"; diff --git a/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer.cs b/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer.cs index f43768e28b..7ac8a94baf 100644 --- a/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer.cs +++ b/modules/docs/src/Volo.Docs.Domain/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer.cs @@ -54,6 +54,7 @@ public class PdfSharpHtmlToPdfRenderer : IHtmlToPdfRenderer, ITransientDependenc htmlDocument.LoadHtml(html.Replace("\t", " ")); ReplaceUnsupportedImages(htmlDocument); SplitMultiWordLinks(htmlDocument); + BreakLongWords(htmlDocument); PreserveHtmlEntities(htmlDocument); // HtmlRenderer ignores "page-break-after", so every document is laid out separately to start on a new page. @@ -156,6 +157,64 @@ public class PdfSharpHtmlToPdfRenderer : IHtmlToPdfRenderer, ITransientDependenc } } + protected virtual void BreakLongWords(HtmlDocument htmlDocument) + { + // HtmlRenderer does not support "overflow-wrap: break-word": a word wider than its line is clipped, and "word-break: break-all" breaks every word. + // So only the words that can not fit are allowed to break anywhere. + foreach (var textNode in htmlDocument.DocumentNode.Descendants().OfType().ToList()) + { + if (textNode.ParentNode.Name is "style" or "script" or "title" || textNode.Ancestors("pre").Any()) + { + continue; + } + + var maxWordLength = GetMaxWordLength(textNode); + var parts = SplitWords(textNode.Text); + if (!parts.Any(part => IsLongWord(part, maxWordLength))) + { + continue; + } + + foreach (var part in parts) + { + if (!IsLongWord(part, maxWordLength)) + { + textNode.ParentNode.InsertBefore(htmlDocument.CreateTextNode(part), textNode); + continue; + } + + var span = htmlDocument.CreateElement("span"); + span.SetAttributeValue("style", "word-break: break-all"); + span.AppendChild(htmlDocument.CreateTextNode(part)); + textNode.ParentNode.InsertBefore(span, textNode); + } + + textNode.Remove(); + } + } + + protected virtual int GetMaxWordLength(HtmlNode textNode) + { + // A line of the default style holds about 90 characters, but table columns are not equally wide and code uses a wider font. + var cell = textNode.Ancestors().FirstOrDefault(node => node.Name is "td" or "th"); + if (cell == null) + { + return 40; + } + + var columnCount = cell.ParentNode.ChildNodes + .Where(node => node.Name is "td" or "th") + .Sum(node => Math.Max(node.GetAttributeValue("colspan", 1), 1)); + var maxLength = Math.Max(45 / columnCount, 6); + + return textNode.Ancestors("code").Any() ? maxLength * 3 / 4 : maxLength; + } + + private static bool IsLongWord(string text, int maxLength) + { + return !text.IsNullOrWhiteSpace() && HtmlEntity.DeEntitize(text).Length > maxLength; + } + protected virtual void PreserveHtmlEntities(HtmlDocument htmlDocument) { // HtmlRenderer splits "word-break: break-all" text into single characters before decoding it, so "&" would be printed as is. diff --git a/modules/docs/test/Volo.Docs.Domain.Tests/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer_Tests.cs b/modules/docs/test/Volo.Docs.Domain.Tests/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer_Tests.cs index 7c1d815a29..ed230deaf3 100644 --- a/modules/docs/test/Volo.Docs.Domain.Tests/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer_Tests.cs +++ b/modules/docs/test/Volo.Docs.Domain.Tests/Volo/Docs/Projects/Pdf/PdfSharpHtmlToPdfRenderer_Tests.cs @@ -132,6 +132,24 @@ public class PdfSharpHtmlToPdfRenderer_Tests : DocsDomainTestBase GetAnnotations(pdf, pdf.Pages[0]).Count.ShouldBe(60); } + [Fact] + public void Should_Only_Let_Long_Words_Break_Anywhere() + { + var renderer = CreateTestRenderer(); + var longWord = new string('a', 41); + + renderer.BreakWords($"

Short words {longWord} end

") + .ShouldBe($"

Short words {longWord} end

"); + renderer.BreakWords("

" + new string('a', 40) + "

").ShouldBe("

" + new string('a', 40) + "

"); + renderer.BreakWords($"
{longWord}
").ShouldBe($"
{longWord}
"); + renderer.BreakWords("
ConfirmationIsEnabledForGetRequestsx
") + .ShouldBe("
ConfirmationIsEnabledForGetRequestsx
"); + renderer.BreakWords("
xConfirmation
") + .ShouldBe("
xConfirmation
"); + renderer.BreakWords("
AIManagement.WorkspaceAIManagement.Workspace
") + .ShouldBe("
AIManagement.WorkspaceAIManagement.Workspace
"); + } + [Fact] public void Should_Split_Multi_Word_Links_Only() { @@ -314,6 +332,11 @@ public class PdfSharpHtmlToPdfRenderer_Tests : DocsDomainTestBase return Transform(html, SplitMultiWordLinks); } + public string BreakWords(string html) + { + return Transform(html, BreakLongWords); + } + public string ReplaceImages(string html) { return Transform(html, ReplaceUnsupportedImages);