Merge branch 'main' into repo-assist/fix-tomd-yaml-frontmatter-2026-04-13-bca272bf909c4735

Author: dsyme

RELEASE_NOTES.md

@@ -4,6 +4,8 @@
 
 ### Fixed
 * Fix `Markdown.ToMd` silently dropping YAML frontmatter when serialising a parsed `MarkdownDocument` back to Markdown text. Frontmatter is now preserved with its `---` delimiters.
+* Fix `Markdown.ToMd` dropping link titles in `DirectLink` and `DirectImage` spans. Links with a title attribute (e.g. `[text](url "title")`) now round-trip correctly; without this fix the title was silently discarded on serialisation.
+* Fix `Markdown.ToMd` serialising inline code spans that contain backtick characters. Previously, `InlineCode` was always wrapped in single backticks, producing syntactically incorrect Markdown when the code body contained backticks. Now the serialiser selects the shortest backtick fence that does not collide with the body content (e.g. a double-backtick fence for bodies containing single backticks, triple for double, etc.), matching the CommonMark spec.
 
 ## [22.0.0] - 2026-04-03
 
@@ -22,6 +24,8 @@
 ## [22.0.0-alpha.2] - 2026-03-13
 
 ### Added
+* Add `--root` option to `fsdocs watch` to override the root URL for generated pages. Useful for serving docs via GitHub Codespaces, reverse proxies, or other remote hosting where `localhost` URLs are inaccessible. E.g. `fsdocs watch --root /` or `fsdocs watch --root https://example.com/docs/`. When not set, defaults to `http://localhost:<port>/` as before. [#924](https://github.com/fsprojects/FSharp.Formatting/issues/924)
+* Fix `fsdocs watch` hot-reload WebSocket to connect using the page's actual host (`window.location.host`) instead of a hardcoded `localhost:<port>`, so hot-reload works correctly in GitHub Codespaces, behind reverse proxies, and over HTTPS. [#924](https://github.com/fsprojects/FSharp.Formatting/issues/924)
 * Search dialog now auto-focuses the search input when opened, clears on close, and can be triggered with `Ctrl+K` / `Cmd+K` in addition to `/`.
 * 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)

src/FSharp.Formatting.Markdown/MarkdownUtils.fs

@@ -106,15 +106,50 @@ module internal MarkdownUtils =
         | HardLineBreak(_) -> "\n"
 
         | AnchorLink _ -> ""
+        | DirectLink(body, link, title, _) ->
+            let t =
+                title
+                |> Option.map (fun t -> sprintf " \"%s\"" (t.Replace("\"", "\\\"")))
+                |> Option.defaultValue ""
+
+            "[" + formatSpans ctx body + "](" + link + t + ")"
+
         | IndirectLink(body, _, LookupKey ctx.Links (link, _), _)
-        | DirectLink(body, link, _, _)
         | IndirectLink(body, link, _, _) -> "[" + formatSpans ctx body + "](" + link + ")"
 
         | IndirectImage(body, _, LookupKey ctx.Links (link, _), _) -> sprintf "![%s](%s)" body link
         | IndirectImage(body, _, key, _) -> sprintf "![%s][%s]" body key
-        | DirectImage(body, link, _, _) -> sprintf "![%s](%s)" body link
+
+        | DirectImage(body, link, title, _) ->
+            let t =
+                title
+                |> Option.map (fun t -> sprintf " \"%s\"" (t.Replace("\"", "\\\"")))
+                |> Option.defaultValue ""
+
+            sprintf "![%s](%s)" body (link + t)
         | Strong(body, _) -> "**" + formatSpans ctx body + "**"
