Merge branch 'main' into repo-assist/feature-811-fsdocs-convert-2cf2c2973fcbd211

Author: dsyme

.github/workflows/pull-requests.yml

@@ -8,6 +8,10 @@ on:
     branches:
     - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
   id-token: write
@@ -24,6 +28,13 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
+    - name: Cache .NET SDK
+      uses: actions/cache@v4
+      with:
+        path: ~/.dotnet
+        key: ${{ runner.os }}-dotnet-sdk-${{ hashFiles('global.json') }}
+        restore-keys: |
+          ${{ runner.os }}-dotnet-sdk-
     - name: Cache NuGet packages
       uses: actions/cache@v4
       with:

.github/workflows/push-main.yml

@@ -5,6 +5,13 @@ on:
     branches:
     - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+permissions:
+  id-token: write
+  contents: write
+
 jobs:
   build:
 
@@ -16,6 +23,13 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
+    - name: Cache .NET SDK
+      uses: actions/cache@v4
+      with:
+        path: ~/.dotnet
+        key: ${{ runner.os }}-dotnet-sdk-${{ hashFiles('global.json') }}
+        restore-keys: |
+          ${{ runner.os }}-dotnet-sdk-
     - name: Cache NuGet packages
       uses: actions/cache@v4
       with:
@@ -34,5 +48,11 @@ jobs:
         publish_dir: ./output
         publish_branch: gh-pages
         force_orphan: true
-    - name: Publish NuGets (if main version changed)
-      run: dotnet nuget push "artifacts/*.nupkg" -s https://api.nuget.org/v3/index.json -k ${{ secrets.FSHARP_FORMATTING_TOKEN_2020 }} --skip-duplicate
+    - name: Obtain NuGet key
+      # this hash is v1.1.0
+      uses: NuGet/login@d22cc5f58ff5b88bf9bd452535b4335137e24544
+      id: login
+      with:
+          user: dsyme
+    - name: Publish NuGets (if this version not published before)
+      run: dotnet nuget push "artifacts/*.nupkg" -s https://www.nuget.org/api/v2/package -k ${{ steps.login.outputs.NUGET_API_KEY }} --skip-duplicate

.github/workflows/repo-assist.lock.yml

@@ -71,7 +71,7 @@ tools:
   bash: true
   repo-memory: true
 
-source: githubnext/agentics/workflows/repo-assist.md@b87234850bf9664d198f28a02df0f937d0447295
+source: githubnext/agentics/workflows/repo-assist.md@f2c5cf1e4af58e09a93ba0703c6bf084711b265f
 ---
 
 # Repo Assist
@@ -115,6 +115,8 @@ Read memory at the **start** of every run; update it at the **end**.
 
 Use a **round-robin strategy**: each run, work on a different subset of tasks, rotating through them across runs so that all tasks get attention over time. Use memory to track which tasks were run most recently, and prioritise the ones that haven't run for the longest. Aim to do 2–4 tasks per run (plus the mandatory Task 11).
 
+**Repeat-run mode**: When invoked via `gh aw run repo-assist --repeat`, runs occur every 5–10 minutes. Even in this mode, **actively look for useful work to do** on every run. Do not skip a run just because the last one was recent or because open PRs are awaiting CI — there is always a task to advance: label issues, scan the backlog, study the codebase, prepare a fix, push an update, or work on Task 10. Treat a "nothing to do" conclusion as a sign you haven't looked hard enough, unless there really is, like, literally nothing to do. And be careful not to do duplicate work across runs — check memory to see if you've already tried a fix or commented on an issue before doing it again.
+
 Always do Task 11 (Update Monthly Activity Summary Issue) every run. In all comments and PR descriptions, identify yourself as "Repo Assist".
 
 ### Task 1: Triage and Comment on Open Issues

.github/workflows/repo-assist.md

