diff --git a/docs/configure/content-set/navigation.md b/docs/configure/content-set/navigation.md
index 09b841e82..c2bd4ae4b 100644
--- a/docs/configure/content-set/navigation.md
+++ b/docs/configure/content-set/navigation.md
@@ -8,6 +8,7 @@ Example:
 
 ```yaml
 project: 'PROJECT_NAME'
+soft_line_endings: true
 
 external_hosts:
   - EXTERNAL_LINKS_HERE
@@ -41,6 +42,11 @@ Example:
 project: 'APM Java agent reference'
 ```
 
+### `soft_line_endings`
+
+Optional key. Defaults to `false`. When enabled turns soft line endings in the markdown to hard HTML breaks `<br />`.
+
+
 ### `external_hosts`
 
 All links to external hosts must be declared in this section of `docset.yml`.
diff --git a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs
index acb969e34..b6984b10c 100644
--- a/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs
+++ b/src/Elastic.Markdown/IO/Configuration/ConfigurationFile.cs
@@ -19,6 +19,7 @@ public record ConfigurationFile : DocumentationFile
 	private readonly int _depth;
 	public string? Project { get; }
 	public Glob[] Exclude { get; } = [];
+	public bool SoftLineEndings { get; }
 
 	public string[] CrossLinkRepositories { get; } = [];
 
@@ -68,6 +69,9 @@ public ConfigurationFile(IFileInfo sourceFile, IDirectoryInfo rootPath, BuildCon
 					case "project":
 						Project = reader.ReadString(entry.Entry);
 						break;
+					case "soft_line_endings":
+						SoftLineEndings = bool.TryParse(reader.ReadString(entry.Entry), out var softLineEndings) && softLineEndings;
+						break;
 					case "exclude":
 						Exclude = [.. YamlStreamReader.ReadStringArray(entry.Entry).Select(Glob.Parse)];
 						break;
diff --git a/src/Elastic.Markdown/Myst/MarkdownParser.cs b/src/Elastic.Markdown/Myst/MarkdownParser.cs
index a55e6791e..b2489f929 100644
--- a/src/Elastic.Markdown/Myst/MarkdownParser.cs
+++ b/src/Elastic.Markdown/Myst/MarkdownParser.cs
@@ -144,7 +144,6 @@ public MarkdownPipeline Pipeline
 				.UseDiagnosticLinks()
 				.UseHeadingsWithSlugs()
 				.UseEmphasisExtras(EmphasisExtraOptions.Default)
-				.UseSoftlineBreakAsHardlineBreak()
 				.UseSubstitution()
 				.UseComments()
 				.UseYamlFrontMatter()
diff --git a/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs b/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
index b5c8eaf87..cafd79338 100644
--- a/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
+++ b/tests/Elastic.Markdown.Tests/Inline/SubstitutionTest.cs
@@ -23,7 +23,7 @@ not a comment
 	[Fact]
 	public void ReplacesSubsFromFrontMatter() =>
 		Html.Should().Contain(
-				"""Hello World!<br />"""
+				"""Hello World!"""
 			).And.Contain(
 				"""not a comment"""
 			)
@@ -52,7 +52,7 @@ not a {substitution}
 	[Fact]
 	public void PreservesSingleBracket() =>
 		Html.Should().Contain(
-				"""Hello World!<br />"""
+				"""Hello World!"""
 			).And.Contain(
 				"""not a comment"""
 			)
@@ -108,7 +108,7 @@ public class SupportsSubstitutionsFromDocSet(ITestOutputHelper output) : InlineT
 
 	[Fact]
 	public void EmitsGlobalVariable() =>
-		Html.Should().Contain("Hello World!<br />")
+		Html.Should().Contain("Hello World!")
 			.And.NotContain("{{hello-world}}")
 			.And.Contain("A variable from docset.yml")
 			.And.NotContain("{{global-var}}");
diff --git a/tests/authoring/Container/DefinitionLists.fs b/tests/authoring/Container/DefinitionLists.fs
index 2b4116301..dd8cee990 100644
--- a/tests/authoring/Container/DefinitionLists.fs
+++ b/tests/authoring/Container/DefinitionLists.fs
@@ -42,7 +42,7 @@ This is my `definition`
 """
 
     [<Fact>]
-    let ``validate HTML 2`` () =
+    let ``validate HTML`` () =
         markdown |> convertsToHtml """
               <dl>
  	            <dt>This is my
@@ -51,7 +51,6 @@ This is my `definition`
  	            <dd>
              		<p>And this is the definition
  			            <strong>body</strong>
- 			            <br>
  			            Which may contain multiple lines
  			        </p>
  		            <div class="admonition note">
diff --git a/tests/authoring/Inline/CrossLinksRedirects.fs b/tests/authoring/Inline/CrossLinksRedirects.fs
index b6f2ccce4..c7c1b5f22 100644
--- a/tests/authoring/Inline/CrossLinksRedirects.fs
+++ b/tests/authoring/Inline/CrossLinksRedirects.fs
@@ -90,7 +90,7 @@ type ``Scenario 2: Splitting a page into multiple smaller pages`` () =
     [<Fact>]
     let ``validate HTML`` () =
         markdown |> convertsToHtml $"""
-            <p><a href="{urlPrefix}/testing/redirects/second-page#zz">Scenario 2</a><br/>
+            <p><a href="{urlPrefix}/testing/redirects/second-page#zz">Scenario 2</a>
             <a href="{urlPrefix}/testing/redirects/third-page#bb">Scenario 2</a></p>
         """
 
diff --git a/tests/authoring/Inline/Substitutions.fs b/tests/authoring/Inline/Substitutions.fs
index ef128c249..d6c53e6d8 100644
--- a/tests/authoring/Inline/Substitutions.fs
+++ b/tests/authoring/Inline/Substitutions.fs
@@ -19,7 +19,7 @@ not a comment
     [<Fact>]
     let ``validate HTML: replace substitution`` () =
         markdown |> convertsToHtml """
-<p>The following should be subbed: Hello World!<br>
+<p>The following should be subbed: Hello World!
 not a comment</p>
         """
 
@@ -44,8 +44,8 @@ not a {substitution}
     [<Fact>]
     let ``validate HTML: leaves non subs alone`` () =
         markdown |> convertsToHtml """
- <p>The following should be subbed: Hello World!<br>
- 	not a comment</br>
- 	not a {{valid-key}}<br>
+ <p>The following should be subbed: Hello World!
+ 	not a comment
+ 	not a {{valid-key}}
  	not a {substitution}</p>
 """