-        | InlineCode(body, _) -> "`" + body + "`"
+        | InlineCode(body, _) ->
+            // Pick the shortest backtick fence that does not appear in the body.
+            // E.g. body "``h``" needs a triple-backtick fence; body "a`b" needs double.
+            let maxConsecutiveBackticks =
+                body
+                |> Seq.fold
+                    (fun (maxR, run) c ->
+                        if c = '`' then
+                            let run' = run + 1
+                            (max maxR run'), run'
+                        else
+                            maxR, 0)
+                    (0, 0)
+                |> fst
+
+            let fence = String.replicate (maxConsecutiveBackticks + 1) "`"
+            // Surround with spaces when the body starts or ends with a backtick so the
+            // fence and content do not merge (e.g. `` ``h`` `` would look like 4-backtick).
+            if body.Length > 0 && (body.[0] = '`' || body.[body.Length - 1] = '`') then
+                fence + " " + body + " " + fence
+            else
+                fence + body + fence
         | Emphasis(body, _) -> "*" + formatSpans ctx body + "*"
 
     /// Format a list of MarkdownSpan

src/fsdocs-tool/BuildCommand.fs

@@ -827,11 +827,10 @@ module Serve =
     let refreshEvent = FSharp.Control.Event<string>()
 
     /// generate the script to inject into html to enable hot reload during development
-    let generateWatchScript (port: int) =
-        let tag =
-            """
+    let generateWatchScript () =
+        """
 <script type="text/javascript">
-    var wsUri = "ws://localhost:{{PORT}}/websocket";
+    var wsUri = "ws://" + window.location.host + "/websocket";
     function init()
     {
         websocket = new WebSocket(wsUri);
@@ -858,8 +857,6 @@ module Serve =
 </script>
 """
 
-        tag.Replace("{{PORT}}", string<int> port)
-
     let connectedClients = ConcurrentDictionary<WebSocket, unit>()
 
     let socketHandler (webSocket: WebSocket) (context: HttpContext) =
@@ -1568,9 +1565,15 @@ type CoreBuildOptions(watch) =
         // Adjust the user substitutions for 'watch' mode root
         let userRoot, userParameters =
             if watch then
-                let userRoot = sprintf "http://localhost:%d/" this.port_option
-
-                if userParametersDict.ContainsKey(ParamKeys.root) then
+                let userRoot =
+                    match this.root_override_option with
+                    | Some r -> r
+                    | None -> sprintf "http://localhost:%d/" this.port_option
+
+                if
+                    userParametersDict.ContainsKey(ParamKeys.root)
+                    && this.root_override_option.IsNone
+                then
                     printfn "ignoring user-specified root since in watch mode, root = %s" userRoot
 
                 let userParameters =
@@ -1881,7 +1884,7 @@ type CoreBuildOptions(watch) =
         let getLatestWatchScript () =
             if watch then
                 // if running in watch mode, inject hot reload script
-                [ ParamKeys.``fsdocs-watch-script``, Serve.generateWatchScript this.port_option ]
+                [ ParamKeys.``fsdocs-watch-script``, Serve.generateWatchScript () ]
             else
                 // otherwise, inject empty replacement string
                 [ ParamKeys.``fsdocs-watch-script``, "" ]
@@ -2330,6 +2333,9 @@ type CoreBuildOptions(watch) =
     abstract port_option: int
     default x.port_option = 0
 
+    abstract root_override_option: string option
+    default x.root_override_option = None
+
 /// Helpers for the <c>fsdocs convert</c> command.
 module private ConvertHelpers =
 
@@ -2746,3 +2752,12 @@ type WatchCommand() =
 
     [<Option("port", Required = false, Default = 8901, HelpText = "Port to serve content for http://localhost serving.")>]
     member val port = 8901 with get, set
+
+    override x.root_override_option = if x.root = "" then None else Some x.root
+
+    [<Option("root",
+             Required = false,
+             Default = "",
+             HelpText =
+                 "Override the root URL for generated pages. Useful for reverse proxies or GitHub Codespaces. E.g. --root / or --root https://example.com/docs/. When not set, defaults to http://localhost:<port>/.")>]
+    member val root = "" with get, set

tests/FSharp.Markdown.Tests/Markdown.fs

@@ -1239,16 +1239,62 @@ let ``ToMd preserves strong (bold) text`` () =
 let ``ToMd preserves inline code`` () =
     "Use `printf` here." |> toMd |> should contain "`printf`"
 
+[<Test>]
+let ``ToMd round-trips inline code containing a single backtick`` () =
+    // "a`b" must be serialised with a double-backtick fence so it re-parses correctly.
+    let original = "`` a`b ``"
+    let md = Markdown.Parse original
+    let result = Markdown.ToMd md
+    // The serialised form must round-trip: re-parsing must yield the same InlineCode body.
+    let reparsed = Markdown.Parse result
+
+    match reparsed.Paragraphs with
+    | [ Paragraph([ InlineCode("a`b", _) ], _) ] -> ()
+    | _ -> Assert.Fail(sprintf "Expected InlineCode(\"a`b\") after round-trip, got: %A" reparsed.Paragraphs)
+
+[<Test>]
+let ``ToMd round-trips inline code containing multiple backticks`` () =
+    // Body "``h``" contains double backticks — needs a triple-backtick fence.
+    let original = "` ``h`` `"
+    let md = Markdown.Parse original
+    let result = Markdown.ToMd md
+
+    match (Markdown.Parse result).Paragraphs with
+    | [ Paragraph([ InlineCode("``h``", _) ], _) ] -> ()
+    | _ -> Assert.Fail(sprintf "Expected InlineCode(\"``h``\") after round-trip, got: %A" result)
+
 [<Test>]
 let ``ToMd preserves a direct link`` () =
     "[FSharp](https://fsharp.org)"
     |> toMd
     |> should contain "[FSharp](https://fsharp.org)"
 
+[<Test>]
+let ``ToMd preserves a direct link with title`` () =
+    let md = "[FSharp](https://fsharp.org \"F# language\")"
+    let result = toMd md
+    result |> should contain "[FSharp]("
+    result |> should contain "https://fsharp.org"
+    result |> should contain "\"F# language\""
+
+[<Test>]
+let ``ToMd preserves a direct link without title unchanged`` () =
+    let result = "[link](http://example.com)" |> toMd
+    result |> should contain "[link](http://example.com)"
+    result |> should not' (contain "\"")
+
 [<Test>]
 let ``ToMd preserves a direct image`` () =
     "![alt text](image.png)" |> toMd |> should contain "![alt text](image.png)"
 
+[<Test>]
+let ``ToMd preserves a direct image with title`` () =
+    let md = "![photo](image.png \"My Photo\")"
+    let result = toMd md
+    result |> should contain "![photo]("
+    result |> should contain "image.png"
+    result |> should contain "\"My Photo\""
+
 [<Test>]
 let ``ToMd preserves an unordered list`` () =
     let md = "* apple\n* banana\n* cherry"