@@ -11,13 +11,18 @@
 * Add `{{fsdocs-logo-alt}}` substitution (configurable via `<FsDocsLogoAlt>` MSBuild property, defaults to `Logo`) for accessible alt text on the header logo image. [#626](https://github.com/fsprojects/FSharp.Formatting/issues/626)
 
 ### Fixed
+* Fix `_menu_template.html` and `_menu-item_template.html` being copied to the output directory. [#803](https://github.com/fsprojects/FSharp.Formatting/issues/803)
+* Fix `ApiDocMember.Details.ReturnInfo.ReturnType` returning `None` for properties that have both a getter and a setter. [#734](https://github.com/fsprojects/FSharp.Formatting/issues/734)
 * Improve error message when a named code snippet is not found (e.g. `(*** include:name ***)` with undefined name now reports the missing name clearly). [#982](https://github.com/fsprojects/FSharp.Formatting/pull/982)
 * HTML-encode XML doc text nodes and unresolved `<see cref>` values to prevent HTML injection and fix broken output when docs contain characters like `<`, `>`, or backticks in generic type notation. [#748](https://github.com/fsprojects/FSharp.Formatting/issues/748)
 * Add uppercase output kind extension (e.g. `HTML`, `IPYNB`) to `ConditionalDefines` so that `#if HTML` and `(*** condition: HTML ***)` work alongside their lowercase variants. [#693](https://github.com/fsprojects/FSharp.Formatting/issues/693)
 * Strip `#if SYMBOL` / `#endif // SYMBOL` marker lines from `LiterateCode` source before syntax-highlighting so they do not appear in formatted output. [#693](https://github.com/fsprojects/FSharp.Formatting/issues/693)
+* Fix incorrect column ranges for inline spans (links, images, inline code) in the Markdown parser — spans and subsequent literals now report correct `StartColumn`/`EndColumn` values. [#744](https://github.com/fsprojects/FSharp.Formatting/issues/744)
+* Normalize `--projects` paths to absolute paths before passing to the project cracker, fixing failures when relative paths are supplied. [#793](https://github.com/fsprojects/FSharp.Formatting/issues/793)
 
 ### Changed
 * Update FCS to 43.10.100. [#935](https://github.com/fsprojects/FSharp.Formatting/pull/966)
+* Reduce dark mode header border contrast to match the visual subtlety of light mode borders. [#885](https://github.com/fsprojects/FSharp.Formatting/issues/885)
 
 ## 21.0.0 - 2025-11-12
 

RELEASE_NOTES.md

@@ -135,7 +135,7 @@
     --code-background: #28282D;
     --code-color: #f5f5f6;
     --header-background: #0c1318;
-    --header-border: #9b9b9b;
+    --header-border: #3a3a42;
     --menu-item-hover-background: #2c2624;
     --doc-tip-background: #2e293a;
     --link-color: #c5eff7;

docs/content/fsdocs-default.css

@@ -1538,6 +1538,7 @@ module internal SymbolReader =
         let argInfos, retType =
             match argInfos, v.HasGetterMethod, v.HasSetterMethod with
             | [ AllAndLast(args, last) ], _, true -> [ args ], Some last.Type
+            | [ [] ], _, true -> [], Some retType
             | _, _, true -> argInfos, None
             | [ [] ], true, _ -> [], Some retType
             | _, _, _ -> argInfos, Some retType

src/FSharp.Formatting.ApiDocs/GenerateModel.fs

@@ -324,6 +324,23 @@ type ParsingContext =
 
     member x.AllowYamlFrontMatter = (x.ParseOptions &&& MarkdownParseOptions.AllowYamlFrontMatter) <> enum 0
 
+/// Advances the StartColumn of the current range in ctx by n characters.
+let private advanceCtxBy n ctx =
+    { ctx with
+        CurrentRange =
+            match ctx.CurrentRange with
+            | Some r ->
+                Some
+                    { r with
+                        StartColumn = r.StartColumn + n }
+            | None -> None }
+
+/// Computes a span range starting at ctx.StartColumn and spanning n characters.
+let private spanRange n ctx =
+    match ctx.CurrentRange with
+    | Some r -> Some { r with EndColumn = r.StartColumn + n }
+    | None -> None
+
 /// Parses a body of a paragraph and recognizes all inline tags.
 let rec parseChars acc input (ctx: ParsingContext) =
     seq {
@@ -390,11 +407,11 @@ let rec parseChars acc input (ctx: ParsingContext) =
                     Some
                         { n with
                             StartColumn = n.StartColumn + s
-                            EndColumn = n.EndColumn - e }
+                            EndColumn = n.StartColumn + s + body.Length }
                 | None -> None
 
             yield InlineCode(String(Array.ofList body).Trim(), rng)
-            yield! parseChars [] rest ctx
+            yield! parseChars [] rest (advanceCtxBy (s + body.Length + e) ctx)
 
         // Display Latex inline math mode
         | DelimitedLatexDisplayMath [ '$'; '$' ] (body, rest) ->
@@ -442,60 +459,70 @@ let rec parseChars acc input (ctx: ParsingContext) =
             ->
             let (value, ctx) = accLiterals.Value
             yield! value
-            yield DirectLink([ Literal(link, ctx.CurrentRange) ], link, None, ctx.CurrentRange)
-            yield! parseChars [] rest ctx
+            let consumed = 1 + link.Length + 1
+            yield DirectLink([ Literal(link, spanRange consumed ctx) ], link, None, spanRange consumed ctx)
+            yield! parseChars [] rest (advanceCtxBy consumed ctx)
         // Not an inline link - leave as an inline HTML tag
         | List.DelimitedWith [ '<' ] [ '>' ] (tag, rest, _s, _e) ->
             yield! parseChars ('>' :: (List.rev tag) @ '<' :: acc) rest ctx
 
         // Recognize direct link [foo](http://bar) or indirect link [foo][bar] or auto link http://bar
-        | DirectLink(body, link, rest) ->
+        | DirectLink(body, linkChars, rest) ->
             let (value, ctx) = accLiterals.Value
             yield! value
 
-            let link, title = getLinkAndTitle (String(Array.ofList link), MarkdownRange.zero)
+            let consumed = 2 + body.Length + 2 + linkChars.Length
+            let link, title = getLinkAndTitle (String(Array.ofList linkChars), MarkdownRange.zero)
+            let bodyCtx = advanceCtxBy 1 ctx // advance past opening '['
 
-            yield DirectLink(parseChars [] body ctx |> List.ofSeq, link, title, ctx.CurrentRange)
-            yield! parseChars [] rest ctx
+            yield DirectLink(parseChars [] body bodyCtx |> List.ofSeq, link, title, spanRange consumed ctx)
+            yield! parseChars [] rest (advanceCtxBy consumed ctx)
         | IndirectLink(body, link, original, rest) ->
             let (value, ctx) = accLiterals.Value
             yield! value
 
+            let consumed = 2 + body.Length + original.Length
+            let bodyCtx = advanceCtxBy 1 ctx // advance past opening '['
+
             let key =
                 if String.IsNullOrEmpty(link) then
                     String(body |> Array.ofSeq)
                 else
                     link
 
-            yield IndirectLink(parseChars [] body ctx |> List.ofSeq, original, key, ctx.CurrentRange)
-            yield! parseChars [] rest ctx
+            yield IndirectLink(parseChars [] body bodyCtx |> List.ofSeq, original, key, spanRange consumed ctx)
+            yield! parseChars [] rest (advanceCtxBy consumed ctx)
         | AutoLink(link, rest) ->
             let (value, ctx) = accLiterals.Value
             yield! value
-            yield DirectLink([ Literal(link, ctx.CurrentRange) ], link, None, ctx.CurrentRange)
-            yield! parseChars [] rest ctx
+            let consumed = link.Length
+            yield DirectLink([ Literal(link, spanRange consumed ctx) ], link, None, spanRange consumed ctx)
+            yield! parseChars [] rest (advanceCtxBy consumed ctx)
 
         // Recognize image - this is a link prefixed with the '!' symbol
-        | '!' :: DirectLink(body, link, rest) ->
+        | '!' :: DirectLink(body, linkChars, rest) ->
             let (value, ctx) = accLiterals.Value
             yield! value
 
-            let link, title = getLinkAndTitle (String(Array.ofList link), MarkdownRange.zero)
+            let consumed = 1 + 2 + body.Length + 2 + linkChars.Length
+            let link, title = getLinkAndTitle (String(Array.ofList linkChars), MarkdownRange.zero)
 
-            yield DirectImage(String(Array.ofList body), link, title, ctx.CurrentRange)
-            yield! parseChars [] rest ctx
+            yield DirectImage(String(Array.ofList body), link, title, spanRange consumed ctx)
+            yield! parseChars [] rest (advanceCtxBy consumed ctx)
         | '!' :: IndirectLink(body, link, original, rest) ->
             let (value, ctx) = accLiterals.Value
             yield! value
 
+            let consumed = 1 + 2 + body.Length + original.Length
+
             let key =
                 if String.IsNullOrEmpty(link) then
                     String(body |> Array.ofSeq)
                 else
                     link
 
-            yield IndirectImage(String(Array.ofList body), original, key, ctx.CurrentRange)
-            yield! parseChars [] rest ctx
+            yield IndirectImage(String(Array.ofList body), original, key, spanRange consumed ctx)
+            yield! parseChars [] rest (advanceCtxBy consumed ctx)
 
         // Handle Emphasis
         | CannotOpenEmphasis(revPre, post) -> yield! parseChars (revPre @ acc) post ctx

src/FSharp.Formatting.Markdown/MarkdownParser.fs

@@ -141,6 +141,10 @@ type internal DocContent
           if
               not (inputFileName.StartsWith('.'))
               && not (inputFileName.StartsWith("_template", StringComparison.Ordinal))
+              && not (
+                  inputFileName.StartsWith("_menu", StringComparison.Ordinal)
+                  && inputFileName.EndsWith("_template.html", StringComparison.Ordinal)
+              )
           then
               let inputFileFullPath = Path.GetFullPath(inputFileFullPath)
 
@@ -186,7 +190,13 @@ type internal DocContent
 
           if name.StartsWith('.') then
               printfn "skipping file %s" inputFileFullPath
-          elif not (name.StartsWith("_template", StringComparison.Ordinal)) then
+          elif
+              not (name.StartsWith("_template", StringComparison.Ordinal))
+              && not (
+                  name.StartsWith("_menu", StringComparison.Ordinal)
+                  && name.EndsWith("_template.html", StringComparison.Ordinal)
+              )
+          then
               let isFsx = inputFileFullPath.EndsWith(".fsx", StringComparison.OrdinalIgnoreCase)
 
               let isMd = inputFileFullPath.EndsWith(".md", StringComparison.OrdinalIgnoreCase)