From 0a608d88ae02bfddca2d53ce26fc385621f3e985 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 10 Apr 2026 11:01:10 +0000 Subject: [PATCH 1/4] css: introduce --surface-background and --surface-border variables Decouple component surface colours from --header-background/--header-border. The new variables default to the header values for full backwards compatibility. Themes that need a distinct surface colour (e.g. dark header + light content surfaces) can now override --surface-background and --surface-border without touching the header variables. Affected components: - .copy-code-button (background + border) - --mobile-menu-background - --aside-background (sidebar) - --blockquote-bacground-color - --page-menu-background-color + border - --nav-item-border-color - --dialog-background-color - div.fsdocs-tip (border) - API docs table row borders - dialog list item borders - #fsdocs-main-menu sidebar border Closes #1156 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- RELEASE_NOTES.md | 3 +++ docs/content/fsdocs-default.css | 31 +++++++++++++++++-------------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 33214cbc4..5025fd82d 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,6 +2,9 @@ ## [Unreleased] +### Added +* Introduce `--surface-background` and `--surface-border` CSS custom properties in `fsdocs-default.css`. These decouple component surface colours (copy-code button, blockquotes, sidebar, page menu, dialogs, tooltips, API tables) from `--header-background`/`--header-border`. Both variables default to the header values, so existing themes are unaffected; themes that need a different colour for content surfaces can now override `--surface-background` and `--surface-border` independently. [#1156](https://github.com/fsprojects/FSharp.Formatting/issues/1156) + ## [22.0.0] - 2026-04-03 ### Fixed diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 5e2c1261e..8bcbd12e7 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -63,7 +63,10 @@ --header-background: light-dark(#f9fbfc, #0c1318); --header-border: light-dark(#e8ecf1, #3a3a42); --header-link-color: var(--text-color); - --mobile-menu-background: var(--header-background); + /* Surface variables — override these independently from the header */ + --surface-background: var(--header-background); + --surface-border: var(--header-border); + --mobile-menu-background: var(--surface-background); --menu-color: var(--text-color); --menu-item-hover-background: light-dark(#eff0f1, #2c2624); --menu-item-hover-color: var(--menu-color); @@ -77,16 +80,16 @@ --scrollbar-thumb-background: #686868; --shadow-color: hsla(0, 0%, 0%, .1); --main-shadow-color: hsla(0, 0%, 0%, .025); - --aside-background: var(--header-background); - --blockquote-bacground-color: var(--header-background); + --aside-background: var(--surface-background); + --blockquote-bacground-color: var(--surface-background); --blockquote-color: var(--text-color); --on-this-page-color: var(--menu-color); - --page-menu-background-color: var(--header-background); - --page-menu-background-border-color: var(--header-border); + --page-menu-background-color: var(--surface-background); + --page-menu-background-border-color: var(--surface-border); --page-menu-background-hover-border-color: var(--text-color); - --nav-item-border-color: var(--header-border); + --nav-item-border-color: var(--surface-border); --nav-item-active-border-color: var(--text-color); - --dialog-background-color: var(--header-background); + --dialog-background-color: var(--surface-background); --dialog-empty-color: var(--nav-category); --dialog-icon-color: var(--text-color); --dialog-link-color: var(--link-color); @@ -347,7 +350,7 @@ main { margin: 0; & li { - border-left: 1px solid var(--header-border); + border-left: 1px solid var(--surface-border); margin: 0; &:hover, &:focus { @@ -468,7 +471,7 @@ main { padding: var(--spacing-300) var(--spacing-500); background-color: var(--aside-background); width: var(--main-menu-width); - border-right: 1px solid var(--header-border); + border-right: 1px solid var(--surface-border); grid-row: var(--main-menu-grid-row); grid-column: var(--main-menu-grid-column); overflow-y: auto; @@ -731,8 +734,8 @@ pre.has-copy-button { top: var(--spacing-100); right: var(--spacing-100); padding: var(--spacing-50) var(--spacing-100); - background-color: var(--header-background); - border: 1px solid var(--header-border); + background-color: var(--surface-background); + border: 1px solid var(--surface-border); border-radius: var(--radius); color: var(--text-color); cursor: pointer; @@ -989,7 +992,7 @@ table.pre, code, pre.fssnip { div.fsdocs-tip { background-color: var(--doc-tip-background); border-radius: var(--radius); - border: 1px solid var(--header-border); + border: 1px solid var(--surface-border); padding: var(--spacing-200); font-family: var(--monospace-font); font-variant-ligatures: none; @@ -1070,7 +1073,7 @@ div.fsdocs-tip:popover-open { } & tbody td { - border-top: 1px solid var(--header-border); + border-top: 1px solid var(--surface-border); padding: var(--spacing-300) 0; } @@ -1280,7 +1283,7 @@ dialog { & li { margin: 0; - border-bottom: 1px solid var(--header-border); + border-bottom: 1px solid var(--surface-border); &:hover { & a, & a iconify-icon { From ad4ea184a339af5b65cab309614d3f951469c6d8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 10 Apr 2026 11:01:13 +0000 Subject: [PATCH 2/4] ci: trigger checks From e5ed887dcaa1edfbfaf1c96e7093b7c159dba66f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 21 Apr 2026 10:57:31 +0000 Subject: [PATCH 3/4] css: rename --surface-* to --panel-* for clarity The 'surface' naming was found to be non-intuitive by maintainers. Rename to --panel-background and --panel-border which more clearly communicates that these variables control backgrounds and borders of panel/component UI elements (menus, dialogs, blockquotes, etc.) as distinct from the page header colours. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- RELEASE_NOTES.md | 2 +- docs/content/fsdocs-default.css | 34 ++++++++++++++++----------------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index a4e5d29c3..8fb65a549 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -19,7 +19,7 @@ * Fix `Markdown.ToLatex` producing invalid LaTeX output for level-6 (and deeper) headings. Previously the LaTeX command was an empty string, resulting in bare `{content}` without a command prefix. Headings at level 6+ are now serialised as `\subparagraph{...}`, which is the deepest sectioning command available in LaTeX. ### Added -* Introduce `--surface-background` and `--surface-border` CSS custom properties in `fsdocs-default.css`. These decouple component surface colours (copy-code button, blockquotes, sidebar, page menu, dialogs, tooltips, API tables) from `--header-background`/`--header-border`. Both variables default to the header values, so existing themes are unaffected; themes that need a different colour for content surfaces can now override `--surface-background` and `--surface-border` independently. [#1156](https://github.com/fsprojects/FSharp.Formatting/issues/1156) +* Introduce `--panel-background` and `--panel-border` CSS custom properties in `fsdocs-default.css`. These decouple panel/component colours (copy-code button, blockquotes, sidebar, page menu, dialogs, tooltips, API tables) from `--header-background`/`--header-border`. Both variables default to the header values, so existing themes are unaffected; themes that need a different colour for content panels can now override `--panel-background` and `--panel-border` independently. [#1156](https://github.com/fsprojects/FSharp.Formatting/issues/1156) * Add tests for `Markdown.ToFsx` (direct serialisation to F# script format), which previously had no unit test coverage. * Add tests for `Markdown.ToPynb` (direct serialisation to Jupyter notebook format), which previously had no unit test coverage. * Add round-trip tests for `HardLineBreak` and `HorizontalRule` character preservation in `Markdown.ToMd`. diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 8bcbd12e7..a69f1360e 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -63,10 +63,10 @@ --header-background: light-dark(#f9fbfc, #0c1318); --header-border: light-dark(#e8ecf1, #3a3a42); --header-link-color: var(--text-color); - /* Surface variables — override these independently from the header */ - --surface-background: var(--header-background); - --surface-border: var(--header-border); - --mobile-menu-background: var(--surface-background); + /* Panel variables — override these independently from the header to customise menus, dialogs, and blockquote backgrounds */ + --panel-background: var(--header-background); + --panel-border: var(--header-border); + --mobile-menu-background: var(--panel-background); --menu-color: var(--text-color); --menu-item-hover-background: light-dark(#eff0f1, #2c2624); --menu-item-hover-color: var(--menu-color); @@ -80,16 +80,16 @@ --scrollbar-thumb-background: #686868; --shadow-color: hsla(0, 0%, 0%, .1); --main-shadow-color: hsla(0, 0%, 0%, .025); - --aside-background: var(--surface-background); - --blockquote-bacground-color: var(--surface-background); + --aside-background: var(--panel-background); + --blockquote-bacground-color: var(--panel-background); --blockquote-color: var(--text-color); --on-this-page-color: var(--menu-color); - --page-menu-background-color: var(--surface-background); - --page-menu-background-border-color: var(--surface-border); + --page-menu-background-color: var(--panel-background); + --page-menu-background-border-color: var(--panel-border); --page-menu-background-hover-border-color: var(--text-color); - --nav-item-border-color: var(--surface-border); + --nav-item-border-color: var(--panel-border); --nav-item-active-border-color: var(--text-color); - --dialog-background-color: var(--surface-background); + --dialog-background-color: var(--panel-background); --dialog-empty-color: var(--nav-category); --dialog-icon-color: var(--text-color); --dialog-link-color: var(--link-color); @@ -350,7 +350,7 @@ main { margin: 0; & li { - border-left: 1px solid var(--surface-border); + border-left: 1px solid var(--panel-border); margin: 0; &:hover, &:focus { @@ -471,7 +471,7 @@ main { padding: var(--spacing-300) var(--spacing-500); background-color: var(--aside-background); width: var(--main-menu-width); - border-right: 1px solid var(--surface-border); + border-right: 1px solid var(--panel-border); grid-row: var(--main-menu-grid-row); grid-column: var(--main-menu-grid-column); overflow-y: auto; @@ -734,8 +734,8 @@ pre.has-copy-button { top: var(--spacing-100); right: var(--spacing-100); padding: var(--spacing-50) var(--spacing-100); - background-color: var(--surface-background); - border: 1px solid var(--surface-border); + background-color: var(--panel-background); + border: 1px solid var(--panel-border); border-radius: var(--radius); color: var(--text-color); cursor: pointer; @@ -992,7 +992,7 @@ table.pre, code, pre.fssnip { div.fsdocs-tip { background-color: var(--doc-tip-background); border-radius: var(--radius); - border: 1px solid var(--surface-border); + border: 1px solid var(--panel-border); padding: var(--spacing-200); font-family: var(--monospace-font); font-variant-ligatures: none; @@ -1073,7 +1073,7 @@ div.fsdocs-tip:popover-open { } & tbody td { - border-top: 1px solid var(--surface-border); + border-top: 1px solid var(--panel-border); padding: var(--spacing-300) 0; } @@ -1283,7 +1283,7 @@ dialog { & li { margin: 0; - border-bottom: 1px solid var(--surface-border); + border-bottom: 1px solid var(--panel-border); &:hover { & a, & a iconify-icon { From 14ed586dd4f0d0ca64c353697360cb62d084c300 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 22 Apr 2026 10:59:53 +0000 Subject: [PATCH 4/4] css: improve --panel-background/--panel-border comment for clarity Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/content/fsdocs-default.css | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index a69f1360e..2324cdc85 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -63,7 +63,8 @@ --header-background: light-dark(#f9fbfc, #0c1318); --header-border: light-dark(#e8ecf1, #3a3a42); --header-link-color: var(--text-color); - /* Panel variables — override these independently from the header to customise menus, dialogs, and blockquote backgrounds */ + /* Panel variables (--panel-background, --panel-border): override to customise menus, dialogs, + blockquotes, copy buttons, and other UI panels independently from the page header. */ --panel-background: var(--header-background); --panel-border: var(--header-border); --mobile-menu-background: var(--panel-background);