[Repo Assist] Make MarkdownRange non-optional in MarkdownSpan and MarkdownParagraph (fixes #742) (#1067)

* Make MarkdownRange non-optional in MarkdownSpan and MarkdownParagraph

Replace all `range: MarkdownRange option` fields in the MarkdownSpan
and MarkdownParagraph discriminated unions with `range: MarkdownRange`,
using `MarkdownRange.zero` as the fallback where no range was available.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci: trigger CI checks

* Fix docs/evaluation.fsx: use MarkdownRange.zero instead of None after breaking change

The PR changed MarkdownRange from option to non-optional in all DU cases.
docs/evaluation.fsx was missed and still used None for range arguments in
Literal, Paragraph, and ListBlock constructors.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci: trigger checks

---------

Co-authored-by: GitHub Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Don Syme <dsyme@users.noreply.github.com>

Author: 4 people

RELEASE_NOTES.md

@@ -2,14 +2,19 @@
 
 ## [Unreleased]
 
+### Refactored
+* Split `MarkdownParser.fs` (1500 lines) into `MarkdownInlineParser.fs` (inline formatting) and `MarkdownParser.fs` (block-level parsing) for better maintainability. [#1022](https://github.com/fsprojects/FSharp.Formatting/issues/1022)
+
 ### Added
 * Add `dotnet fsdocs convert` command to convert a single `.md`, `.fsx`, or `.ipynb` file to HTML (or another output format) without building a full documentation site. [#811](https://github.com/fsprojects/FSharp.Formatting/issues/811)
 * `fsdocs convert` now accepts the input file as a positional argument (e.g. `fsdocs convert notebook.ipynb -o notebook.html`). [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 * `fsdocs convert` infers the output format from the output file extension when `--outputformat` is not specified (e.g. `-o out.md` implies `--outputformat markdown`). [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 * `fsdocs convert` now accepts `-o` as a shorthand for `--output`. [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
 
 ### Changed
+* Changed `range` fields in `MarkdownSpan` and `MarkdownParagraph` DU cases from `MarkdownRange option` to `MarkdownRange`, using `MarkdownRange.zero` as the default/placeholder value instead of `None`.
 * When no template is provided (e.g. `fsdocs convert` without `--template`), `fsdocs-tip` tooltip divs are no longer included in the output. Tooltips require JavaScript/CSS from a template to function, so omitting them produces cleaner raw output. [#1019](https://github.com/fsprojects/FSharp.Formatting/pull/1019)
+
 ## 22.0.0-alpha.1 - 2026-03-03
 
 ### Added

docs/evaluation.fsx

@@ -200,9 +200,10 @@ fsiEvaluator.RegisterTransformation(fun (o, ty, _executionCount) ->
        && ty.GetGenericTypeDefinition() = typedefof<list<_>> then
         let items =
             // Get items as objects and create a paragraph for each item
-            [ for it in Seq.cast<obj> (unbox o) -> [ Paragraph([ Literal(it.ToString(), None) ], None) ] ]
+            [ for it in Seq.cast<obj> (unbox o) ->
+                  [ Paragraph([ Literal(it.ToString(), MarkdownRange.zero) ], MarkdownRange.zero) ] ]
         // Return option value (success) with ordered list
-        Some [ ListBlock(MarkdownListKind.Ordered, items, None) ]
+        Some [ ListBlock(MarkdownListKind.Ordered, items, MarkdownRange.zero) ]
     else
         None)
 (**

src/FSharp.Formatting.Literate/Formatting.fs

@@ -80,14 +80,15 @@ module internal Formatting =
     /// entire source code of the specified document (with possible fsx formatting)
     let getSourceDocument (doc: LiterateDocument) =
         match doc.Source with
-        | LiterateSource.Markdown text -> doc.With(paragraphs = [ CodeBlock(text, None, None, "", "", None) ])
+        | LiterateSource.Markdown text ->
+            doc.With(paragraphs = [ CodeBlock(text, None, None, "", "", MarkdownRange.zero) ])
         | LiterateSource.Script snippets ->
             let mutable count = 0
 
             let paragraphs =
                 [ for Snippet(name, lines) in snippets do
                       if snippets.Length > 1 then
-                          yield Heading(3, [ Literal(name, None) ], None)
+                          yield Heading(3, [ Literal(name, MarkdownRange.zero) ], MarkdownRange.zero)
 
                       let id =
                           count <- count + 1
@@ -100,7 +101,7 @@ module internal Formatting =
                             Visibility = LiterateCodeVisibility.VisibleCode }
 
                       let popts = { Condition = None }
-                      yield EmbedParagraphs(LiterateCode(lines, opts, popts), None) ]
+                      yield EmbedParagraphs(LiterateCode(lines, opts, popts), MarkdownRange.zero) ]
 
             doc.With(paragraphs = paragraphs)
 

src/FSharp.Formatting.Literate/Literate.fs

@@ -286,7 +286,11 @@ type Literate private () =
         let doc = Transformations.replaceLiterateParagraphs ctx doc
 
         let doc =
-            MarkdownDocument(doc.Paragraphs @ [ InlineHtmlBlock(doc.FormattedTips, None, None) ], doc.DefinedLinks)
+            MarkdownDocument(
+                doc.Paragraphs
+                @ [ InlineHtmlBlock(doc.FormattedTips, None, MarkdownRange.zero) ],
+                doc.DefinedLinks
+            )
 
         let sb = System.Text.StringBuilder()
         use wr = new StringWriter(sb)
@@ -334,7 +338,10 @@ type Literate private () =
 
         let doc = Transformations.replaceLiterateParagraphs ctx doc
 
-        let paragraphs = doc.Paragraphs @ [ InlineHtmlBlock(doc.FormattedTips, None, None) ], doc.DefinedLinks
+        let paragraphs =
+            doc.Paragraphs
+            @ [ InlineHtmlBlock(doc.FormattedTips, None, MarkdownRange.zero) ],
+            doc.DefinedLinks
 
         let doc = MarkdownDocument(paragraphs)
 

src/FSharp.Formatting.Literate/ParseScript.fs

@@ -183,103 +183,103 @@ type internal ParseScript(parseOptions, ctx: CompilerContext) =
         | BlockCommand((Command "include" ref) as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(CodeReference(ref, popts), None)
+            let p = EmbedParagraphs(CodeReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false None count noEval (p :: acc) defs blocks
 
         // Include console output (stdout) of previous block
         | BlockCommand(Command "include-output" EmptyString as cmds) :: blocks, Some prevCodeId ->
             let popts = getParaOptions cmds
 
-            let p1 = EmbedParagraphs(OutputReference(prevCodeId, popts), None)
+            let p1 = EmbedParagraphs(OutputReference(prevCodeId, popts), MarkdownRange.zero)
 
             transformBlocks false (Some prevCodeId) count noEval (p1 :: acc) defs blocks
 
         // Include console output (stdout) of a named block
         | BlockCommand(Command "include-output" ref as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(OutputReference(ref, popts), None)
+            let p = EmbedParagraphs(OutputReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false prevCodeId count noEval (p :: acc) defs blocks
 
         // Include FSI output (stdout) of previous block
         | BlockCommand(Command "include-fsi-output" EmptyString as cmds) :: blocks, Some prevCodeId ->
             let popts = getParaOptions cmds
 
-            let p1 = EmbedParagraphs(FsiOutputReference(prevCodeId, popts), None)
+            let p1 = EmbedParagraphs(FsiOutputReference(prevCodeId, popts), MarkdownRange.zero)
 
             transformBlocks false (Some prevCodeId) count noEval (p1 :: acc) defs blocks
 
         // Include FSI output (stdout) of a named block
         | BlockCommand(Command "include-fsi-output" ref as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(FsiOutputReference(ref, popts), None)
+            let p = EmbedParagraphs(FsiOutputReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false prevCodeId count noEval (p :: acc) defs blocks
 
         // Include the merge of the console and FSI output (stdout) of previous block
         | BlockCommand(Command "include-fsi-merged-output" EmptyString as cmds) :: blocks, Some prevCodeId ->
             let popts = getParaOptions cmds
 
-            let p1 = EmbedParagraphs(FsiMergedOutputReference(prevCodeId, popts), None)
+            let p1 = EmbedParagraphs(FsiMergedOutputReference(prevCodeId, popts), MarkdownRange.zero)
 
             transformBlocks false (Some prevCodeId) count noEval (p1 :: acc) defs blocks
 
         // Include the merge of the console and FSI output (stdout) of a named block
         | BlockCommand(Command "include-fsi-merged-output" ref as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(FsiMergedOutputReference(ref, popts), None)
+            let p = EmbedParagraphs(FsiMergedOutputReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false prevCodeId count noEval (p :: acc) defs blocks
 
         // Include formatted 'it' of previous block
         | BlockCommand((Command "include-it" EmptyString) as cmds) :: blocks, Some prevCodeId ->
             let popts = getParaOptions cmds
 
-            let p1 = EmbedParagraphs(ItValueReference(prevCodeId, popts), None)
+            let p1 = EmbedParagraphs(ItValueReference(prevCodeId, popts), MarkdownRange.zero)
 
             transformBlocks false (Some prevCodeId) count noEval (p1 :: acc) defs blocks
 
         // Include formatted 'it' of a named block
         | BlockCommand(Command "include-it" ref as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(ItValueReference(ref, popts), None)
+            let p = EmbedParagraphs(ItValueReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false None count noEval (p :: acc) defs blocks
 
         // Include unformatted 'it' of previous block
         | BlockCommand((Command "include-it-raw" EmptyString) as cmds) :: blocks, Some prevCodeId ->
             let popts = getParaOptions cmds
 
-            let p1 = EmbedParagraphs(ItRawReference(prevCodeId, popts), None)
+            let p1 = EmbedParagraphs(ItRawReference(prevCodeId, popts), MarkdownRange.zero)
 
             transformBlocks false (Some prevCodeId) count noEval (p1 :: acc) defs blocks
 
         // Include unformatted 'it' of a named block
         | BlockCommand(Command "include-it-raw" ref as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(ItRawReference(ref, popts), None)
+            let p = EmbedParagraphs(ItRawReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false None count noEval (p :: acc) defs blocks
 
         // Include formatted named value
         | BlockCommand(Command "include-value" ref as cmds) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(ValueReference(ref, popts), None)
+            let p = EmbedParagraphs(ValueReference(ref, popts), MarkdownRange.zero)
 
             transformBlocks false None count noEval (p :: acc) defs blocks
 
         // Include code without evaluation
         | BlockCommand(Command "raw" _ as cmds) :: BlockSnippet(snip) :: blocks, _ ->
             let popts = getParaOptions cmds
 
-            let p = EmbedParagraphs(RawBlock(snip, popts), None)
+            let p = EmbedParagraphs(RawBlock(snip, popts), MarkdownRange.zero)
 
             transformBlocks false None count noEval (p :: acc) defs blocks
 
@@ -304,7 +304,7 @@ type internal ParseScript(parseOptions, ctx: CompilerContext) =
 
             let popts = getParaOptions cmds
 
-            let code = EmbedParagraphs(LiterateCode(snip, opts, popts), None)
+            let code = EmbedParagraphs(LiterateCode(snip, opts, popts), MarkdownRange.zero)
 
             transformBlocks false (Some outputName) count noEval (code :: acc) defs blocks
 
@@ -329,7 +329,7 @@ type internal ParseScript(parseOptions, ctx: CompilerContext) =
 
             let popts = { Condition = None }
 
-            let p = EmbedParagraphs(LiterateCode(snip, opts, popts), None)
+            let p = EmbedParagraphs(LiterateCode(snip, opts, popts), MarkdownRange.zero)
 
             transformBlocks false (Some id) count noEval (p :: acc) defs blocks
 

src/FSharp.Formatting.Literate/Transformations.fs

@@ -264,25 +264,35 @@ module internal Transformations =
 
                       yield
                           [ Span(
-                                [ Literal(sprintf "[%d] " i, None)
-                                  DirectLink([ Literal(name.Trim(), None) ], link, Some title, None)
-                                  Literal(" - " + auth, None) ],
-                                None
+                                [ Literal(sprintf "[%d] " i, MarkdownRange.zero)
+                                  DirectLink(
+                                      [ Literal(name.Trim(), MarkdownRange.zero) ],
+                                      link,
+                                      Some title,
+                                      MarkdownRange.zero
+                                  )
+                                  Literal(" - " + auth, MarkdownRange.zero) ],
+                                MarkdownRange.zero
                             ) ]
                   else
                       yield
                           [ Span(
-                                [ Literal(sprintf "[%d] " i, None)
-                                  DirectLink([ Literal(title, None) ], link, Some title, None) ],
-                                None
+                                [ Literal(sprintf "[%d] " i, MarkdownRange.zero)
+                                  DirectLink(
+                                      [ Literal(title, MarkdownRange.zero) ],
+                                      link,
+                                      Some title,
+                                      MarkdownRange.zero
+                                  ) ],
+                                MarkdownRange.zero
                             ) ] ]
 
         // Return the document together with dictionary for looking up indices
         let id = DateTime.Now.ToString("yyMMddhh")
 
-        [ Paragraph([ AnchorLink(id, None) ], None)
-          Heading(3, [ Literal("References", None) ], None)
-          ListBlock(MarkdownListKind.Unordered, refList, None) ],
+        [ Paragraph([ AnchorLink(id, MarkdownRange.zero) ], MarkdownRange.zero)
+          Heading(3, [ Literal("References", MarkdownRange.zero) ], MarkdownRange.zero)
+          ListBlock(MarkdownListKind.Unordered, refList, MarkdownRange.zero) ],
         refLookup
 
     /// Turn all indirect links into a references
@@ -417,8 +427,8 @@ module internal Transformations =
                     { opts with
                         ExecutionCount = Some executionCount }
 
-                [ EmbedParagraphs(LiterateCode(lines, opts, popts), None) ]
-            | _ -> [ EmbedParagraphs(special, None) ]
+                [ EmbedParagraphs(LiterateCode(lines, opts, popts), MarkdownRange.zero) ]
+            | _ -> [ EmbedParagraphs(special, MarkdownRange.zero) ]
 
         // Traverse all other structrues recursively
         | MarkdownPatterns.ParagraphNested(pn, nested) ->
@@ -517,7 +527,7 @@ module internal Transformations =
                     | LiterateCode(_, { Visibility = LiterateCodeVisibility.NamedCode _ }, _) -> None
                     | _ ->
                         match special with
-                        | RawBlock(lines, _) -> Some(InlineHtmlBlock(unparse lines, None, None))
+                        | RawBlock(lines, _) -> Some(InlineHtmlBlock(unparse lines, None, MarkdownRange.zero))
                         | LiterateCode(lines, _, _) -> Some(formatted.[Choice1Of2 lines])
                         | CodeReference(ref, _) ->
                             match formatted.TryGetValue(Choice2Of2 ref) with
@@ -536,7 +546,7 @@ module internal Transformations =
                             let msg = "Warning: Output, it-value and value references require --eval"
 
                             printfn "%s" msg
-                            Some(InlineHtmlBlock(msg, None, None))
+                            Some(InlineHtmlBlock(msg, None, MarkdownRange.zero))
                         | LanguageTaggedCode(lang, code, _) ->
                             let inlined =
                                 match ctx.OutputKind with
@@ -546,7 +556,7 @@ module internal Transformations =
                                 | OutputKind.Fsx -> code
                                 | OutputKind.Markdown -> code
 
-                            Some(InlineHtmlBlock(inlined, None, None))
+                            Some(InlineHtmlBlock(inlined, None, MarkdownRange.zero))
         // Traverse all other structures recursively
         | MarkdownPatterns.ParagraphNested(pn, nested) ->
             let nested = List.map (List.choose (replaceLiterateParagraph ctx formatted)) nested
@@ -602,7 +612,7 @@ module internal Transformations =
             [ for (key, (_, executionCount)), fmtd in Seq.zip codes formatted.Snippets ->
                   let block =
                       match ctx.OutputKind with
-                      | OutputKind.Html -> InlineHtmlBlock(fmtd.Content, executionCount, None)
+                      | OutputKind.Html -> InlineHtmlBlock(fmtd.Content, executionCount, MarkdownRange.zero)
                       | OutputKind.Fsx
                       | OutputKind.Markdown
                       | OutputKind.Latex
@@ -613,7 +623,7 @@ module internal Transformations =
                               fence = Some "```",
                               language = "fsharp",
                               ignoredLine = "",
-                              range = None
+                              range = MarkdownRange.zero
                           )
 
                   key, block ]

src/FSharp.Formatting.Markdown/Markdown.fs

@@ -70,7 +70,7 @@ type Markdown internal () =
             { Newline = newline
               IsFirst = true
               Links = links
-              CurrentRange = Some(MarkdownRange.zero)
+              CurrentRange = MarkdownRange.zero
               ParseOptions = parseOptions }
 
         let paragraphs =

src/FSharp.Formatting.Markdown/MarkdownBlockParser.fs

@@ -742,8 +742,8 @@ let (|LinkDefinition|_|) s =
 
 let updateCurrentRange lines =
     match lines with
-    | [] -> None
-    | (_, l) :: _ -> Some(l)
+    | [] -> MarkdownRange.zero
+    | (_, l) :: _ -> l
 
 /// Parse a list of lines into a sequence of markdown paragraphs
 let rec parseParagraphs (ctx: ParsingContext) (lines: (string * MarkdownRange) list) =
@@ -755,7 +755,7 @@ let rec parseParagraphs (ctx: ParsingContext) (lines: (string * MarkdownRange) l
         let frontMatter, (Lines.TrimBlankStart(_, moreLines)) =
             if ctx.IsFirst && ctx.AllowYamlFrontMatter then
                 match lines with
-                | YamlFrontmatter(yaml, loc, rest) -> Some(YamlFrontmatter(yaml, Some loc)), rest
+                | YamlFrontmatter(yaml, loc, rest) -> Some(YamlFrontmatter(yaml, loc)), rest
                 | _ -> None, lines
             else
                 None, lines