From 4b406e67b8a70419c2056217957a062cd7c56cc8 Mon Sep 17 00:00:00 2001 From: nojaf Date: Sun, 15 Oct 2023 17:35:23 +0200 Subject: [PATCH 01/71] Basic site structure. --- FSharp.Formatting.sln | 3 - docs/_template.html | 123 +-- docs/content/fsdocs-custom.css | 5 - docs/content/fsdocs-default.css | 1158 ++++++++++++++---------- docs/content/navbar-fixed-left.css | 77 -- docs/content/navbar-fixed-right.css | 78 -- docs/sidebyside/_template.html | 89 -- docs/sidebyside/sideextensions.md | 38 - docs/sidebyside/sidemarkdown.md | 70 -- docs/sidebyside/sidescript.fsx | 90 -- docs/templates/leftside/_template.html | 82 -- docs/templates/leftside/styling.md | 17 - src/fsdocs-tool/BuildCommand.fs | 2 +- 13 files changed, 718 insertions(+), 1114 deletions(-) delete mode 100644 docs/content/fsdocs-custom.css delete mode 100644 docs/content/navbar-fixed-left.css delete mode 100644 docs/content/navbar-fixed-right.css delete mode 100644 docs/sidebyside/_template.html delete mode 100644 docs/sidebyside/sideextensions.md delete mode 100644 docs/sidebyside/sidemarkdown.md delete mode 100644 docs/sidebyside/sidescript.fsx delete mode 100644 docs/templates/leftside/_template.html delete mode 100644 docs/templates/leftside/styling.md diff --git a/FSharp.Formatting.sln b/FSharp.Formatting.sln index 76b0b62a2..d7c141c06 100644 --- a/FSharp.Formatting.sln +++ b/FSharp.Formatting.sln @@ -121,12 +121,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "leftside", "leftside", "{18 EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{FAD5C374-4748-4A3D-A435-FFA425916F3A}" ProjectSection(SolutionItems) = preProject - docs\content\fsdocs-custom.css = docs\content\fsdocs-custom.css docs\content\fsdocs-default.css = docs\content\fsdocs-default.css docs\content\fsdocs-search.js = docs\content\fsdocs-search.js docs\content\fsdocs-tips.js = docs\content\fsdocs-tips.js - docs\content\navbar-fixed-left.css = docs\content\navbar-fixed-left.css - docs\content\navbar-fixed-right.css = docs\content\navbar-fixed-right.css EndProjectSection EndProject Global diff --git a/docs/_template.html b/docs/_template.html index 3baf0ece5..5c07708da 100644 --- a/docs/_template.html +++ b/docs/_template.html @@ -1,83 +1,58 @@  - - - {{fsdocs-page-title}} - + + + - - - - - - - - - - - - - - - - - + {{fsdocs-page-title}} | {{fsdocs-collection-name}} + + + + + + {{fsdocs-watch-script}} - - -
-
-

{{fsdocs-collection-name}}

-
-
-
- {{fsdocs-content}} - {{fsdocs-tooltips}} -
- - - - - - - - +
+ + Header menu logo + {{fsdocs-collection-name}} +
+ +
+ {{fsdocs-content}} + {{fsdocs-tooltips}} +
- - - + \ No newline at end of file diff --git a/docs/content/fsdocs-custom.css b/docs/content/fsdocs-custom.css deleted file mode 100644 index c32465db8..000000000 --- a/docs/content/fsdocs-custom.css +++ /dev/null @@ -1,5 +0,0 @@ - -/*-------------------------------------------------------------------------- - Customize your CSS here -/*--------------------------------------------------------------------------*/ - diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index bf73bfa5a..7c9f913c9 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -1,613 +1,791 @@ -@import url('https://fonts.googleapis.com/css2?family=Hind+Vadodara&family=Roboto+Mono:wght@400;500;600&display=swap'); -/*-------------------------------------------------------------------------- - Formatting for page & standard document content -/*--------------------------------------------------------------------------*/ - -body { - font-family: 'Hind Vadodara', sans-serif; - /* padding-top: 0px; - padding-bottom: 40px; -*/ +:root { + --monospace-font: "Fira Code", monospace; + --system-font: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif; + + --unit: 0.25rem; + --unit-2: calc(2 * var(--unit)); + --unit-3: calc(3 * var(--unit)); + --unit-4: calc(4 * var(--unit)); + --unit-5: calc(5 * var(--unit)); + --unit-6: calc(6 * var(--unit)); + --unit-7: calc(7 * var(--unit)); + --unit-8: calc(8 * var(--unit)); + --unit-9: calc(9 * var(--unit)); + --unit-10: calc(10 * var(--unit)); + --unit-11: calc(11 * var(--unit)); + --unit-12: calc(12 * var(--unit)); + --radius: 6px; + --icon-size: 30px; + + --container-sm: 768px; + --container-md: 960px; + --container-lg: 1024px; + --container-xl: 1200px; + --container-xxl: 1400px; + --aside-width: 200px; + + --header-height: 60px; + + /* light theme */ + --primary: #1e8bc3; + --background: #f5f5f6; + --text-color: #020202; + --text-hover: #282828; + --code-background: #ffffff; + --code-color: #1B6504; + --header-background: #f9fbfc; + --header-border: #e8ecf1; + --menu-icon-hover: #F7F7F7; + --menu-icon-hover-background: #bdc3c7; + --doc-tip-background: #F7F7F7; + --link-color: #4871f7; + --search-background: rgb(229, 231, 235); + --nav-category: rgb(156, 163, 175); + + --code-strings-color: #0093A1; + --code-printf-color: #6B2FBA; + --code-escaped-color: #EA8675; + --code-identifiers-color: #6B2FBA; + --code-module-color: #009999; + --code-reference-color: #4974D1; + --code-value-color: #1B6600; + --code-interface-color: #43AEC6; + --code-typearg-color: #43AEC6; + --code-disposable-color: #43AEC6; + --code-property-color: #43AEC6; + --code-punctuation-color: #43AEC6; + --code-punctuation2-color: var(--text-color); + --code-function-color: #6B2FBA; + --code-function2-color: #6B2FBA; + --code-activepattern-color: #4ec9b0; + --code-unioncase-color: #4ec9b0; + --code-enumeration-color: #8C6C41; + --code-keywords-color: #0F54D6; + --code-comment-color: #707070; + --code-operators-color: #0F54D6; + --code-numbers-color: #009999; + --code-linenumbers-color: #80b0b0; + --code-mutable-color: #1b6600; + --code-inactive-color: #808080; + --code-preprocessor-color: #af75c1; + --code-fsioutput-color: #808080; + --code-tooltip-color: #d1d1d1; +} + +/* CSS Reset, source: https://www.joshwcomeau.com/css/custom-css-reset/ */ +*, *::before, *::after { + box-sizing: border-box; } -blockquote { - margin: 0 1em 0 0.25em; - margin-top: 0px; - margin-right: 1em; - margin-bottom: 0px; - margin-left: 0.25em; - padding: 0 .75em 0 1em; - border-left: 1px solid #777; - border-right: 0px solid #777; +* { + margin: 0; } -/* Format the heading - nicer spacing etc. */ -.masthead { - overflow: hidden; +body { + line-height: 1.5; + -webkit-font-smoothing: antialiased; } - .masthead .muted a { - text-decoration: none; - color: #999999; - } - - .masthead ul, .masthead li { - margin-bottom: 0px; - } - - .masthead .nav li { - margin-top: 15px; - font-size: 110%; - } - - .masthead h3 { - margin-top: 15px; - margin-bottom: 5px; - font-size: 170%; - } - -/*-------------------------------------------------------------------------- - Formatting fsdocs-content -/*--------------------------------------------------------------------------*/ - -/* Change font sizes for headings etc. */ -#fsdocs-content h1 { - margin: 30px 0px 15px 0px; - /* font-weight: 400; */ - font-size: 2rem; - letter-spacing: 1.78px; - line-height: 2.5rem; - font-weight: 400; +img, picture, video, canvas, svg { + display: block; + max-width: 100%; } -#fsdocs-content h2 { - font-size: 1.6rem; - margin: 20px 0px 10px 0px; - font-weight: 400; +input, button, textarea, select { + font: inherit; } -#fsdocs-content h3 { - font-size: 1.2rem; - margin: 15px 0px 10px 0px; - font-weight: 400; +p, h1, h2, h3, h4, h5, h6 { + overflow-wrap: break-word; } -#fsdocs-content hr { - margin: 0px 0px 20px 0px; -} +/* Main layout */ +body { + font-family: var(--system-font); +} + +header { + background-color: var(--header-background); + padding: var(--unit-2); + height: var(--header-height); + display: flex; + align-items: center; + + & #menu-toggle { + position: relative; + height: var(--icon-size); + width: var(--icon-size); + border: 1px solid var(--header-border); + border-radius: var(--radius); + + & .icon { + top: 3px; + left: 3px; + width: calc(var(--icon-size) - 4px); + height: calc(var(--icon-size) - 4px); + position: absolute; + + &.open { + display: none; + } + } -#fsdocs-content li { - font-size: 1.0rem; - line-height: 1.375rem; - letter-spacing: 0.01px; - font-weight: 500; - margin: 0px 0px 15px 0px; -} + & input[type=checkbox] { + position: absolute; + width: 100%; + height: 100%; + left: 0; + top: 0; + appearance: none; + cursor: pointer; + } -#fsdocs-content p { - font-size: 1.0rem; - line-height: 1.375rem; - letter-spacing: 0.01px; - font-weight: 500; - color: #262626; -} + & .menu { + visibility: hidden; + height: 0; + opacity: 0; + width: 100%; + transition: all 0.2s ease-in-out; + position: fixed; + top: var(--header-height); + left: 0; + background-color: var(--header-background); + list-style: none; + padding: var(--unit-2); + } -#fsdocs-content a { - color: #4974D1; -} -/* remove the default bootstrap bold on dt elements */ -#fsdocs-content dt { - font-weight: normal; -} + & input:checked + .menu { + visibility: visible; + opacity: 1; + height: calc(100vh - var(--header-height)); + } + &:has(input:checked) { + .icon.open { + display: block; + } + .icon.closed { + display: none; + } + } + } -/*-------------------------------------------------------------------------- - Formatting tables in fsdocs-content, using learn.microsoft.com tables -/*--------------------------------------------------------------------------*/ + & img { + margin: 0 var(--unit-4); + border-radius: var(--radius); + height: calc(var(--icon-size) - 2px); + } -#fsdocs-content .table { - table-layout: auto; - width: 100%; - font-size: 0.875rem; + & strong { + line-height: var(--icon-size); + font-size: var(--unit-4); + display: block; + } } - #fsdocs-content .table caption { - font-size: 0.8rem; - font-weight: 600; - letter-spacing: 2px; - text-transform: uppercase; - padding: 1.125rem; - border-width: 0 0 1px; - border-style: solid; - border-color: #e3e3e3; - text-align: right; - } +aside { + display: none; +} - #fsdocs-content .table td, - #fsdocs-content .table th { - display: table-cell; - word-wrap: break-word; - padding: 0.75rem 1rem 0.75rem 0rem; - line-height: 1.5; - vertical-align: top; - border-top: 1px solid #e3e3e3; - border-right: 0; - border-left: 0; - border-bottom: 0; - border-style: solid; - } +main { + height: calc(100vh - var(--header-height)); + padding: var(--unit-2) var(--unit-4); +} - /* suppress the top line on inner lists such as tables of exceptions */ - #fsdocs-content .table .fsdocs-exception-list td, - #fsdocs-content .table .fsdocs-exception-list th { - border-top: 0 - } +/* menu items */ +.menu { + padding: 0; - #fsdocs-content .table td p:first-child, - #fsdocs-content .table th p:first-child { - margin-top: 0; + & > li { + list-style: none; } +} - #fsdocs-content .table td.nowrap, - #fsdocs-content .table th.nowrap { - white-space: nowrap; - } +.nav-header { + margin-top: var(--unit-3); + text-transform: uppercase; + font-size: var(--unit-3); +} - #fsdocs-content .table td.is-narrow, - #fsdocs-content .table th.is-narrow { - width: 15%; - } +.nav-header:first-child { + margin-top: 0; +} - #fsdocs-content .table th:not([scope='row']) { - border-top: 0; - border-bottom: 1px; - } +.nav-item { + padding-left: var(--unit-3); + padding-top: var(--unit); + border-left: 1px solid var(--header-border); - #fsdocs-content .table > caption + thead > tr:first-child > td, - #fsdocs-content .table > colgroup + thead > tr:first-child > td, - #fsdocs-content .table > thead:first-child > tr:first-child > td { - border-top: 0; + & a { + color: var(--text-color); + text-decoration: none; + font-size: var(--unit-3); } - #fsdocs-content .table table-striped > tbody > tr:nth-of-type(odd) { - background-color: var(--box-shadow-light); + &:hover { + border-color: var(--text-color); } +} - #fsdocs-content .table.min { - width: unset; +@media screen and (min-width: 768px) { + #menu-toggle { + display: none; } - #fsdocs-content .table.is-left-aligned td:first-child, - #fsdocs-content .table.is-left-aligned th:first-child { - padding-left: 0; + body { + display: grid; + grid-template-rows: var(--header-height) 1fr; + grid-template-columns:var(--aside-width) 1fr; + gap: 0; } - #fsdocs-content .table.is-left-aligned td:first-child a, - #fsdocs-content .table.is-left-aligned th:first-child a { - outline-offset: -0.125rem; - } + header { + border-bottom: 1px solid var(--header-border); + grid-row: 1; + grid-column: span 2; + } -@media screen and (max-width: 767px), screen and (min-resolution: 120dpi) and (max-width: 767.9px) { - #fsdocs-content .table.is-stacked-mobile td:nth-child(1) { - display: block; - width: 100%; - padding: 1rem 0; + aside, main { + height: calc(100vh - var(--header-height)); } - #fsdocs-content .table.is-stacked-mobile td:not(:nth-child(1)) { + aside { display: block; - border-width: 0; - padding: 0 0 1rem; + padding: var(--unit-2) var(--unit-3); + background-color: var(--header-background); + width: var(--aside-width); + border-right: 1px solid var(--header-border); } } -#fsdocs-content .table.has-inner-borders th, -#fsdocs-content .table.has-inner-borders td { - border-right: 1px solid #e3e3e3; +/*@media screen and (min-width: 768px) {*/ +/* #fsdocs-content {*/ +/* max-width: calc(var(--container-sm) - var(--aside-width) - var(--unit-8));*/ +/* min-width: calc(var(--container-sm) - var(--aside-width) - var(--unit-8));*/ +/* margin: 0 auto;*/ +/* }*/ +/*}*/ + +/*@media screen and (min-width: 960px) {*/ +/* #fsdocs-content {*/ +/* min-width: calc(var(--container-md) - var(--aside-width) - var(--unit-8));*/ +/* max-width: calc(var(--container-md) - var(--aside-width) - var(--unit-8));*/ +/* }*/ +/*}*/ + +/*@media screen and (min-width: 1024px) {*/ +/* #fsdocs-content {*/ +/* min-width: calc(var(--container-lg) - var(--aside-width) - var(--unit-8));*/ +/* max-width: calc(var(--container-lg) - var(--aside-width) - var(--unit-8));*/ +/* }*/ +/*}*/ + +/*@media screen and (min-width: 1200px) {*/ +/* #fsdocs-content {*/ +/* min-width: calc(var(--container-xl) - var(--aside-width) - var(--unit-8));*/ +/* max-width: calc(var(--container-xl) - var(--aside-width) - var(--unit-8));*/ +/* }*/ +/*}*/ + +/*@media screen and (min-width: 1400px) {*/ +/* #fsdocs-content {*/ +/* max-width: calc(var(--container-xxl) - var(--aside-width) - var(--unit-8));*/ +/* }*/ +/*}*/ + +/* Headings */ +h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { + color: var(--primary); + text-decoration: none; } - #fsdocs-content .table.has-inner-borders th:last-child, - #fsdocs-content .table.has-inner-borders td:last-child { - border-right: none; - } +h1, h2, h3, h4, h5, h6 { + margin-top: 0; + margin-bottom: var(--unit-3); +} -.fsdocs-entity-list .fsdocs-entity-name { - width: 25%; - font-weight: bold; +h1 { + font-size: var(--unit-8); } -.fsdocs-member-list .fsdocs-member-usage { - width: 35%; +h2 { + font-size: var(--unit-6); } -/*-------------------------------------------------------------------------- - Formatting xmldoc sections in fsdocs-content -/*--------------------------------------------------------------------------*/ +h3 { + font-size: var(--unit-5); +} -.fsdocs-summary { - display: inline; +h4 { + font-size: var(--unit-4); } -.fsdocs-xmldoc, .fsdocs-entity-xmldoc, .fsdocs-member-xmldoc { - font-size: 1.0rem; - line-height: 1.375rem; - letter-spacing: 0.01px; - font-weight: 500; - color: #262626; +h5 { + font-size: var(--unit-3); } -.fsdocs-xmldoc h1 { - font-size: 1.2rem; - margin: 10px 0px 0px 0px; +h6 { + font-size: var(--unit-2); } -.fsdocs-xmldoc h2 { - font-size: 1.2rem; - margin: 10px 0px 0px 0px; +/* Common items */ +a { + color: var(--link-color); } -.fsdocs-xmldoc h3 { - font-size: 1.1rem; - margin: 10px 0px 0px 0px; +p { + line-height: 1.8; } -.fsdocs-member-xmldoc details[open] summary + * { - margin-top: 1rem; +ol li { + margin-bottom: var(--unit-2); } -/* #fsdocs-nav .searchbox { - margin-top: 30px; - margin-bottom: 30px; -} */ +/* Code snippets */ -#fsdocs-nav img.logo{ - width:90%; - /* height:140px; */ - /* margin:10px 0px 0px 20px; */ - margin-top:40px; - border-style:none; +/* reset browser style */ +pre { + margin: 0; + padding: 0; } -#fsdocs-nav input{ - /* margin-left: 20px; */ - margin-right: 20px; - margin-top: 20px; - margin-bottom: 20px; - width: 93%; - -webkit-border-radius: 0; - border-radius: 0; +code, table.pre, pre { + background-color: var(--code-background); + color: var(--code-color); + font-family: var(--monospace-font); } -#fsdocs-nav { - /* margin-left: -5px; */ - /* width: 90%; */ - font-size:0.95rem; +table.pre, pre.fssnip.highlighted { + margin-bottom: var(--unit-3); } -#fsdocs-nav li.nav-header{ - /* margin-left: -5px; */ - /* width: 90%; */ - padding-left: 0; - color: #262626; - text-transform: none; - font-size:16px; - margin-top: 9px; - font-weight: bold; +table.pre, pre.fssnip { + padding: var(--unit) var(--unit-2); } -#fsdocs-nav a{ - padding-left: 0; - color: #6c6c6d; - /* margin-left: 5px; */ - /* width: 90%; */ +p > code, li > code { + padding: var(--unit); + transform: translateY(var(--unit)); } -/*-------------------------------------------------------------------------- - Formatting pre and code sections in fsdocs-content (code highlighting is - further below) -/*--------------------------------------------------------------------------*/ +table.pre, code { + overflow-x: auto; + max-width: calc(100vw - var(--unit-12)); + box-sizing: border-box; + border-radius: var(--radius); +} -#fsdocs-content code { - /* font-size: 0.83rem; */ - font: 0.85rem 'Roboto Mono', monospace; - background-color: #f7f7f900; - border: 0px; - padding: 0px; - /* word-wrap: break-word; */ - /* white-space: pre; */ +table.pre, pre > code { + display: block; } -/* omitted */ -#fsdocs-content span.omitted { - background: #3c4e52; - border-radius: 5px; - color: #808080; - padding: 0px 0px 1px 0px; +pre.fssnip > code { + max-width: initial; + margin-bottom: initial; } -#fsdocs-content pre .fssnip code { - font: 0.86rem 'Roboto Mono', monospace; +/* copy icons in the shell commands */ +table.pre td iconify-icon { + margin-top: 4px; } -#fsdocs-content table.pre, -#fsdocs-content pre.fssnip, -#fsdocs-content pre { - line-height: 13pt; - border: 0px solid #d8d8d8; - border-top: 0px solid #e3e3e3; - border-collapse: separate; - white-space: pre; - font: 0.86rem 'Roboto Mono', monospace; - width: 100%; - margin: 10px 0px 20px 0px; - background-color: #f3f4f7; - padding: 10px; - border-radius: 5px; - color: #8e0e2b; - max-width: none; - box-sizing: border-box; +@media screen and (min-width: 768px) { + table.pre, code { + max-width: var(--container-sm); + } } -#fsdocs-content pre.fssnip code { - font: 0.86rem 'Roboto Mono', monospace; - font-weight: 600; +@media screen and (min-width: 960px) { + table.pre, code { + max-width: var(--container-md); + } } -#fsdocs-content table.pre { - background-color: #fff7ed; +@media screen and (min-width: 1024px) { + table.pre, code { + max-width: var(--container-lg); + } } -#fsdocs-content table.pre pre { - padding: 0px; - margin: 0px; - border-radius: 0px; - width: 100%; - background-color: #fff7ed; - color: #837b79; +@media screen and (min-width: 1200px) { + table.pre, code { + max-width: var(--container-xl); + } } -#fsdocs-content table.pre td { - padding: 0px; - white-space: normal; - margin: 0px; - width: 100%; +@media screen and (min-width: 1400px) { + table.pre, code { + max-width: var(--container-xxl); + } } -#fsdocs-content table.pre td.lines { - width: 30px; +/* Code coloring */ +.param-name, +.return-name, +.param { + font-weight: 900; + font-size: 0.85rem; + font-family: 'Roboto Mono', monospace; } +.fssnip { + /* strings --- and stlyes for other string related formats */ -#fsdocs-content pre { - word-wrap: inherit; -} + & span.s { + color: var(--code-strings-color); + } -.fsdocs-example-header { - font-size: 1.0rem; - line-height: 1.375rem; - letter-spacing: 0.01px; - font-weight: 700; - color: #262626; -} + /* printf formatters */ -/*-------------------------------------------------------------------------- - Formatting github source links -/*--------------------------------------------------------------------------*/ + & span.pf { + color: var(--code-printf-color); + } -.fsdocs-source-link { - float: right; - text-decoration: none; -} + /* escaped chars */ - .fsdocs-source-link img { - border-style: none; - margin-left: 10px; - width: auto; - height: 1.4em; + & span.e { + color: var(--code-escaped-color); } - .fsdocs-source-link .hover { - display: none; + /* identifiers --- and styles for more specific identifier types */ + + & span.id { + color: var(--code-identifiers-color);; } - .fsdocs-source-link:hover .hover { - display: block; + /* module */ + + & span.m { + color: var(--code-module-color); } - .fsdocs-source-link .normal { - display: block; + /* reference type */ + + & span.rt { + color: var(--code-reference-color); } - .fsdocs-source-link:hover .normal { - display: none; + /* value type */ + + & span.vt { + color: var(--code-value-color); } -/*-------------------------------------------------------------------------- - Formatting logo -/*--------------------------------------------------------------------------*/ - -#fsdocs-logo { - width:140px; - height:140px; - margin:10px 0px 0px 0px; - border-style:none; -} - -/*-------------------------------------------------------------------------- - -/*--------------------------------------------------------------------------*/ - -#fsdocs-content table.pre pre { - padding: 0px; - margin: 0px; - border: none; -} - -/*-------------------------------------------------------------------------- - Remove formatting from links -/*--------------------------------------------------------------------------*/ - -#fsdocs-content h1 a, -#fsdocs-content h1 a:hover, -#fsdocs-content h1 a:focus, -#fsdocs-content h2 a, -#fsdocs-content h2 a:hover, -#fsdocs-content h2 a:focus, -#fsdocs-content h3 a, -#fsdocs-content h3 a:hover, -#fsdocs-content h3 a:focus, -#fsdocs-content h4 a, -#fsdocs-content h4 a:hover, #fsdocs-content -#fsdocs-content h4 a:focus, -#fsdocs-content h5 a, -#fsdocs-content h5 a:hover, -#fsdocs-content h5 a:focus, -#fsdocs-content h6 a, -#fsdocs-content h6 a:hover, -#fsdocs-content h6 a:focus { - color: #262626; - text-decoration: none; - text-decoration-style: none; - /* outline: none */ -} + /* interface */ -/*-------------------------------------------------------------------------- - Formatting for F# code snippets -/*--------------------------------------------------------------------------*/ + & span.if { + color: var(--code-interface-color); + } -.fsdocs-param-name, -.fsdocs-return-name, -.fsdocs-param { - font-weight: 900; - font-size: 0.85rem; - font-family: 'Roboto Mono', monospace; -} -/* strings --- and stlyes for other string related formats */ -#fsdocs-content span.s { - color: #dd1144; -} -/* printf formatters */ -#fsdocs-content span.pf { - color: #E0C57F; -} -/* escaped chars */ -#fsdocs-content span.e { - color: #EA8675; -} + /* type argument */ -/* identifiers --- and styles for more specific identifier types */ -#fsdocs-content span.id { - color: #262626; -} -/* module */ -#fsdocs-content span.m { - color: #009999; -} -/* reference type */ -#fsdocs-content span.rt { - color: #4974D1; -} -/* value type */ -#fsdocs-content span.vt { - color: #43AEC6; -} -/* interface */ -#fsdocs-content span.if { - color: #43AEC6; -} -/* type argument */ -#fsdocs-content span.ta { - color: #43AEC6; -} -/* disposable */ -#fsdocs-content span.d { - color: #43AEC6; -} -/* property */ -#fsdocs-content span.prop { - color: #43AEC6; -} -/* punctuation */ -#fsdocs-content span.p { - color: #43AEC6; -} -#fsdocs-content span.pn { - color: #262626; -} -/* function */ -#fsdocs-content span.f { - color: #e1e1e1; -} -#fsdocs-content span.fn { - color: #990000; -} -/* active pattern */ -#fsdocs-content span.pat { - color: #4ec9b0; -} -/* union case */ -#fsdocs-content span.u { - color: #4ec9b0; -} -/* enumeration */ -#fsdocs-content span.e { - color: #4ec9b0; -} -/* keywords */ -#fsdocs-content span.k { - color: #b68015; - /* font-weight: bold; */ -} -/* comment */ -#fsdocs-content span.c { - color: #808080; - font-weight: 400; - font-style: italic; -} -/* operators */ -#fsdocs-content span.o { - color: #af75c1; -} -/* numbers */ -#fsdocs-content span.n { - color: #009999; -} -/* line number */ -#fsdocs-content span.l { - color: #80b0b0; + & span.ta { + color: var(--code-typearg-color); + } + + /* disposable */ + + & span.d { + color: var(--code-disposable-color); + } + + /* property */ + + & span.prop { + color: var(--code-property-color); + } + + /* punctuation */ + + & span.p { + color: var(--code-punctuation-color); + } + + & span.pn { + color: var(--code-punctuation2-color); + } + + /* function */ + + & span.f { + color: var(--code-function-color); + } + + & span.fn { + color: var(--code-function2-color); + } + + /* active pattern */ + + & span.pat { + color: var(--code-activepattern-color); + } + + /* union case */ + + & span.u { + color: var(--code-unioncase-color); + } + + /* enumeration */ + + & span.e { + color: var(--code-enumeration-color); + } + + /* keywords */ + + & span.k { + color: var(--code-keywords-color); + } + + /* comment */ + + & span.c { + color: var(--code-comment-color); + font-weight: 400; + font-style: italic; + } + + /* operators */ + + & span.o { + color: var(--code-operators-color); + } + + /* numbers */ + + & span.n { + color: var(--code-numbers-color); + } + + /* line number */ + + & span.l { + color: var(--code-linenumbers-color); + } + + /* mutable var or ref cell */ + + & span.v { + color: var(--code-mutable-color); + font-weight: bold; + } + + /* inactive code */ + + & span.inactive { + color: var(--code-inactive-color); + } + + /* preprocessor */ + + & span.prep { + color: var(--code-preprocessor-color); + } + + /* fsi output */ + + & span.fsi { + color: var(--code-fsioutput-color); + } } -/* mutable var or ref cell */ -#fsdocs-content span.v { - color: #d1d1d1; - font-weight: bold; + + +/* tooltips */ + +div.fsdocs-tip { + z-index: 1000; + display: none; + background-color: var(--doc-tip-background); + border-radius: var(--radius); + border: 1px solid var(--header-border); + padding: var(--unit-3); + font-family: var(--monospace-font); + color: var(--code-color); + + & code { + color: var(--code-color); + } } -/* inactive code */ -#fsdocs-content span.inactive { - color: #808080; + +span[onmouseout] { + cursor: pointer; } -/* preprocessor */ -#fsdocs-content span.prep { - color: #af75c1; + +/* API docs */ +.table { + width: 100%; + + & thead tr td { + font-weight: bold; + padding: var(--unit-3) 0; + } + + & tbody td { + border-top: 1px solid var(--header-border); + padding: var(--unit-2) 0; + } + + .fsdocs-entity-xmldoc { + > div { + display: flex; + flex-direction: row-reverse; + justify-content: flex-start; + align-items: center; + + > p { + margin: 0 var(--unit-2) 0 0; + } + } + } + + .fsdocs-member-usage { + display: block; + margin-right: var(--unit-2); + } + + .fsdocs-member-xmldoc { + & details { + margin-left: var(--unit-2); + + & .fsdocs-summary { + margin-left: var(--unit-2); + } + } + + & summary { + list-style: none; + + .fsdocs-summary { + display: flex; + align-items: center; + } + + &::after { + content: '▶'; + cursor: pointer; + margin-left: var(--unit-4); + } + } + + & details[open] summary::after { + content: "▼"; + } + + .fsdocs-returns, .fsdocs-params { + margin-left: var(--unit-4); + } + + /* hide the browser mark and display one after the summary */ + + & ::marker { + display: none; + } + } } -/* fsi output */ -#fsdocs-content span.fsi { - color: #808080; + +.fsdocs-source-link { + padding: 0 var(--unit); + + > img { + height: var(--icon-size); + cursor: pointer; + + &.hover { + display: none; + } + } + + &:hover { + > img.normal { + display: none; + } + + > img.hover { + display: block; + } + } } -/* tool tip */ -div.fsdocs-tip { - background: #475b5f; - border-radius: 4px; - font: 0.85rem 'Roboto Mono', monospace; - padding: 6px 8px 6px 8px; +[data-theme=dark] { + .fsdocs-source-link img.normal { + filter: invert(1); + } +; +} + +/* dark theme */ + +[data-theme=dark] { + --primary: #81cfe0; + --background: #32283c; + --text-color: #F7F7F7; + --text-hover: #FFF; + --code-background: #3e3e42; + --code-color: #f5f5f6; + --header-border: #9b9b9b; + --doc-tip-background: #2e293a; + --link-color: #c5eff7; + --search-background: #020202; + --nav-category: rgb(207, 211, 215); + + --code-strings-color: #5adfec; + --code-printf-color: #6B2FBA; + --code-escaped-color: #EA8675; + --code-identifiers-color: #d1b3f5; + --code-module-color: #15e1e1; + --code-reference-color: #7a9cee; + --code-value-color: #66d73d; + --code-interface-color: #43AEC6; + --code-typearg-color: #43AEC6; + --code-disposable-color: #6dd6f1; + --code-property-color: #6acfe7; + --code-punctuation-color: #43AEC6; + --code-punctuation2-color: var(--text-color); + --code-function-color: #6B2FBA; + --code-function2-color: #da9d9d; + --code-activepattern-color: #4ec9b0; + --code-unioncase-color: #4ec9b0; + --code-enumeration-color: #8C6C41; + --code-keywords-color: #a7c2f8; + --code-comment-color: #dcd8d8; + --code-operators-color: #b4c6ee; + --code-numbers-color: #009999; + --code-linenumbers-color: #80b0b0; + --code-mutable-color: #1b6600; + --code-inactive-color: #808080; + --code-preprocessor-color: #af75c1; + --code-fsioutput-color: #808080; + --code-tooltip-color: #d1d1d1; +} + +/* theme toggling */ + +.themeToggle.dark { + display: block; +} + +.themeToggle.light { display: none; - color: #d1d1d1; - pointer-events: none; } - div.fsdocs-tip code { - color: #d1d1d1; - font: 0.85rem 'Roboto Mono', monospace; +[data-theme=dark] { + .themeToggle.light { + display: block; } + .themeToggle.dark { + display: none; + } +} + +.themeToggle { + cursor: pointer; + color: var(--text-color); + + &:hover { + color: var(--text-hover); + } +} \ No newline at end of file diff --git a/docs/content/navbar-fixed-left.css b/docs/content/navbar-fixed-left.css deleted file mode 100644 index 2de6255a8..000000000 --- a/docs/content/navbar-fixed-left.css +++ /dev/null @@ -1,77 +0,0 @@ -body { - padding-top: 90px; -} - -@media (min-width: 768px) { - body { - padding-top: 0; - } -} - -@media (min-width: 768px) { - body { - margin-left: 252px; - } -} -.navbar { - overflow-y: auto; - overflow-x: hidden; - box-shadow: none; -} -.navbar.fixed-left { - position: fixed; - top: 0; - left: 0; - right: 0; - z-index: 1030; -} -.navbar-nav .nav-link { - padding-top: 0.3rem; - padding-bottom: 0.3rem; -} - -@media (min-width: 768px) { - .navbar.fixed-left { - bottom: 0; - width: 252px; - flex-flow: column nowrap; - align-items: flex-start; - } - - .navbar.fixed-left .navbar-collapse { - flex-grow: 0; - flex-direction: column; - width: 100%; - } - - .navbar.fixed-left .navbar-collapse .navbar-nav { - flex-direction: column; - width: 100%; - } - - .navbar.fixed-left .navbar-collapse .navbar-nav .nav-item { - width: 100%; - } - - .navbar.fixed-left .navbar-collapse .navbar-nav .nav-item .dropdown-menu { - top: 0; - } -} - -@media (min-width: 768px) { - .navbar.fixed-left { - right: auto; - } - - .navbar.fixed-left .navbar-nav .nav-item .dropdown-toggle:after { - border-top: 0.3em solid transparent; - border-left: 0.3em solid; - border-bottom: 0.3em solid transparent; - border-right: none; - vertical-align: baseline; - } - - .navbar.fixed-left .navbar-nav .nav-item .dropdown-menu { - left: 100%; - } -} diff --git a/docs/content/navbar-fixed-right.css b/docs/content/navbar-fixed-right.css deleted file mode 100644 index ad6cef83b..000000000 --- a/docs/content/navbar-fixed-right.css +++ /dev/null @@ -1,78 +0,0 @@ -body { - padding-top: 90px; -} - -@media (min-width: 768px) { - body { - padding-top: 0; - } -} - -@media (min-width: 768px) { - body { - margin-right: 252px; - } -} - -.navbar { - overflow-y: auto; - overflow-x: hidden; - box-shadow: none; -} -.navbar.fixed-right { - position: fixed; - top: 0; - left: 0; - right: 0; - z-index: 1030; -} -.navbar-nav .nav-link { - padding-top: 0.3rem; - padding-bottom: 0.3rem; -} -@media (min-width: 768px) { - .navbar.fixed-right { - bottom: 0; - width: 252px; - flex-flow: column nowrap; - align-items: flex-start; - } - - .navbar.fixed-right .navbar-collapse { - flex-grow: 0; - flex-direction: column; - width: 100%; - } - - .navbar.fixed-right .navbar-collapse .navbar-nav { - flex-direction: column; - width: 100%; - } - - .navbar.fixed-right .navbar-collapse .navbar-nav .nav-item { - width: 100%; - } - - .navbar.fixed-right .navbar-collapse .navbar-nav .nav-item .dropdown-menu { - top: 0; - } -} - -@media (min-width: 768px) { - .navbar.fixed-right { - left: auto; - } - - .navbar.fixed-right .navbar-nav .nav-item .dropdown-toggle:after { - border-top: 0.3em solid transparent; - border-left: none; - border-bottom: 0.3em solid transparent; - border-right: 0.3em solid; - vertical-align: baseline; - } - - .navbar.fixed-right .navbar-nav .nav-item .dropdown-menu { - left: auto; - right: 100%; - } -} diff --git a/docs/sidebyside/_template.html b/docs/sidebyside/_template.html deleted file mode 100644 index 59c7f5cfa..000000000 --- a/docs/sidebyside/_template.html +++ /dev/null @@ -1,89 +0,0 @@ - - - - - - {{fsdocs-page-title}} - - - - - - - - - - - - - - - - - - - - - - - -
-
-

{{fsdocs-collection-name}}

-
-
-
-
-
- {{fsdocs-source}} -
-
- {{fsdocs-content}} - {{fsdocs-tooltips}} -
-
-
- - - - - - - - -
- - - - diff --git a/docs/sidebyside/sideextensions.md b/docs/sidebyside/sideextensions.md deleted file mode 100644 index 76d1630e3..000000000 --- a/docs/sidebyside/sideextensions.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Markdown LaTeX -category: Examples -categoryindex: 2 -index: 3 ---- -Example: Using the Markdown Extensions for LaTeX -=================== - -To use LaTex extension, you need add javascript -link to [MathJax](http://www.mathjax.org/) in -your template. - -To use inline LaTex, eclose LaTex code with `$`: -$ k_{n+1} = n^2 + k_n^2 - k_{n-1} $. Alternatively, -you can also use `$$`. - -To use block LaTex, start a new parapgraph, with -the first line marked as `$$$` (no close `$$$`): - -$$$ -A_{m,n} = - \begin{pmatrix} - a_{1,1} & a_{1,2} & \cdots & a_{1,n} \\ - a_{2,1} & a_{2,2} & \cdots & a_{2,n} \\ - \vdots & \vdots & \ddots & \vdots \\ - a_{m,1} & a_{m,2} & \cdots & a_{m,n} - \end{pmatrix} - -Use LaTex escape rule: - -- Escape \$ in inline mode: $ \$ $, $ \$var $ -- Other escapes: $ \& \% \$ \# \_ \{ \} $ -- Using < or >: $ x > 1 $, $ y < 1 $, $ x >= 1 $, - $ y <= 1 $, $ x = 1 $ -- $

something

$ - - diff --git a/docs/sidebyside/sidemarkdown.md b/docs/sidebyside/sidemarkdown.md deleted file mode 100644 index 4a81cfb9f..000000000 --- a/docs/sidebyside/sidemarkdown.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Markdown Content -category: Examples -categoryindex: 2 -index: 2 ---- -# Example: Using Markdown Content - -This file demonstrates how to write Markdown document with -embedded F# snippets that can be transformed into nice HTML -using the `literate.fsx` script from the [F# Formatting -package](http://fsprojects.github.io/FSharp.Formatting). - -In this case, the document itself is a valid Markdown and -you can use standard Markdown features to format the text: - - - Here is an example of unordered list and... - - Text formatting including **bold** and _emphasis_ - -For more information, see the [Markdown][md] reference. - - [md]: http://daringfireball.net/projects/markdown - - -## Writing F# code - -In standard Markdown, you can include code snippets by -writing a block indented by four spaces and the code -snippet will be turned into a `
` element. If you do 
-the same using Literate F# tool, the code is turned into
-a nicely formatted F# snippet:
-
-    /// The Hello World of functional languages!
-    let rec factorial x = 
-      if x = 0 then 1 
-      else x * (factorial (x - 1))
-
-    let f10 = factorial 10
-
-
-## Hiding code
-
-If you want to include some code in the source code, 
-but omit it from the output, you can use the `hide` 
-command. You can also use `module=...` to specify that 
-the snippet should be placed in a separate module 
-(e.g. to avoid duplicate definitions).
-
-    [hide, module=Hidden]
-    /// This is a hidden answer
-    let answer = 42
-
-The value will be deffined in the F# code that is 
-processed and so you can use it from other (visible) 
-code and get correct tool tips:
-
-    let answer = Hidden.answer
-
-## Including other snippets
-
-When writing literate programs as Markdown documents, 
-you can also include snippets in other languages. 
-These will not be colorized and processed as F# 
-code samples:
-
-    [lang=csharp]
-    Console.WriteLine("Hello world!");
-
-This snippet is turned into a `pre` element with the
-`lang` attribute set to `csharp`.
diff --git a/docs/sidebyside/sidescript.fsx b/docs/sidebyside/sidescript.fsx
deleted file mode 100644
index 846ceaabf..000000000
--- a/docs/sidebyside/sidescript.fsx
+++ /dev/null
@@ -1,90 +0,0 @@
-(**
----
-title: Literate Script
-category: Examples
-categoryindex: 2
-index: 1
----
-# Example: Using Literate Script Content
-
-This file demonstrates how to write literate F# script
-files (`*.fsx`) that can be transformed into nice HTML
-using the `literate.fsx` script from the [F# Formatting
-package](http://fsprojects.github.io/FSharp.Formatting).
-
-As you can see, a comment starting with double asterisk
-is treated as part of the document and is transformed
-using Markdown, which means that you can use:
-
- - Unordered or ordered lists
- - Text formatting including **bold** and _emphasis_
-
-And numerous other [Markdown][md] features.
-
- [md]: http://daringfireball.net/projects/markdown
-
-## Writing F# code
-
-Code that is not inside comment will be formatted as
-a sample snippet.
-*)
-
-/// The Hello World of functional languages!
-let rec factorial x =
-    if x = 0 then 1 else x * (factorial (x - 1))
-
-let f10 = factorial 10
-
-(**
-Hiding code
------------
-
-If you want to include some code in the source code,
-but omit it from the output, you can use the `hide`
-command.
-*)
-
-(*** hide ***)
-/// This is a hidden answer
-let hidden = 42
-
-(**
-The value will be defined in the F# code and so you
-can use it from other (visible) code and get correct
-tool tips:
-*)
-
-let answer = hidden
-
-(**
-## Moving code around
-
-Sometimes, it is useful to first explain some code that
-has to be located at the end of the snippet (perhaps
-because it uses some definitions discussed in the middle).
-This can be done using `include` and `define` commands.
-
-The following snippet gets correct tool tips, even though
-it uses `laterFunction`:
-*)
-
-(*** include:later-bit ***)
-
-(**
-Then we can explain how `laterFunction` is defined:
-*)
-
-let laterFunction () = "Not very difficult, is it?"
-
-(**
-This example covers pretty much all features that are
-currently implemented in `literate.fsx`, but feel free
-to [fork the project on GitHub][fs] and add more
-features or report bugs!
-
-  [fs]: https://github.com/fsprojects/FSharp.Formatting
-
-*)
-
-(*** define:later-bit ***)
-let sample = laterFunction () |> printfn "Got: %s"
diff --git a/docs/templates/leftside/_template.html b/docs/templates/leftside/_template.html
deleted file mode 100644
index 84a58b472..000000000
--- a/docs/templates/leftside/_template.html
+++ /dev/null
@@ -1,82 +0,0 @@
-
-
-
-
-    
-    {{fsdocs-page-title}}
-    
-    
-
-    
-    
-    
-
-    
-
-    
-    
-    
-    
-    
-    
-    
-    
-    
-    {{fsdocs-watch-script}}
-
-
-
-    
-    

-        

-            
{{fsdocs-collection-name}}

-        

-        

-        

-            {{fsdocs-content}}
-            {{fsdocs-tooltips}}
-        

-
-        
-        
-        
-        
-        
-        
-        
-    

-
-
-
-
diff --git a/docs/templates/leftside/styling.md b/docs/templates/leftside/styling.md
deleted file mode 100644
index a3221a78b..000000000
--- a/docs/templates/leftside/styling.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-# Example: Right-Side NavBar
-category: Examples
-categoryindex: 2
-index: 4
----
-
-# Example: Styling for Right-Side Navigation Bar
-
-The sidebar can be moved to the right by using 
-
-   `fixed-right`
-   
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?
-
diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs
index 284acdd5b..913632771 100644
--- a/src/fsdocs-tool/BuildCommand.fs
+++ b/src/fsdocs-tool/BuildCommand.fs
@@ -728,7 +728,7 @@ module Serve =
 
     refreshEvent.Publish
     |> Event.add (fun fileName ->
-        let fileName = fileName.TrimEnd('~')
+        let fileName = fileName.Replace("\\", "/").TrimEnd('~')
         broadCastReload fileName)
 
     let startWebServer rootOutputFolderAsGiven localPort =

From 777e7a4d361c3877d7b26f82bc639ec55261281c Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 16 Oct 2023 08:36:38 +0200
Subject: [PATCH 02/71] Only refresh when file has extension.

---
 src/fsdocs-tool/BuildCommand.fs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs
index 913632771..7ad603789 100644
--- a/src/fsdocs-tool/BuildCommand.fs
+++ b/src/fsdocs-tool/BuildCommand.fs
@@ -728,8 +728,9 @@ module Serve =
 
     refreshEvent.Publish
     |> Event.add (fun fileName ->
-        let fileName = fileName.Replace("\\", "/").TrimEnd('~')
-        broadCastReload fileName)
+        if Path.HasExtension fileName then
+            let fileName = fileName.Replace("\\", "/").TrimEnd('~')
+            broadCastReload fileName)
 
     let startWebServer rootOutputFolderAsGiven localPort =
         let mimeTypesMap ext =

From a57c6bbce79fde10d7eddb2a00c2443d43413bda Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 16 Oct 2023 08:38:39 +0200
Subject: [PATCH 03/71] Style content responsively.

---
 docs/_template.html             |  29 +++++----
 docs/content/fsdocs-default.css | 107 ++++++++++++++++++--------------
 docs/content/fsdocs-tips.js     |  59 +++++++++---------
 3 files changed, 107 insertions(+), 88 deletions(-)

diff --git a/docs/_template.html b/docs/_template.html
index 5c07708da..27ed9f32f 100644
--- a/docs/_template.html
+++ b/docs/_template.html
@@ -2,24 +2,24 @@
 
 
     
-    
-    
-    
+    
+    
+    
     {{fsdocs-page-title}} | {{fsdocs-collection-name}}
-    
-    
+    
+    
     
     
-    
-    
+    
+    
     {{fsdocs-watch-script}}
 
 
 

     
-    Header menu logo
+    Header menu logo
     {{fsdocs-collection-name}}
 

 
 

-    {{fsdocs-content}}
-    {{fsdocs-tooltips}}
+    

+        {{fsdocs-content}}
+        {{fsdocs-tooltips}}
+    

 

+
 
 
\ No newline at end of file
diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css
index 7c9f913c9..0a769f47b 100644
--- a/docs/content/fsdocs-default.css
+++ b/docs/content/fsdocs-default.css
@@ -86,7 +86,7 @@ body {
     -webkit-font-smoothing: antialiased;
 }
 
-img, picture, video, canvas, svg {
+picture, video, canvas, svg {
     display: block;
     max-width: 100%;
 }
@@ -190,7 +190,10 @@ aside {
 
 main {
     height: calc(100vh - var(--header-height));
-    padding: var(--unit-2) var(--unit-4);
+}
+
+#content {
+    padding: var(--unit-2) var(--unit-2);
 }
 
 /* menu items */
@@ -235,8 +238,8 @@ main {
 
     body {
         display: grid;
-        grid-template-rows: var(--header-height) 1fr;
-        grid-template-columns:var(--aside-width) 1fr;
+        grid-template-rows: var(--header-height) minmax(0, 1fr);
+        grid-template-columns:var(--aside-width) minmax(0, 1fr);
         gap: 0;
     }
 
@@ -247,52 +250,61 @@ main {
     }
 
     aside, main {
-        height: calc(100vh - var(--header-height));
+        min-height: calc(100vh - var(--header-height));
     }
 
     aside {
         display: block;
-        padding: var(--unit-2) var(--unit-3);
+        padding: var(--unit-2) var(--unit-6);
         background-color: var(--header-background);
         width: var(--aside-width);
         border-right: 1px solid var(--header-border);
+        grid-row: 2;
+        grid-row-end: 3;
+    }
+
+    main {
+        grid-row: 2;
+        grid-column: 2;
+        overflow-y: auto;
+    }
+
+    #content {
+        padding-left: var(--unit-4);
+        padding-right: var(--unit-4);
+    }
+}
+
+@media screen and (min-width: 768px) {
+    #content {
+        max-width: calc(100vw - var(--aside-width) - var(--unit-4));
+        margin: 0 auto;
+    }
+}
+
+@media screen and (min-width: 960px) {
+    #content {
+        max-width: calc(var(--container-md) - var(--aside-width) - var(--unit-4));
     }
 }
 
-/*@media screen and (min-width: 768px) {*/
-/*    #fsdocs-content {*/
-/*        max-width: calc(var(--container-sm) - var(--aside-width) - var(--unit-8));*/
-/*        min-width: calc(var(--container-sm) - var(--aside-width) - var(--unit-8));*/
-/*        margin: 0 auto;*/
-/*    }*/
-/*}*/
-
-/*@media screen and (min-width: 960px) {*/
-/*    #fsdocs-content {*/
-/*        min-width: calc(var(--container-md) - var(--aside-width) - var(--unit-8));*/
-/*        max-width: calc(var(--container-md) - var(--aside-width) - var(--unit-8));*/
-/*    }*/
-/*}*/
-
-/*@media screen and (min-width: 1024px) {*/
-/*    #fsdocs-content {*/
-/*        min-width: calc(var(--container-lg) - var(--aside-width) - var(--unit-8));*/
-/*        max-width: calc(var(--container-lg) - var(--aside-width) - var(--unit-8));*/
-/*    }*/
-/*}*/
-
-/*@media screen and (min-width: 1200px) {*/
-/*    #fsdocs-content {*/
-/*        min-width: calc(var(--container-xl) - var(--aside-width) - var(--unit-8));*/
-/*        max-width: calc(var(--container-xl) - var(--aside-width) - var(--unit-8));*/
-/*    }*/
-/*}*/
-
-/*@media screen and (min-width: 1400px) {*/
-/*    #fsdocs-content {*/
-/*        max-width: calc(var(--container-xxl) - var(--aside-width) - var(--unit-8));*/
-/*    }*/
-/*}*/
+@media screen and (min-width: 1024px) {
+    #content {
+        max-width: calc(var(--container-lg) - var(--aside-width) - var(--unit-4));
+    }
+}
+
+@media screen and (min-width: 1200px) {
+    #content {
+        max-width: calc(var(--container-xl) - var(--aside-width) - var(--unit-4));
+    }
+}
+
+@media screen and (min-width: 1400px) {
+    #content {
+        max-width: calc(var(--container-xxl) - var(--aside-width) - var(--unit-4));
+    }
+}
 
 /* Headings */
 h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
@@ -342,6 +354,10 @@ ol li {
     margin-bottom: var(--unit-2);
 }
 
+#content > table {
+    margin: var(--unit-2) 0;
+}
+
 /* Code snippets */
 
 /* reset browser style */
@@ -391,31 +407,31 @@ table.pre td iconify-icon {
 }
 
 @media screen and (min-width: 768px) {
-    table.pre, code {
+    table, code {
         max-width: var(--container-sm);
     }
 }
 
 @media screen and (min-width: 960px) {
-    table.pre, code {
+    table, code {
         max-width: var(--container-md);
     }
 }
 
 @media screen and (min-width: 1024px) {
-    table.pre, code {
+    table, code {
         max-width: var(--container-lg);
     }
 }
 
 @media screen and (min-width: 1200px) {
-    table.pre, code {
+    table, code {
         max-width: var(--container-xl);
     }
 }
 
 @media screen and (min-width: 1400px) {
-    table.pre, code {
+    table, code {
         max-width: var(--container-xxl);
     }
 }
@@ -594,7 +610,6 @@ table.pre td iconify-icon {
 
 
 /* tooltips */
-
 div.fsdocs-tip {
     z-index: 1000;
     display: none;
diff --git a/docs/content/fsdocs-tips.js b/docs/content/fsdocs-tips.js
index bcd04cb10..d17e65f52 100644
--- a/docs/content/fsdocs-tips.js
+++ b/docs/content/fsdocs-tips.js
@@ -1,54 +1,55 @@
-var currentTip = null;
-var currentTipElement = null;
+let currentTip = null;
+let currentTipElement = null;
 
 function hideTip(evt, name, unique) {
-    var el = document.getElementById(name);
+    const el = document.getElementById(name);
     el.style.display = "none";
     currentTip = null;
 }
 
-function findPos(obj) {
-    // no idea why, but it behaves differently in webbrowser component
-    if (window.location.search == "?inapp")
-        return [obj.offsetLeft + 10, obj.offsetTop + 30];
-
-    var curleft = 0;
-    var curtop = obj.offsetHeight;
-    while (obj) {
-        curleft += obj.offsetLeft;
-        curtop += obj.offsetTop;
-        obj = obj.offsetParent;
-    };
-    return [curleft, curtop];
-}
-
 function hideUsingEsc(e) {
-    if (!e) { e = event; }
     hideTip(e, currentTipElement, currentTip);
 }
 
 function showTip(evt, name, unique, owner) {
     document.onkeydown = hideUsingEsc;
-    if (currentTip == unique) return;
+    if (currentTip === unique) return;
     currentTip = unique;
     currentTipElement = name;
 
-    var pos = findPos(owner ? owner : (evt.srcElement ? evt.srcElement : evt.target));
-    var posx = pos[0];
-    var posy = pos[1];
+    const offset = 20;
+    let x = evt.clientX;
+    let y = evt.clientY + offset;
 
-    var el = document.getElementById(name);
-    var parent = (document.documentElement == null) ? document.body : document.documentElement;
+    const el = document.getElementById(name);
     el.style.position = "absolute";
-    el.style.left = posx + "px";
-    el.style.top = posy + "px";
     el.style.display = "block";
+    el.style.left = `${x}px`;
+    el.style.top = `${y}px`;
+
+    const rect =  el.getBoundingClientRect();
+    // Move tooltip if it is out of sight
+    if(rect.bottom > window.innerHeight) {
+        y = y - el.clientHeight - offset;
+        el.style.top = `${y}px`;
+    }
+
+    if (rect.right > window.innerWidth) {
+        x = y - el.clientWidth - offset;
+        el.style.left = `${x}px`;
+    }
 }
+
 function Clipboard_CopyTo(value) {
-    var tempInput = document.createElement("input");
+    const tempInput = document.createElement("input");
     tempInput.value = value;
     document.body.appendChild(tempInput);
     tempInput.select();
     document.execCommand("copy");
     document.body.removeChild(tempInput);
-}
\ No newline at end of file
+}
+
+window.showTip = showTip;
+window.hideTip = hideTip;
+// Used by API documentation
+window.Clipboard_CopyTo = Clipboard_CopyTo;
\ No newline at end of file

From 22f2579cc7af3dc7823113f010c339f5c4193523 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 16 Oct 2023 09:36:33 +0200
Subject: [PATCH 04/71] Toggle between dark and light.

---
 FSharp.Formatting.sln               |   1 +
 docs/_template.html                 |  46 ++++---
 docs/content/fsdocs-default.css     | 198 +++++++++++++++-------------
 docs/content/fsdocs-theme-toggle.js |  54 ++++++++
 4 files changed, 189 insertions(+), 110 deletions(-)
 create mode 100644 docs/content/fsdocs-theme-toggle.js

diff --git a/FSharp.Formatting.sln b/FSharp.Formatting.sln
index d7c141c06..18bf78788 100644
--- a/FSharp.Formatting.sln
+++ b/FSharp.Formatting.sln
@@ -124,6 +124,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "content", "content", "{FAD5
 		docs\content\fsdocs-default.css = docs\content\fsdocs-default.css
 		docs\content\fsdocs-search.js = docs\content\fsdocs-search.js
 		docs\content\fsdocs-tips.js = docs\content\fsdocs-tips.js
+		docs\content\fsdocs-theme-toggle.js = docs\content\fsdocs-theme-toggle.js
 	EndProjectSection
 EndProject
 Global
diff --git a/docs/_template.html b/docs/_template.html
index 27ed9f32f..fd2e7681d 100644
--- a/docs/_template.html
+++ b/docs/_template.html
@@ -16,25 +16,34 @@
 
 
 

-
+ \ No newline at end of file diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 0a769f47b..fca5c3b37 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -39,6 +39,7 @@ --menu-icon-hover-background: #bdc3c7; --doc-tip-background: #F7F7F7; --link-color: #4871f7; + --link-hover: #91aafa; --search-background: rgb(229, 231, 235); --nav-category: rgb(156, 163, 175); @@ -102,6 +103,8 @@ p, h1, h2, h3, h4, h5, h6 { /* Main layout */ body { font-family: var(--system-font); + background-color: var(--background); + color: var(--text-color); } header { @@ -110,77 +113,105 @@ header { height: var(--header-height); display: flex; align-items: center; + justify-content: space-between; + position: sticky; + top: 0; + + & .start { + display: flex; + align-items: center; + + & #menu-toggle { + position: relative; + height: var(--icon-size); + width: var(--icon-size); + border: 1px solid var(--header-border); + border-radius: var(--radius); + + & .icon { + top: 3px; + left: 3px; + width: calc(var(--icon-size) - 4px); + height: calc(var(--icon-size) - 4px); + position: absolute; + + &.open { + display: none; + } + } - & #menu-toggle { - position: relative; - height: var(--icon-size); - width: var(--icon-size); - border: 1px solid var(--header-border); - border-radius: var(--radius); - - & .icon { - top: 3px; - left: 3px; - width: calc(var(--icon-size) - 4px); - height: calc(var(--icon-size) - 4px); - position: absolute; - - &.open { - display: none; + & input[type=checkbox] { + position: absolute; + width: 100%; + height: 100%; + left: 0; + top: 0; + appearance: none; + cursor: pointer; } - } - & input[type=checkbox] { - position: absolute; - width: 100%; - height: 100%; - left: 0; - top: 0; - appearance: none; - cursor: pointer; - } + & .menu { + visibility: hidden; + height: 0; + opacity: 0; + width: 100%; + transition: all 0.2s ease-in-out; + position: fixed; + top: var(--header-height); + left: 0; + background-color: var(--header-background); + list-style: none; + padding: var(--unit-2); + } - & .menu { - visibility: hidden; - height: 0; - opacity: 0; - width: 100%; - transition: all 0.2s ease-in-out; - position: fixed; - top: var(--header-height); - left: 0; - background-color: var(--header-background); - list-style: none; - padding: var(--unit-2); - } + & input:checked + .menu { + visibility: visible; + opacity: 1; + height: calc(100vh - var(--header-height)); + } - & input:checked + .menu { - visibility: visible; - opacity: 1; - height: calc(100vh - var(--header-height)); - } + &:has(input:checked) { + .icon.open { + display: block; + } - &:has(input:checked) { - .icon.open { - display: block; + .icon.closed { + display: none; + } } + } - .icon.closed { - display: none; - } + & img { + margin: 0 var(--unit-4); + border-radius: var(--radius); + height: calc(var(--icon-size) - 2px); } - } - & img { - margin: 0 var(--unit-4); - border-radius: var(--radius); - height: calc(var(--icon-size) - 2px); + & strong { + line-height: var(--icon-size); + font-size: var(--unit-4); + display: block; + } } - & strong { - line-height: var(--icon-size); - font-size: var(--unit-4); - display: block; + & .end { + display: flex; + align-items: center; + + & a { + display: none; + } + + & > .themeToggle, & > .search { + cursor: pointer; + height: var(--icon-size); + align-items: center; + margin: 0 var(--unit); + } + + & > .search { + display: flex; + } } } @@ -247,6 +278,20 @@ main { border-bottom: 1px solid var(--header-border); grid-row: 1; grid-column: span 2; + + & .end { + > a { + display: flex; + align-items: center; + text-decoration: none; + color: var(--text-color); + margin: 0 var(--unit); + + &:hover { + color: var(--link-hover); + } + } + } } aside, main { @@ -313,8 +358,7 @@ h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { } h1, h2, h3, h4, h5, h6 { - margin-top: 0; - margin-bottom: var(--unit-3); + margin: var(--unit-3) 0; } h1 { @@ -608,7 +652,6 @@ table.pre td iconify-icon { } } - /* tooltips */ div.fsdocs-tip { z-index: 1000; @@ -728,7 +771,6 @@ span[onmouseout] { .fsdocs-source-link img.normal { filter: invert(1); } -; } /* dark theme */ @@ -740,6 +782,7 @@ span[onmouseout] { --text-hover: #FFF; --code-background: #3e3e42; --code-color: #f5f5f6; + --header-background: #0c1318; --header-border: #9b9b9b; --doc-tip-background: #2e293a; --link-color: #c5eff7; @@ -775,32 +818,3 @@ span[onmouseout] { --code-fsioutput-color: #808080; --code-tooltip-color: #d1d1d1; } - -/* theme toggling */ - -.themeToggle.dark { - display: block; -} - -.themeToggle.light { - display: none; -} - -[data-theme=dark] { - .themeToggle.light { - display: block; - } - - .themeToggle.dark { - display: none; - } -} - -.themeToggle { - cursor: pointer; - color: var(--text-color); - - &:hover { - color: var(--text-hover); - } -} \ No newline at end of file diff --git a/docs/content/fsdocs-theme-toggle.js b/docs/content/fsdocs-theme-toggle.js new file mode 100644 index 000000000..eabc698c2 --- /dev/null +++ b/docs/content/fsdocs-theme-toggle.js @@ -0,0 +1,54 @@ +import {LitElement, html, css} from 'https://cdn.jsdelivr.net/gh/lit/dist@3/core/lit-core.min.js'; + +const prefersDark = window.matchMedia("@media (prefers-color-scheme: dark)").matches; +let currentTheme = localStorage.getItem('theme') ?? (prefersDark ? 'dark' : 'light'); +if (currentTheme === 'dark') { + window.document.documentElement.setAttribute("data-theme", 'dark'); +} + +export class ThemeToggle extends LitElement { + static properties = { + _theme: {state: true, type: String}, + }; + + constructor() { + super(); + this._theme = currentTheme; + } + + static styles = css` + div { + height: 30px; + width: 30px; + cursor: pointer; + } + + .light { + background: url('https://api.iconify.design/basil/moon-solid.svg') no-repeat center center / contain; + } + + .dark { + background: url('https://api.iconify.design/basil/sun-solid.svg?color=white') no-repeat center center / contain; + } + `; + + changeTheme() { + this._theme = this._theme === 'light' ? 'dark' : 'light'; + localStorage.setItem('theme', this._theme); + window.document.documentElement.setAttribute("data-theme", this._theme); + } + + render() { + return html` +
+ `; + } +} + +customElements.define('fsdocs-theme-toggle', ThemeToggle); + +/* + + + + */ \ No newline at end of file From 020c3d7913a6e2a9470ead421a5280347822de51 Mon Sep 17 00:00:00 2001 From: nojaf Date: Mon, 16 Oct 2023 11:07:55 +0200 Subject: [PATCH 05/71] Watch default template folder as well. --- src/fsdocs-tool/BuildCommand.fs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs index 7ad603789..d673cb2b3 100644 --- a/src/fsdocs-tool/BuildCommand.fs +++ b/src/fsdocs-tool/BuildCommand.fs @@ -1773,10 +1773,12 @@ type CoreBuildOptions(watch) = if watch then let docsWatchers = - if Directory.Exists(this.input) then - [ new FileSystemWatcher(this.input) ] - else - [] + [ if Directory.Exists(this.input) then + yield new FileSystemWatcher(this.input) + match defaultTemplate with + | Some defaultTemplate -> + yield new FileSystemWatcher(Path.GetDirectoryName(defaultTemplate), IncludeSubdirectories = true) + | None -> () ] let templateWatchers = if Directory.Exists(this.input) then From 7509baa1ad34764e90d63257d7c53bf1091b36f4 Mon Sep 17 00:00:00 2001 From: nojaf Date: Mon, 16 Oct 2023 11:08:04 +0200 Subject: [PATCH 06/71] Tweak variables. --- docs/content/fsdocs-default.css | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index fca5c3b37..731aba409 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -22,7 +22,7 @@ --container-lg: 1024px; --container-xl: 1200px; --container-xxl: 1400px; - --aside-width: 200px; + --aside-width: 250px; --header-height: 60px; @@ -31,8 +31,9 @@ --background: #f5f5f6; --text-color: #020202; --text-hover: #282828; + --heading-color: #2e293a; --code-background: #ffffff; - --code-color: #1B6504; + --code-color: #1a4b0b; --header-background: #f9fbfc; --header-border: #e8ecf1; --menu-icon-hover: #F7F7F7; @@ -116,11 +117,11 @@ header { justify-content: space-between; position: sticky; top: 0; - + & .start { display: flex; align-items: center; - + & #menu-toggle { position: relative; height: var(--icon-size); @@ -197,11 +198,11 @@ header { & .end { display: flex; align-items: center; - + & a { display: none; } - + & > .themeToggle, & > .search { cursor: pointer; height: var(--icon-size); @@ -224,7 +225,7 @@ main { } #content { - padding: var(--unit-2) var(--unit-2); + padding: var(--unit-2) var(--unit-4); } /* menu items */ @@ -278,7 +279,7 @@ main { border-bottom: 1px solid var(--header-border); grid-row: 1; grid-column: span 2; - + & .end { > a { display: flex; @@ -353,7 +354,7 @@ main { /* Headings */ h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { - color: var(--primary); + color: var(--heading-color); text-decoration: none; } @@ -780,6 +781,7 @@ span[onmouseout] { --background: #32283c; --text-color: #F7F7F7; --text-hover: #FFF; + --heading-color: #F4F4F6; --code-background: #3e3e42; --code-color: #f5f5f6; --header-background: #0c1318; From 95f3a40792d985cee468600111ccf062f61024e0 Mon Sep 17 00:00:00 2001 From: nojaf Date: Tue, 17 Oct 2023 15:37:25 +0200 Subject: [PATCH 07/71] Separate spacing and font size chart. --- docs/content/fsdocs-default.css | 259 +++++++++++++++++++------------- 1 file changed, 153 insertions(+), 106 deletions(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 731aba409..50be6b794 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -2,20 +2,33 @@ --monospace-font: "Fira Code", monospace; --system-font: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif; - --unit: 0.25rem; - --unit-2: calc(2 * var(--unit)); - --unit-3: calc(3 * var(--unit)); - --unit-4: calc(4 * var(--unit)); - --unit-5: calc(5 * var(--unit)); - --unit-6: calc(6 * var(--unit)); - --unit-7: calc(7 * var(--unit)); - --unit-8: calc(8 * var(--unit)); - --unit-9: calc(9 * var(--unit)); - --unit-10: calc(10 * var(--unit)); - --unit-11: calc(11 * var(--unit)); - --unit-12: calc(12 * var(--unit)); + --spacing-one-quarter: 4px; + --spacing-half: 8px; + --spacing-three-quarter: 12px; + --spacing: 16px; + --spacing-one-and-a-half: 24px; + --spacing-twice: 32px; + --spacing-three-times: 48px; + --spacing-four-times: 64px; + --spacing-six-times: 96px; + --spacing-eight-times: 128px; + --spacing-twelve-times: 192px; + + --font-size-smallest: 12x; + --font-size-smaller: 14px; + --font-size: 16px; + --font-size-larger: 18px; + --font-size-largest: 20px; + --font-size-heading-6: 24px; + --font-size-heading-5: 30px; + --font-size-heading-4: 36px; + --font-size-heading-3: 48px; + --font-size-heading-2: 60px; + --font-size-heading-1: 72px; + + --line-height: 1.5; + --heading-line-height: 1.25; --radius: 6px; - --icon-size: 30px; --container-sm: 768px; --container-md: 960px; @@ -23,7 +36,6 @@ --container-xl: 1200px; --container-xxl: 1400px; --aside-width: 250px; - --header-height: 60px; /* light theme */ @@ -38,12 +50,15 @@ --header-border: #e8ecf1; --menu-icon-hover: #F7F7F7; --menu-icon-hover-background: #bdc3c7; + --menu-item-hover-background: #eff0f1; --doc-tip-background: #F7F7F7; --link-color: #4871f7; --link-hover: #91aafa; --search-background: rgb(229, 231, 235); --nav-category: rgb(156, 163, 175); + --header-brand-text-transform: none; + --code-strings-color: #0093A1; --code-printf-color: #6B2FBA; --code-escaped-color: #EA8675; @@ -106,11 +121,12 @@ body { font-family: var(--system-font); background-color: var(--background); color: var(--text-color); + line-height: var(--line-height); } header { background-color: var(--header-background); - padding: var(--unit-2); + padding: var(--spacing); height: var(--header-height); display: flex; align-items: center; @@ -124,16 +140,16 @@ header { & #menu-toggle { position: relative; - height: var(--icon-size); - width: var(--icon-size); + height: var(--spacing-twice); + width: var(--spacing-twice); border: 1px solid var(--header-border); border-radius: var(--radius); & .icon { - top: 3px; - left: 3px; - width: calc(var(--icon-size) - 4px); - height: calc(var(--icon-size) - 4px); + top: 4px; + left: 4px; + width: calc(var(--spacing-twice) - 4px); + height: calc(var(--spacing-twice) - 4px); position: absolute; &.open { @@ -162,7 +178,7 @@ header { left: 0; background-color: var(--header-background); list-style: none; - padding: var(--unit-2); + padding: var(--spacing); } & input:checked + .menu { @@ -183,15 +199,16 @@ header { } & img { - margin: 0 var(--unit-4); + margin: 0 var(--spacing-three-quarter); border-radius: var(--radius); - height: calc(var(--icon-size) - 2px); + height: calc(var(--spacing-twice) - 2px); } & strong { - line-height: var(--icon-size); - font-size: var(--unit-4); + line-height: var(--spacing-twice); + font-size: var(--font-size); display: block; + text-transform: var(--header-brand-text-transform); } } @@ -205,9 +222,9 @@ header { & > .themeToggle, & > .search { cursor: pointer; - height: var(--icon-size); + height: var(--spacing-twice); align-items: center; - margin: 0 var(--unit); + margin: 0 var(--spacing-half); } & > .search { @@ -225,7 +242,11 @@ main { } #content { - padding: var(--unit-2) var(--unit-4); + padding: var(--spacing); + + > *:first-child { + margin-top: 0; + } } /* menu items */ @@ -238,9 +259,9 @@ main { } .nav-header { - margin-top: var(--unit-3); + margin-top: var(--spacing-one-and-a-half); text-transform: uppercase; - font-size: var(--unit-3); + font-size: var(--font-size-largest); } .nav-header:first-child { @@ -248,14 +269,18 @@ main { } .nav-item { - padding-left: var(--unit-3); - padding-top: var(--unit); border-left: 1px solid var(--header-border); & a { color: var(--text-color); text-decoration: none; - font-size: var(--unit-3); + font-size: var(--font-size); + padding: var(--spacing-half); + display: inline-block; + + &:hover { + background-color: var(--menu-item-hover-background); + } } &:hover { @@ -286,7 +311,6 @@ main { align-items: center; text-decoration: none; color: var(--text-color); - margin: 0 var(--unit); &:hover { color: var(--link-hover); @@ -301,7 +325,7 @@ main { aside { display: block; - padding: var(--unit-2) var(--unit-6); + padding: var(--spacing) var(--spacing-twice); background-color: var(--header-background); width: var(--aside-width); border-right: 1px solid var(--header-border); @@ -316,39 +340,39 @@ main { } #content { - padding-left: var(--unit-4); - padding-right: var(--unit-4); + padding-left: var(--spacing); + padding-right: var(--spacing); } } @media screen and (min-width: 768px) { #content { - max-width: calc(100vw - var(--aside-width) - var(--unit-4)); + max-width: calc(100vw - var(--aside-width) - var(--spacing) - var(--spacing)); margin: 0 auto; } } @media screen and (min-width: 960px) { #content { - max-width: calc(var(--container-md) - var(--aside-width) - var(--unit-4)); + max-width: calc(var(--container-md) - var(--aside-width) - var(--spacing) - var(--spacing)); } } @media screen and (min-width: 1024px) { #content { - max-width: calc(var(--container-lg) - var(--aside-width) - var(--unit-4)); + max-width: calc(var(--container-lg) - var(--aside-width) - var(--spacing) - var(--spacing)); } } @media screen and (min-width: 1200px) { #content { - max-width: calc(var(--container-xl) - var(--aside-width) - var(--unit-4)); + max-width: calc(var(--container-xl) - var(--aside-width) - var(--spacing) - var(--spacing)); } } @media screen and (min-width: 1400px) { #content { - max-width: calc(var(--container-xxl) - var(--aside-width) - var(--unit-4)); + max-width: calc(var(--container-xxl) - var(--aside-width) - var(--spacing) - var(--spacing)); } } @@ -358,32 +382,72 @@ h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { text-decoration: none; } -h1, h2, h3, h4, h5, h6 { - margin: var(--unit-3) 0; -} - h1 { - font-size: var(--unit-8); + font-size: var(--font-size-heading-5); + line-height: var(--heading-line-height); + margin-bottom: var(--spacing); + margin-top: var(--spacing-one-quarter); } h2 { - font-size: var(--unit-6); + font-size: var(--font-size-heading-6); + line-height: var(--heading-line-height); + margin-top: var(--spacing); + margin-bottom: var(--spacing-three-quarter); } h3 { - font-size: var(--unit-5); + font-size: var(--font-size-largest); + line-height: var(--heading-line-height); + margin-top: var(--spacing-three-quarter); + margin-bottom: var(--spacing-three-quarter); } h4 { - font-size: var(--unit-4); + font-size: var(--font-size-larger); + font-weight: bold; + margin-top: var(--spacing-three-quarter); + margin-bottom: var(--spacing-three-quarter); } h5 { - font-size: var(--unit-3); + font-size: var(--font-size-larger); + margin-top: var(--spacing-three-quarter); + margin-bottom: var(--spacing-three-quarter); } h6 { - font-size: var(--unit-2); + font-size: var(--font-size-larger); + margin-top: var(--spacing-three-quarter); + margin-bottom: var(--spacing-three-quarter); +} + +@media screen and (min-width: 768px) { + h1 { + font-size: var(--font-size-heading-3); + margin-bottom: var(--spacing-one-and-a-half); + line-height: var(--heading-line-height); + } + + h2 { + font-size: var(--font-size-heading-4); + margin-top: var(--spacing-twice); + margin-bottom: var(--spacing); + } + + h3 { + font-size: var(--font-size-heading-5); + margin-top: var(--spacing-one-and-a-half); + margin-bottom: var(--spacing-three-quarter); + } + + h4 { + font-size: var(--font-size-heading-6); + } + + h4, h5, h6 { + margin-top: var(--spacing); + } } /* Common items */ @@ -395,12 +459,20 @@ p { line-height: 1.8; } +ol, ul { + margin-bottom: var(--spacing); +} + ol li { - margin-bottom: var(--unit-2); + margin-bottom: var(--spacing-three-quarter); +} + +img { + max-width: 100%; } #content > table { - margin: var(--unit-2) 0; + margin: var(--spacing) 0; } /* Code snippets */ @@ -418,21 +490,21 @@ code, table.pre, pre { } table.pre, pre.fssnip.highlighted { - margin-bottom: var(--unit-3); + margin-bottom: var(--spacing-half); + margin-top: var(--spacing-half); } table.pre, pre.fssnip { - padding: var(--unit) var(--unit-2); + padding: var(--spacing-half); } p > code, li > code { - padding: var(--unit); - transform: translateY(var(--unit)); + padding: var(--spacing-one-quarter); } table.pre, code { overflow-x: auto; - max-width: calc(100vw - var(--unit-12)); + max-width: 100%; box-sizing: border-box; border-radius: var(--radius); } @@ -448,37 +520,7 @@ pre.fssnip > code { /* copy icons in the shell commands */ table.pre td iconify-icon { - margin-top: 4px; -} - -@media screen and (min-width: 768px) { - table, code { - max-width: var(--container-sm); - } -} - -@media screen and (min-width: 960px) { - table, code { - max-width: var(--container-md); - } -} - -@media screen and (min-width: 1024px) { - table, code { - max-width: var(--container-lg); - } -} - -@media screen and (min-width: 1200px) { - table, code { - max-width: var(--container-xl); - } -} - -@media screen and (min-width: 1400px) { - table, code { - max-width: var(--container-xxl); - } + margin-top: var(--spacing-one-quarter); } /* Code coloring */ @@ -486,8 +528,8 @@ table.pre td iconify-icon { .return-name, .param { font-weight: 900; - font-size: 0.85rem; - font-family: 'Roboto Mono', monospace; + font-size: var(--font-size-smaller); + font-family: var(--monospace-font); } .fssnip { @@ -660,7 +702,7 @@ div.fsdocs-tip { background-color: var(--doc-tip-background); border-radius: var(--radius); border: 1px solid var(--header-border); - padding: var(--unit-3); + padding: var(--spacing-three-quarter); font-family: var(--monospace-font); color: var(--code-color); @@ -674,17 +716,21 @@ span[onmouseout] { } /* API docs */ +#content > div > h2:first-child { + margin-top: 0; +} + .table { width: 100%; & thead tr td { font-weight: bold; - padding: var(--unit-3) 0; + padding: var(--spacing-one-and-a-half) 0; } & tbody td { border-top: 1px solid var(--header-border); - padding: var(--unit-2) 0; + padding: var(--spacing) 0; } .fsdocs-entity-xmldoc { @@ -695,22 +741,22 @@ span[onmouseout] { align-items: center; > p { - margin: 0 var(--unit-2) 0 0; + margin: 0 var(--spacing-one-and-a-half) 0 0; } } } .fsdocs-member-usage { display: block; - margin-right: var(--unit-2); + margin-right: var(--spacing); } .fsdocs-member-xmldoc { & details { - margin-left: var(--unit-2); + margin-left: var(--spacing); & .fsdocs-summary { - margin-left: var(--unit-2); + margin-left: var(--spacing); } } @@ -725,7 +771,7 @@ span[onmouseout] { &::after { content: '▶'; cursor: pointer; - margin-left: var(--unit-4); + margin-left: var(--spacing-one-and-a-half); } } @@ -734,7 +780,7 @@ span[onmouseout] { } .fsdocs-returns, .fsdocs-params { - margin-left: var(--unit-4); + margin-left: var(--spacing-one-and-a-half); } /* hide the browser mark and display one after the summary */ @@ -746,10 +792,11 @@ span[onmouseout] { } .fsdocs-source-link { - padding: 0 var(--unit); + padding: 0 var(--spacing-half); > img { - height: var(--icon-size); + height: var(--spacing-twice); + width: var(--spacing-twice); cursor: pointer; &.hover { @@ -778,10 +825,10 @@ span[onmouseout] { [data-theme=dark] { --primary: #81cfe0; - --background: #32283c; + --background: #171717; --text-color: #F7F7F7; --text-hover: #FFF; - --heading-color: #F4F4F6; + --heading-color: rgb(229, 231, 235); --code-background: #3e3e42; --code-color: #f5f5f6; --header-background: #0c1318; From 4787205c48fa76a18a10ff4cae465e45007a696a Mon Sep 17 00:00:00 2001 From: nojaf Date: Tue, 17 Oct 2023 15:37:38 +0200 Subject: [PATCH 08/71] Test theming story in Telplin. --- docs/_template.html | 3 ++- docs/content/fsdocs-theme.css | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 docs/content/fsdocs-theme.css diff --git a/docs/_template.html b/docs/_template.html index fd2e7681d..456d25fa6 100644 --- a/docs/_template.html +++ b/docs/_template.html @@ -12,6 +12,7 @@ + {{fsdocs-watch-script}} @@ -34,7 +35,7 @@ {{fsdocs-list-of-namespaces}} - Header menu logo + Header menu logo {{fsdocs-collection-name}}
diff --git a/docs/content/fsdocs-theme.css b/docs/content/fsdocs-theme.css new file mode 100644 index 000000000..cd0e6a975 --- /dev/null +++ b/docs/content/fsdocs-theme.css @@ -0,0 +1 @@ +/* Override any variables here */ \ No newline at end of file From 1bf6afeecb79e914557a71da838f050d21e03248 Mon Sep 17 00:00:00 2001 From: nojaf Date: Tue, 17 Oct 2023 15:50:25 +0200 Subject: [PATCH 09/71] Avoid double background coloring in code snippets. --- docs/content/fsdocs-default.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 50be6b794..3c82b0810 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -518,6 +518,11 @@ pre.fssnip > code { margin-bottom: initial; } +pre.fssnip.highlighted > code, table.pre .fssnip, table.pre .fssnip code { + background-color: transparent; +} + + /* copy icons in the shell commands */ table.pre td iconify-icon { margin-top: var(--spacing-one-quarter); From 8ccacc5c20740cf267a35341ba07b4c43e990aa3 Mon Sep 17 00:00:00 2001 From: nojaf Date: Tue, 17 Oct 2023 16:30:19 +0200 Subject: [PATCH 10/71] Move dark theme variable closer to light theme. --- docs/content/fsdocs-default.css | 94 +++++++++++++++++---------------- 1 file changed, 48 insertions(+), 46 deletions(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 3c82b0810..9edfc6811 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -89,6 +89,54 @@ --code-tooltip-color: #d1d1d1; } +/* dark theme */ + +[data-theme=dark] { + --primary: #81cfe0; + --background: rgb(20, 21, 26); + --text-color: #F7F7F7; + --text-hover: #FFF; + --heading-color: rgb(229, 231, 235); + --code-background: #3e3e42; + --code-color: #f5f5f6; + --header-background: #0c1318; + --header-border: #9b9b9b; + --menu-item-hover-background: #2c2624; + --doc-tip-background: #2e293a; + --link-color: #c5eff7; + --search-background: #020202; + --nav-category: rgb(207, 211, 215); + + --code-strings-color: #5adfec; + --code-printf-color: #6B2FBA; + --code-escaped-color: #EA8675; + --code-identifiers-color: #d1b3f5; + --code-module-color: #15e1e1; + --code-reference-color: #7a9cee; + --code-value-color: #66d73d; + --code-interface-color: #43AEC6; + --code-typearg-color: #43AEC6; + --code-disposable-color: #6dd6f1; + --code-property-color: #6acfe7; + --code-punctuation-color: #43AEC6; + --code-punctuation2-color: var(--text-color); + --code-function-color: #6B2FBA; + --code-function2-color: #da9d9d; + --code-activepattern-color: #4ec9b0; + --code-unioncase-color: #4ec9b0; + --code-enumeration-color: #8C6C41; + --code-keywords-color: #a7c2f8; + --code-comment-color: #dcd8d8; + --code-operators-color: #b4c6ee; + --code-numbers-color: #009999; + --code-linenumbers-color: #80b0b0; + --code-mutable-color: #1b6600; + --code-inactive-color: #808080; + --code-preprocessor-color: #af75c1; + --code-fsioutput-color: #808080; + --code-tooltip-color: #d1d1d1; +} + /* CSS Reset, source: https://www.joshwcomeau.com/css/custom-css-reset/ */ *, *::before, *::after { box-sizing: border-box; @@ -826,49 +874,3 @@ span[onmouseout] { } } -/* dark theme */ - -[data-theme=dark] { - --primary: #81cfe0; - --background: #171717; - --text-color: #F7F7F7; - --text-hover: #FFF; - --heading-color: rgb(229, 231, 235); - --code-background: #3e3e42; - --code-color: #f5f5f6; - --header-background: #0c1318; - --header-border: #9b9b9b; - --doc-tip-background: #2e293a; - --link-color: #c5eff7; - --search-background: #020202; - --nav-category: rgb(207, 211, 215); - - --code-strings-color: #5adfec; - --code-printf-color: #6B2FBA; - --code-escaped-color: #EA8675; - --code-identifiers-color: #d1b3f5; - --code-module-color: #15e1e1; - --code-reference-color: #7a9cee; - --code-value-color: #66d73d; - --code-interface-color: #43AEC6; - --code-typearg-color: #43AEC6; - --code-disposable-color: #6dd6f1; - --code-property-color: #6acfe7; - --code-punctuation-color: #43AEC6; - --code-punctuation2-color: var(--text-color); - --code-function-color: #6B2FBA; - --code-function2-color: #da9d9d; - --code-activepattern-color: #4ec9b0; - --code-unioncase-color: #4ec9b0; - --code-enumeration-color: #8C6C41; - --code-keywords-color: #a7c2f8; - --code-comment-color: #dcd8d8; - --code-operators-color: #b4c6ee; - --code-numbers-color: #009999; - --code-linenumbers-color: #80b0b0; - --code-mutable-color: #1b6600; - --code-inactive-color: #808080; - --code-preprocessor-color: #af75c1; - --code-fsioutput-color: #808080; - --code-tooltip-color: #d1d1d1; -} From 41d8074fba8c98b43e865dce253e83c29b51b048 Mon Sep 17 00:00:00 2001 From: nojaf Date: Tue, 17 Oct 2023 16:52:20 +0200 Subject: [PATCH 11/71] Custom scrollbar styling. --- docs/content/fsdocs-default.css | 37 ++++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 9edfc6811..6ce940c9a 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -56,6 +56,9 @@ --link-hover: #91aafa; --search-background: rgb(229, 231, 235); --nav-category: rgb(156, 163, 175); + --scrollbar-track-background: #424242; + --scrollbar-track-border: #4A4A4A; + --scrollbar-thumb-background: #686868; --header-brand-text-transform: none; @@ -106,7 +109,6 @@ --link-color: #c5eff7; --search-background: #020202; --nav-category: rgb(207, 211, 215); - --code-strings-color: #5adfec; --code-printf-color: #6B2FBA; --code-escaped-color: #EA8675; @@ -257,6 +259,7 @@ header { font-size: var(--font-size); display: block; text-transform: var(--header-brand-text-transform); + font-weight: 500; } } @@ -543,20 +546,13 @@ table.pre, pre.fssnip.highlighted { } table.pre, pre.fssnip { - padding: var(--spacing-half); + padding: var(--spacing-three-quarter); } p > code, li > code { padding: var(--spacing-one-quarter); } -table.pre, code { - overflow-x: auto; - max-width: 100%; - box-sizing: border-box; - border-radius: var(--radius); -} - table.pre, pre > code { display: block; } @@ -566,14 +562,31 @@ pre.fssnip > code { margin-bottom: initial; } +/* avoid problems with transparent background colors */ pre.fssnip.highlighted > code, table.pre .fssnip, table.pre .fssnip code { background-color: transparent; } +/* Custom scrollbar styling */ +main, table.pre, code { + overflow-x: auto; + max-width: 100%; + box-sizing: border-box; + border-radius: var(--radius); + + &::-webkit-scrollbar { + height: var(--spacing-three-quarter); + width: var(--spacing); + } -/* copy icons in the shell commands */ -table.pre td iconify-icon { - margin-top: var(--spacing-one-quarter); + &::-webkit-scrollbar-track { + background-color: var(--scrollbar-track-background); + border: 1px solid var(--scrollbar-track-border); + } + + &::-webkit-scrollbar-thumb { + background-color: var(--scrollbar-thumb-background); + } } /* Code coloring */ From be3205c28fa623442b6ab5b2f4da66e15c5badc1 Mon Sep 17 00:00:00 2001 From: nojaf Date: Wed, 18 Oct 2023 12:45:58 +0200 Subject: [PATCH 12/71] Rename spacing variables and increase margins slightly. --- docs/content/fsdocs-default.css | 194 +++++++++++++++----------------- 1 file changed, 92 insertions(+), 102 deletions(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 6ce940c9a..b631ebfb5 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -2,29 +2,29 @@ --monospace-font: "Fira Code", monospace; --system-font: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif; - --spacing-one-quarter: 4px; - --spacing-half: 8px; - --spacing-three-quarter: 12px; - --spacing: 16px; - --spacing-one-and-a-half: 24px; - --spacing-twice: 32px; - --spacing-three-times: 48px; - --spacing-four-times: 64px; - --spacing-six-times: 96px; - --spacing-eight-times: 128px; - --spacing-twelve-times: 192px; - - --font-size-smallest: 12x; - --font-size-smaller: 14px; - --font-size: 16px; - --font-size-larger: 18px; - --font-size-largest: 20px; - --font-size-heading-6: 24px; - --font-size-heading-5: 30px; - --font-size-heading-4: 36px; - --font-size-heading-3: 48px; - --font-size-heading-2: 60px; - --font-size-heading-1: 72px; + --spacing-50: 4px; + --spacing-100: 8px; + --spacing-200: 12px; + --spacing-300: 16px; + --spacing-400: 24px; + --spacing-500: 32px; + --spacing-600: 48px; + --spacing-700: 64px; + --spacing-800: 96px; + --spacing-900: 128px; + --spacing-950: 192px; + + --font-50: 12x; + --font-100: 14px; + --font-200: 16px; + --font-300: 18px; + --font-400: 20px; + --font-500: 24px; + --font-600: 30px; + --font-700: 36px; + --font-800: 48px; + --font-900: 60px; + --font-950: 72px; --line-height: 1.5; --heading-line-height: 1.25; @@ -176,7 +176,7 @@ body { header { background-color: var(--header-background); - padding: var(--spacing); + padding: var(--spacing-300); height: var(--header-height); display: flex; align-items: center; @@ -190,16 +190,16 @@ header { & #menu-toggle { position: relative; - height: var(--spacing-twice); - width: var(--spacing-twice); + height: var(--spacing-500); + width: var(--spacing-500); border: 1px solid var(--header-border); border-radius: var(--radius); & .icon { top: 4px; left: 4px; - width: calc(var(--spacing-twice) - 4px); - height: calc(var(--spacing-twice) - 4px); + width: calc(var(--spacing-500) - 4px); + height: calc(var(--spacing-500) - 4px); position: absolute; &.open { @@ -228,7 +228,7 @@ header { left: 0; background-color: var(--header-background); list-style: none; - padding: var(--spacing); + padding: var(--spacing-300); } & input:checked + .menu { @@ -249,14 +249,14 @@ header { } & img { - margin: 0 var(--spacing-three-quarter); + margin: 0 var(--spacing-200); border-radius: var(--radius); - height: calc(var(--spacing-twice) - 2px); + height: calc(var(--spacing-500) - 2px); } & strong { - line-height: var(--spacing-twice); - font-size: var(--font-size); + line-height: var(--spacing-500); + font-size: var(--font-200); display: block; text-transform: var(--header-brand-text-transform); font-weight: 500; @@ -273,9 +273,9 @@ header { & > .themeToggle, & > .search { cursor: pointer; - height: var(--spacing-twice); + height: var(--spacing-500); align-items: center; - margin: 0 var(--spacing-half); + margin: 0 var(--spacing-100); } & > .search { @@ -293,7 +293,7 @@ main { } #content { - padding: var(--spacing); + padding: var(--spacing-300); > *:first-child { margin-top: 0; @@ -310,9 +310,9 @@ main { } .nav-header { - margin-top: var(--spacing-one-and-a-half); + margin-top: var(--spacing-400); text-transform: uppercase; - font-size: var(--font-size-largest); + font-size: var(--font-400); } .nav-header:first-child { @@ -325,8 +325,8 @@ main { & a { color: var(--text-color); text-decoration: none; - font-size: var(--font-size); - padding: var(--spacing-half); + font-size: var(--font-200); + padding: var(--spacing-100); display: inline-block; &:hover { @@ -376,7 +376,7 @@ main { aside { display: block; - padding: var(--spacing) var(--spacing-twice); + padding: var(--spacing-300) var(--spacing-500); background-color: var(--header-background); width: var(--aside-width); border-right: 1px solid var(--header-border); @@ -391,39 +391,39 @@ main { } #content { - padding-left: var(--spacing); - padding-right: var(--spacing); + padding-left: var(--spacing-300); + padding-right: var(--spacing-300); } } @media screen and (min-width: 768px) { #content { - max-width: calc(100vw - var(--aside-width) - var(--spacing) - var(--spacing)); + max-width: calc(100vw - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); margin: 0 auto; } } @media screen and (min-width: 960px) { #content { - max-width: calc(var(--container-md) - var(--aside-width) - var(--spacing) - var(--spacing)); + max-width: calc(var(--container-md) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); } } @media screen and (min-width: 1024px) { #content { - max-width: calc(var(--container-lg) - var(--aside-width) - var(--spacing) - var(--spacing)); + max-width: calc(var(--container-lg) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); } } @media screen and (min-width: 1200px) { #content { - max-width: calc(var(--container-xl) - var(--aside-width) - var(--spacing) - var(--spacing)); + max-width: calc(var(--container-xl) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); } } @media screen and (min-width: 1400px) { #content { - max-width: calc(var(--container-xxl) - var(--aside-width) - var(--spacing) - var(--spacing)); + max-width: calc(var(--container-xxl) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); } } @@ -434,70 +434,61 @@ h1 a, h2 a, h3 a, h4 a, h5 a, h6 a { } h1 { - font-size: var(--font-size-heading-5); + font-size: var(--font-600); line-height: var(--heading-line-height); - margin-bottom: var(--spacing); - margin-top: var(--spacing-one-quarter); + margin-bottom: var(--spacing-300); + margin-top: var(--spacing-50); } h2 { - font-size: var(--font-size-heading-6); + font-size: var(--font-500); line-height: var(--heading-line-height); - margin-top: var(--spacing); - margin-bottom: var(--spacing-three-quarter); + margin-top: var(--spacing-300); + margin-bottom: var(--spacing-200); } h3 { - font-size: var(--font-size-largest); + font-size: var(--font-400); line-height: var(--heading-line-height); - margin-top: var(--spacing-three-quarter); - margin-bottom: var(--spacing-three-quarter); + margin-top: var(--spacing-200); + margin-bottom: var(--spacing-200); } h4 { - font-size: var(--font-size-larger); font-weight: bold; - margin-top: var(--spacing-three-quarter); - margin-bottom: var(--spacing-three-quarter); } -h5 { - font-size: var(--font-size-larger); - margin-top: var(--spacing-three-quarter); - margin-bottom: var(--spacing-three-quarter); -} - -h6 { - font-size: var(--font-size-larger); - margin-top: var(--spacing-three-quarter); - margin-bottom: var(--spacing-three-quarter); +h4, h5, h6 { + font-size: var(--font-300); + margin-top: var(--spacing-200); + margin-bottom: var(--spacing-200); } @media screen and (min-width: 768px) { h1 { - font-size: var(--font-size-heading-3); - margin-bottom: var(--spacing-one-and-a-half); + font-size: var(--font-800); + margin-bottom: var(--spacing-400); line-height: var(--heading-line-height); } h2 { - font-size: var(--font-size-heading-4); - margin-top: var(--spacing-twice); - margin-bottom: var(--spacing); + font-size: var(--font-700); + margin-top: var(--spacing-600); + margin-bottom: var(--spacing-400); } h3 { - font-size: var(--font-size-heading-5); - margin-top: var(--spacing-one-and-a-half); - margin-bottom: var(--spacing-three-quarter); + font-size: var(--font-600); + margin-top: var(--spacing-500); + margin-bottom: var(--spacing-200); } h4 { - font-size: var(--font-size-heading-6); + font-size: var(--font-500); } h4, h5, h6 { - margin-top: var(--spacing); + margin-top: var(--spacing-300); } } @@ -511,11 +502,11 @@ p { } ol, ul { - margin-bottom: var(--spacing); + margin-bottom: var(--spacing-300); } ol li { - margin-bottom: var(--spacing-three-quarter); + margin-bottom: var(--spacing-200); } img { @@ -523,7 +514,7 @@ img { } #content > table { - margin: var(--spacing) 0; + margin: var(--spacing-300) 0; } /* Code snippets */ @@ -541,16 +532,15 @@ code, table.pre, pre { } table.pre, pre.fssnip.highlighted { - margin-bottom: var(--spacing-half); - margin-top: var(--spacing-half); + margin: var(--spacing-200) 0; } table.pre, pre.fssnip { - padding: var(--spacing-three-quarter); + padding: var(--spacing-200); } p > code, li > code { - padding: var(--spacing-one-quarter); + padding: var(--spacing-50); } table.pre, pre > code { @@ -575,8 +565,8 @@ main, table.pre, code { border-radius: var(--radius); &::-webkit-scrollbar { - height: var(--spacing-three-quarter); - width: var(--spacing); + height: var(--spacing-200); + width: var(--spacing-300); } &::-webkit-scrollbar-track { @@ -594,7 +584,7 @@ main, table.pre, code { .return-name, .param { font-weight: 900; - font-size: var(--font-size-smaller); + font-size: var(--font-100); font-family: var(--monospace-font); } @@ -768,7 +758,7 @@ div.fsdocs-tip { background-color: var(--doc-tip-background); border-radius: var(--radius); border: 1px solid var(--header-border); - padding: var(--spacing-three-quarter); + padding: var(--spacing-200); font-family: var(--monospace-font); color: var(--code-color); @@ -791,12 +781,12 @@ span[onmouseout] { & thead tr td { font-weight: bold; - padding: var(--spacing-one-and-a-half) 0; + padding: var(--spacing-400) 0; } & tbody td { border-top: 1px solid var(--header-border); - padding: var(--spacing) 0; + padding: var(--spacing-300) 0; } .fsdocs-entity-xmldoc { @@ -807,22 +797,22 @@ span[onmouseout] { align-items: center; > p { - margin: 0 var(--spacing-one-and-a-half) 0 0; + margin: 0 var(--spacing-400) 0 0; } } } .fsdocs-member-usage { display: block; - margin-right: var(--spacing); + margin-right: var(--spacing-300); } .fsdocs-member-xmldoc { & details { - margin-left: var(--spacing); + margin-left: var(--spacing-300); & .fsdocs-summary { - margin-left: var(--spacing); + margin-left: var(--spacing-300); } } @@ -837,7 +827,7 @@ span[onmouseout] { &::after { content: '▶'; cursor: pointer; - margin-left: var(--spacing-one-and-a-half); + margin-left: var(--spacing-400); } } @@ -846,7 +836,7 @@ span[onmouseout] { } .fsdocs-returns, .fsdocs-params { - margin-left: var(--spacing-one-and-a-half); + margin-left: var(--spacing-400); } /* hide the browser mark and display one after the summary */ @@ -858,11 +848,11 @@ span[onmouseout] { } .fsdocs-source-link { - padding: 0 var(--spacing-half); + padding: 0 var(--spacing-100); > img { - height: var(--spacing-twice); - width: var(--spacing-twice); + height: var(--spacing-500); + width: var(--spacing-500); cursor: pointer; &.hover { From 00b99b0b7d2123a808e60f012ca9589779bd3bcb Mon Sep 17 00:00:00 2001 From: nojaf Date: Wed, 18 Oct 2023 13:11:56 +0200 Subject: [PATCH 13/71] Restore deleted example files, replace FsDocsNavbarPosition with CSS solution. --- RELEASE_NOTES.md | 5 ++ docs/content/fsdocs-default.css | 20 ++--- docs/sidebyside/sideextensions.md | 38 +++++++++ docs/sidebyside/sidemarkdown.md | 70 +++++++++++++++++ docs/sidebyside/sidescript.fsx | 90 ++++++++++++++++++++++ docs/styling.md | 2 - docs/templates/leftside/styling.md | 32 ++++++++ src/FSharp.Formatting.Common/Templating.fs | 3 - src/fsdocs-tool/ProjectCracker.fs | 8 -- 9 files changed, 246 insertions(+), 22 deletions(-) create mode 100644 docs/sidebyside/sideextensions.md create mode 100644 docs/sidebyside/sidemarkdown.md create mode 100644 docs/sidebyside/sidescript.fsx create mode 100644 docs/templates/leftside/styling.md diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 64cd92009..c8063ad05 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,3 +1,8 @@ +## 20.0.0-alpha-001 + +### Removed +* `FsDocsNavbarPosition` is no longer respected. Use CSS variables instead. See [docs](https://fsprojects.github.io/FSharp.Formatting/templates/leftside/styling.html). + ## 19.1.1 * Fix code rendering on firefox. [#851](https://github.com/fsprojects/FSharp.Formatting/pull/851) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index b631ebfb5..38261fef5 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -37,6 +37,11 @@ --container-xxl: 1400px; --aside-width: 250px; --header-height: 60px; + --body-grid-template-columns: var(--aside-width) minmax(0, 1fr); + --aside-grid-row: 2; + --aside-grid-column: 1; + --main-grid-row: 2; + --main-grid-column: 2; /* light theme */ --primary: #1e8bc3; @@ -347,7 +352,7 @@ main { body { display: grid; grid-template-rows: var(--header-height) minmax(0, 1fr); - grid-template-columns:var(--aside-width) minmax(0, 1fr); + grid-template-columns:var(--body-grid-template-columns); gap: 0; } @@ -380,13 +385,13 @@ main { background-color: var(--header-background); width: var(--aside-width); border-right: 1px solid var(--header-border); - grid-row: 2; - grid-row-end: 3; + grid-row: var(--aside-grid-row); + grid-column: var(--aside-grid-column); } main { - grid-row: 2; - grid-column: 2; + grid-row: var(--main-grid-row); + grid-column: var(--main-grid-column); overflow-y: auto; } @@ -499,10 +504,7 @@ a { p { line-height: 1.8; -} - -ol, ul { - margin-bottom: var(--spacing-300); + margin-top: var(--spacing-200); } ol li { diff --git a/docs/sidebyside/sideextensions.md b/docs/sidebyside/sideextensions.md new file mode 100644 index 000000000..76d1630e3 --- /dev/null +++ b/docs/sidebyside/sideextensions.md @@ -0,0 +1,38 @@ +--- +title: Markdown LaTeX +category: Examples +categoryindex: 2 +index: 3 +--- +Example: Using the Markdown Extensions for LaTeX +=================== + +To use LaTex extension, you need add javascript +link to [MathJax](http://www.mathjax.org/) in +your template. + +To use inline LaTex, eclose LaTex code with `$`: +$ k_{n+1} = n^2 + k_n^2 - k_{n-1} $. Alternatively, +you can also use `$$`. + +To use block LaTex, start a new parapgraph, with +the first line marked as `$$$` (no close `$$$`): + +$$$ +A_{m,n} = + \begin{pmatrix} + a_{1,1} & a_{1,2} & \cdots & a_{1,n} \\ + a_{2,1} & a_{2,2} & \cdots & a_{2,n} \\ + \vdots & \vdots & \ddots & \vdots \\ + a_{m,1} & a_{m,2} & \cdots & a_{m,n} + \end{pmatrix} + +Use LaTex escape rule: + +- Escape \$ in inline mode: $ \$ $, $ \$var $ +- Other escapes: $ \& \% \$ \# \_ \{ \} $ +- Using < or >: $ x > 1 $, $ y < 1 $, $ x >= 1 $, + $ y <= 1 $, $ x = 1 $ +- $

something

$ + + diff --git a/docs/sidebyside/sidemarkdown.md b/docs/sidebyside/sidemarkdown.md new file mode 100644 index 000000000..4a81cfb9f --- /dev/null +++ b/docs/sidebyside/sidemarkdown.md @@ -0,0 +1,70 @@ +--- +title: Markdown Content +category: Examples +categoryindex: 2 +index: 2 +--- +# Example: Using Markdown Content + +This file demonstrates how to write Markdown document with +embedded F# snippets that can be transformed into nice HTML +using the `literate.fsx` script from the [F# Formatting +package](http://fsprojects.github.io/FSharp.Formatting). + +In this case, the document itself is a valid Markdown and +you can use standard Markdown features to format the text: + + - Here is an example of unordered list and... + - Text formatting including **bold** and _emphasis_ + +For more information, see the [Markdown][md] reference. + + [md]: http://daringfireball.net/projects/markdown + + +## Writing F# code + +In standard Markdown, you can include code snippets by +writing a block indented by four spaces and the code +snippet will be turned into a `
` element. If you do 
+the same using Literate F# tool, the code is turned into
+a nicely formatted F# snippet:
+
+    /// The Hello World of functional languages!
+    let rec factorial x = 
+      if x = 0 then 1 
+      else x * (factorial (x - 1))
+
+    let f10 = factorial 10
+
+
+## Hiding code
+
+If you want to include some code in the source code, 
+but omit it from the output, you can use the `hide` 
+command. You can also use `module=...` to specify that 
+the snippet should be placed in a separate module 
+(e.g. to avoid duplicate definitions).
+
+    [hide, module=Hidden]
+    /// This is a hidden answer
+    let answer = 42
+
+The value will be deffined in the F# code that is 
+processed and so you can use it from other (visible) 
+code and get correct tool tips:
+
+    let answer = Hidden.answer
+
+## Including other snippets
+
+When writing literate programs as Markdown documents, 
+you can also include snippets in other languages. 
+These will not be colorized and processed as F# 
+code samples:
+
+    [lang=csharp]
+    Console.WriteLine("Hello world!");
+
+This snippet is turned into a `pre` element with the
+`lang` attribute set to `csharp`.
diff --git a/docs/sidebyside/sidescript.fsx b/docs/sidebyside/sidescript.fsx
new file mode 100644
index 000000000..846ceaabf
--- /dev/null
+++ b/docs/sidebyside/sidescript.fsx
@@ -0,0 +1,90 @@
+(**
+---
+title: Literate Script
+category: Examples
+categoryindex: 2
+index: 1
+---
+# Example: Using Literate Script Content
+
+This file demonstrates how to write literate F# script
+files (`*.fsx`) that can be transformed into nice HTML
+using the `literate.fsx` script from the [F# Formatting
+package](http://fsprojects.github.io/FSharp.Formatting).
+
+As you can see, a comment starting with double asterisk
+is treated as part of the document and is transformed
+using Markdown, which means that you can use:
+
+ - Unordered or ordered lists
+ - Text formatting including **bold** and _emphasis_
+
+And numerous other [Markdown][md] features.
+
+ [md]: http://daringfireball.net/projects/markdown
+
+## Writing F# code
+
+Code that is not inside comment will be formatted as
+a sample snippet.
+*)
+
+/// The Hello World of functional languages!
+let rec factorial x =
+    if x = 0 then 1 else x * (factorial (x - 1))
+
+let f10 = factorial 10
+
+(**
+Hiding code
+-----------
+
+If you want to include some code in the source code,
+but omit it from the output, you can use the `hide`
+command.
+*)
+
+(*** hide ***)
+/// This is a hidden answer
+let hidden = 42
+
+(**
+The value will be defined in the F# code and so you
+can use it from other (visible) code and get correct
+tool tips:
+*)
+
+let answer = hidden
+
+(**
+## Moving code around
+
+Sometimes, it is useful to first explain some code that
+has to be located at the end of the snippet (perhaps
+because it uses some definitions discussed in the middle).
+This can be done using `include` and `define` commands.
+
+The following snippet gets correct tool tips, even though
+it uses `laterFunction`:
+*)
+
+(*** include:later-bit ***)
+
+(**
+Then we can explain how `laterFunction` is defined:
+*)
+
+let laterFunction () = "Not very difficult, is it?"
+
+(**
+This example covers pretty much all features that are
+currently implemented in `literate.fsx`, but feel free
+to [fork the project on GitHub][fs] and add more
+features or report bugs!
+
+  [fs]: https://github.com/fsprojects/FSharp.Formatting
+
+*)
+
+(*** define:later-bit ***)
+let sample = laterFunction () |> printfn "Got: %s"
diff --git a/docs/styling.md b/docs/styling.md
index b85e3a6d5..566969cb0 100644
--- a/docs/styling.md
+++ b/docs/styling.md
@@ -46,7 +46,6 @@ The following [content parameters](content.html) are particularly related to vis
 | `fsdocs-license-link`         | ``  | 
 | `fsdocs-logo-src`             | `` |  
 | `fsdocs-logo-link`            | ``   |                
-| `fsdocs-navbar-position`      | `` (`fixed-left` or `fixed-right`)     |  
 | `fsdocs-release-notes-link`   | `` else `/blob/master/RELEASE_NOTES.md`  | 
 | `fsdocs-repository-link`      | ``                                             | 
 | `fsdocs-theme`                | ``, must currently be `default`    | 
@@ -62,7 +61,6 @@ For example:
     https://fsharp.org
     https://github.com/foo/bar/blob/master/License.txt
     https://github.com/foo/bar/blob/master/release-notes.md
-    fixed-left
     true
     default
 ```
diff --git a/docs/templates/leftside/styling.md b/docs/templates/leftside/styling.md
new file mode 100644
index 000000000..52a8cd21b
--- /dev/null
+++ b/docs/templates/leftside/styling.md
@@ -0,0 +1,32 @@
+---
+# Example: Right-Side NavBar
+category: Examples
+categoryindex: 2
+index: 4
+---
+
+# Example: Styling for Right-Side Navigation Bar
+
+
+
+The sidebar can be moved to the right by overwriting the following CSS variables in your `fsdocs-theme.css` file:
+
+```css
+:root {
+    --body-grid-template-columns:  minmax(0, 1fr) var(--aside-width);
+    --aside-grid-column: 2;
+    --main-grid-column: 1;
+}
+```
+
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?
+
diff --git a/src/FSharp.Formatting.Common/Templating.fs b/src/FSharp.Formatting.Common/Templating.fs
index 51745fa86..1ffd22faf 100644
--- a/src/FSharp.Formatting.Common/Templating.fs
+++ b/src/FSharp.Formatting.Common/Templating.fs
@@ -104,9 +104,6 @@ module ParamKeys =
     /// A parameter key known to FSharp.Formatting
     let ``fsdocs-logo-src`` = ParamKey "fsdocs-logo-src"
 
-    /// A parameter key known to FSharp.Formatting
-    let ``fsdocs-navbar-position`` = ParamKey "fsdocs-navbar-position"
-
     /// A parameter key known to FSharp.Formatting
     let ``fsdocs-package-license-expression`` = ParamKey "fsdocs-package-license-expression"
 
diff --git a/src/fsdocs-tool/ProjectCracker.fs b/src/fsdocs-tool/ProjectCracker.fs
index d179f3184..1d01fb647 100644
--- a/src/fsdocs-tool/ProjectCracker.fs
+++ b/src/fsdocs-tool/ProjectCracker.fs
@@ -200,7 +200,6 @@ module Crack =
           FsDocsLicenseLink: string option
           FsDocsLogoLink: string option
           FsDocsLogoSource: string option
-          FsDocsNavbarPosition: string option
           FsDocsReleaseNotesLink: string option
           FsDocsSourceFolder: string option
           FsDocsSourceRepository: string option
@@ -229,7 +228,6 @@ module Crack =
               "UsesMarkdownComments"
               "FsDocsCollectionNameLink"
               "FsDocsLogoSource"
-              "FsDocsNavbarPosition"
               "FsDocsTheme"
               "FsDocsLogoLink"
               "FsDocsLicenseLink"
@@ -319,7 +317,6 @@ module Crack =
                   FsDocsReleaseNotesLink = msbuildPropString "FsDocsReleaseNotesLink"
                   FsDocsLogoLink = msbuildPropString "FsDocsLogoLink"
                   FsDocsLogoSource = msbuildPropString "FsDocsLogoSource"
-                  FsDocsNavbarPosition = msbuildPropString "FsDocsNavbarPosition"
                   FsDocsTheme = msbuildPropString "FsDocsTheme"
                   FsDocsWarnOnMissingDocs = msbuildPropBool "FsDocsWarnOnMissingDocs" |> Option.defaultValue false
                   UsesMarkdownComments = msbuildPropBool "UsesMarkdownComments" |> Option.defaultValue false
@@ -520,7 +517,6 @@ module Crack =
               FsDocsLogoSource = projectInfos |> List.tryPick (fun info -> info.FsDocsLogoSource)
               FsDocsSourceFolder = projectInfos |> List.tryPick (fun info -> info.FsDocsSourceFolder)
               FsDocsSourceRepository = projectInfos |> List.tryPick (fun info -> info.FsDocsSourceRepository)
-              FsDocsNavbarPosition = projectInfos |> List.tryPick (fun info -> info.FsDocsNavbarPosition)
               FsDocsTheme = projectInfos |> List.tryPick (fun info -> info.FsDocsTheme)
               FsDocsWarnOnMissingDocs = false
               PackageProjectUrl =
@@ -564,10 +560,6 @@ module Crack =
                       None
                       ParamKeys.``fsdocs-logo-src``
                       (Some(defaultArg info.FsDocsLogoSource (sprintf "%simg/logo.png" root)))
-                  param
-                      None
-                      ParamKeys.``fsdocs-navbar-position``
-                      (Some(defaultArg info.FsDocsNavbarPosition "fixed-left"))
                   param None ParamKeys.``fsdocs-theme`` (Some(defaultArg info.FsDocsTheme "default"))
                   param
                       None

From e7dbe144266d401b8fa1d9db7be1cf7a76944d5f Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 23 Oct 2023 13:46:14 +0200
Subject: [PATCH 14/71] Add some shadows.

---
 docs/content/fsdocs-default.css | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css
index 38261fef5..3a577f6ed 100644
--- a/docs/content/fsdocs-default.css
+++ b/docs/content/fsdocs-default.css
@@ -64,6 +64,7 @@
     --scrollbar-track-background: #424242;
     --scrollbar-track-border: #4A4A4A;
     --scrollbar-thumb-background: #686868;
+    --shadow: hsla(0,0%,0%,.1);
 
     --header-brand-text-transform: none;
 
@@ -188,6 +189,7 @@ header {
     justify-content: space-between;
     position: sticky;
     top: 0;
+    box-shadow: 0 1px 1px var(--shadow);
 
     & .start {
         display: flex;
@@ -199,6 +201,7 @@ header {
             width: var(--spacing-500);
             border: 1px solid var(--header-border);
             border-radius: var(--radius);
+            box-shadow: 0 1px 1px var(--shadow);
 
             & .icon {
                 top: 4px;
@@ -315,9 +318,10 @@ main {
 }
 
 .nav-header {
-    margin-top: var(--spacing-400);
+    margin-top: var(--spacing-300);
     text-transform: uppercase;
-    font-size: var(--font-400);
+    font-size: var(--font-200);
+    font-weight: 500;
 }
 
 .nav-header:first-child {
@@ -360,6 +364,7 @@ main {
         border-bottom: 1px solid var(--header-border);
         grid-row: 1;
         grid-column: span 2;
+        box-shadow: none;
 
         & .end {
             > a {
@@ -393,6 +398,8 @@ main {
         grid-row: var(--main-grid-row);
         grid-column: var(--main-grid-column);
         overflow-y: auto;
+        box-shadow: inset 1px 1px var(--shadow);
+        border-radius: 0;
     }
 
     #content {
@@ -563,8 +570,6 @@ pre.fssnip.highlighted > code, table.pre .fssnip, table.pre .fssnip code {
 main, table.pre, code {
     overflow-x: auto;
     max-width: 100%;
-    box-sizing: border-box;
-    border-radius: var(--radius);
 
     &::-webkit-scrollbar {
         height: var(--spacing-200);
@@ -581,6 +586,10 @@ main, table.pre, code {
     }
 }
 
+table.pre, code {
+    border-radius: var(--radius);
+}
+
 /* Code coloring */
 .param-name,
 .return-name,

From 1f333569d28e571591d2d3e37d752ff8eae4b4ba Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 23 Oct 2023 13:51:38 +0200
Subject: [PATCH 15/71] Use lighter shadow for main.

---
 docs/content/fsdocs-default.css | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css
index 3a577f6ed..7718e15e2 100644
--- a/docs/content/fsdocs-default.css
+++ b/docs/content/fsdocs-default.css
@@ -64,7 +64,8 @@
     --scrollbar-track-background: #424242;
     --scrollbar-track-border: #4A4A4A;
     --scrollbar-thumb-background: #686868;
-    --shadow: hsla(0,0%,0%,.1);
+    --shadow-color: hsla(0,0%,0%,.1);
+    --main-shadow-color: hsla(0,0%,0%,.025);
 
     --header-brand-text-transform: none;
 
@@ -189,7 +190,7 @@ header {
     justify-content: space-between;
     position: sticky;
     top: 0;
-    box-shadow: 0 1px 1px var(--shadow);
+    box-shadow: 0 1px 1px var(--shadow-color);
 
     & .start {
         display: flex;
@@ -201,7 +202,7 @@ header {
             width: var(--spacing-500);
             border: 1px solid var(--header-border);
             border-radius: var(--radius);
-            box-shadow: 0 1px 1px var(--shadow);
+            box-shadow: 0 1px 1px var(--shadow-color);
 
             & .icon {
                 top: 4px;
@@ -398,7 +399,7 @@ main {
         grid-row: var(--main-grid-row);
         grid-column: var(--main-grid-column);
         overflow-y: auto;
-        box-shadow: inset 1px 1px var(--shadow);
+        box-shadow: inset 1px 1px var(--main-shadow-color);
         border-radius: 0;
     }
 

From c36000cfbba9923d924802a0a64e63dbf241ee3b Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 23 Oct 2023 15:12:54 +0200
Subject: [PATCH 16/71] Allow additional html injection from a _head.html and
 _body.html file.

---
 docs/_template.html                        |  2 ++
 docs/content.fsx                           |  2 ++
 docs/content/fsdocs-default.css            |  1 +
 docs/content/fsdocs-theme-toggle.js        |  6 -----
 docs/styling.md                            |  6 +++++
 src/FSharp.Formatting.Common/Templating.fs |  6 +++++
 src/fsdocs-tool/BuildCommand.fs            | 30 ++++++++++++++++++++--
 7 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/docs/_template.html b/docs/_template.html
index 456d25fa6..8c68dc987 100644
--- a/docs/_template.html
+++ b/docs/_template.html
@@ -13,6 +13,7 @@
     
     
     
+    {{fsdocs-head-extra}}
     {{fsdocs-watch-script}}
 
 
@@ -68,5 +69,6 @@
 
 
 
+{{fsdocs-body-extra}}
 
 
\ No newline at end of file
diff --git a/docs/content.fsx b/docs/content.fsx
index 1275e3a4c..94c916eda 100644
--- a/docs/content.fsx
+++ b/docs/content.fsx
@@ -148,6 +148,8 @@ See [Styling](styling.html) for information about template parameters and stylin
 | `fsdocs-watch-script`         | The websocket script used in watch mode to trigger hot reload |
 | `fsdocs-previous-page-link`   | A relative link to the previous page based on the frontmatter index data |
 | `fsdocs-next-page-link`       | A relative link to the next page based on the frontmatter index data |
+| `fsdocs-head-extra`           | Additional html content loaded from the `_head.html` file if present in the `--input` folder |
+| `fsdocs-body-extra`           | Additional html content loaded from the `_body.html` file if present in the `--input` folder |
 
 The following substitutions are extracted from your project files and may or may not be used by the default
 template:
diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css
index 7718e15e2..c595cc9b1 100644
--- a/docs/content/fsdocs-default.css
+++ b/docs/content/fsdocs-default.css
@@ -866,6 +866,7 @@ span[onmouseout] {
         height: var(--spacing-500);
         width: var(--spacing-500);
         cursor: pointer;
+        object-fit: contain;
 
         &.hover {
             display: none;
diff --git a/docs/content/fsdocs-theme-toggle.js b/docs/content/fsdocs-theme-toggle.js
index eabc698c2..d6e2dd17f 100644
--- a/docs/content/fsdocs-theme-toggle.js
+++ b/docs/content/fsdocs-theme-toggle.js
@@ -46,9 +46,3 @@ export class ThemeToggle extends LitElement {
 }
 
 customElements.define('fsdocs-theme-toggle', ThemeToggle);
-
-/*
-
-        
-        
- */
\ No newline at end of file
diff --git a/docs/styling.md b/docs/styling.md
index 566969cb0..247a531b7 100644
--- a/docs/styling.md
+++ b/docs/styling.md
@@ -138,6 +138,12 @@ Similarly, to customize the individual menu item list, use file `_menu-item_temp
 Do note that files need to be added prior running or won't be generated.
 In case you want to get a unique identifier for a header or menu item, you can use `{{fsdocs-menu-header-id}}` and `{{fsdocs-menu-item-id}}`, respectively.
 
+## Injecting additional html into the default template
+
+Occasionally, you may find the need to make small customizations to the default template, such as adding a Google Analytics snippet or including additional style or script tags. To address this scenario, you can create two files: `_head.html` and/or `_body.html`.
+
+The content within these files will serve as replacements for the `{{fsdocs-head-extra}}` and `{{fsdocs-body-extra}}` placeholders, which are utilized in the default template.
+
 ## Customizing by generating your own site using your own code
 
 The `FSharp.Formatting.ApiDocs` namespace includes a `GenerateModel` that captures
diff --git a/src/FSharp.Formatting.Common/Templating.fs b/src/FSharp.Formatting.Common/Templating.fs
index 1ffd22faf..94b860f84 100644
--- a/src/FSharp.Formatting.Common/Templating.fs
+++ b/src/FSharp.Formatting.Common/Templating.fs
@@ -179,6 +179,12 @@ module ParamKeys =
     /// A parameter key known to FSharp.Formatting, available when frontmatter is used correctly
     let ``fsdocs-next-page-link`` = ParamKey "fsdocs-next-page-link"
 
+    /// A parameter key known to FSharp.Formatting, available when `_head.html` exists in the input folder.
+    let ``fsdocs-head-extra`` = ParamKey "fsdocs-head-extra"
+
+    /// A parameter key known to FSharp.Formatting, available when `_head.html` exists in the input folder.
+    let ``fsdocs-body-extra`` = ParamKey "fsdocs-body-extra"
+
 module internal SimpleTemplating =
 
 #if NETSTANDARD2_0
diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs
index d673cb2b3..df86a6cf2 100644
--- a/src/fsdocs-tool/BuildCommand.fs
+++ b/src/fsdocs-tool/BuildCommand.fs
@@ -221,10 +221,16 @@ type internal DocContent
                               try
                                   let fi = FileInfo(t)
                                   let input = fi.Directory.Name
+                                  let headPath = Path.Combine(input, "_head.html")
+                                  let bodyPath = Path.Combine(input, "_body.html")
 
                                   [ yield File.GetLastWriteTime(t)
                                     if Menu.isTemplatingAvailable input then
-                                        yield! Menu.getLastWriteTimes input ]
+                                        yield! Menu.getLastWriteTimes input
+                                    if File.Exists headPath then
+                                        yield File.GetLastWriteTime headPath
+                                    if File.Exists bodyPath then
+                                        yield File.GetLastWriteTime bodyPath ]
                                   |> List.max
                               with _ ->
                                   DateTime.MaxValue
@@ -1676,6 +1682,22 @@ type CoreBuildOptions(watch) =
 
                 let navEntries = docContent.GetNavigationEntries(this.input, actualDocModels)
 
+                let headTemplateContent =
+                    let headTemplatePath = Path.Combine(this.input, "_head.html")
+
+                    if not (File.Exists headTemplatePath) then
+                        ""
+                    else
+                        File.ReadAllText headTemplatePath
+
+                let bodyTemplateContent =
+                    let bodyTemplatePath = Path.Combine(this.input, "_body.html")
+
+                    if not (File.Exists bodyTemplatePath) then
+                        ""
+                    else
+                        File.ReadAllText bodyTemplatePath
+
                 let results =
                     Map.ofList
                         [ for (thing, _action) in docModels do
@@ -1685,7 +1707,11 @@ type CoreBuildOptions(watch) =
 
                 latestDocContentResults <- results
                 latestDocContentSearchIndexEntries <- extrasForSearchIndex
-                latestDocContentGlobalParameters <- [ ParamKeys.``fsdocs-list-of-documents``, navEntries ]
+
+                latestDocContentGlobalParameters <-
+                    [ ParamKeys.``fsdocs-list-of-documents``, navEntries
+                      ParamKeys.``fsdocs-head-extra``, headTemplateContent
+                      ParamKeys.``fsdocs-body-extra``, bodyTemplateContent ]
 
                 latestDocContentPhase2 <-
                     (fun globals ->

From 6084ba07974e0286fcc1fa06ce80073ac03613f6 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 23 Oct 2023 15:50:03 +0200
Subject: [PATCH 17/71] Fix MathJax example.

---
 docs/content/fsdocs-default.css   | 12 +++++++-----
 docs/sidebyside/sideextensions.md |  8 +++++++-
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css
index c595cc9b1..c536c19c0 100644
--- a/docs/content/fsdocs-default.css
+++ b/docs/content/fsdocs-default.css
@@ -64,8 +64,8 @@
     --scrollbar-track-background: #424242;
     --scrollbar-track-border: #4A4A4A;
     --scrollbar-thumb-background: #686868;
-    --shadow-color: hsla(0,0%,0%,.1);
-    --main-shadow-color: hsla(0,0%,0%,.025);
+    --shadow-color: hsla(0, 0%, 0%, .1);
+    --main-shadow-color: hsla(0, 0%, 0%, .025);
 
     --header-brand-text-transform: none;
 
@@ -543,10 +543,12 @@ code, table.pre, pre {
 
 table.pre, pre.fssnip.highlighted {
     margin: var(--spacing-200) 0;
+    padding: var(--spacing-200);
 }
 
-table.pre, pre.fssnip {
-    padding: var(--spacing-200);
+table.pre .snippet pre.fssnip {
+    padding: 0;
+    margin: 0;
 }
 
 p > code, li > code {
@@ -587,7 +589,7 @@ main, table.pre, code {
     }
 }
 
-table.pre, code {
+table.pre, code, pre.fssnip {
     border-radius: var(--radius);
 }
 
diff --git a/docs/sidebyside/sideextensions.md b/docs/sidebyside/sideextensions.md
index 76d1630e3..00fc31161 100644
--- a/docs/sidebyside/sideextensions.md
+++ b/docs/sidebyside/sideextensions.md
@@ -7,9 +7,15 @@ index: 3
 Example: Using the Markdown Extensions for LaTeX
 ===================
 
+
+
 To use LaTex extension, you need add javascript
 link to [MathJax](http://www.mathjax.org/) in
-your template.
+your template or inside a `_head.html` file.
+
+```html
+
+```
 
 To use inline LaTex, eclose LaTex code with `$`:
 $ k_{n+1} = n^2 + k_n^2 - k_{n-1} $. Alternatively,

From a8b589570735b412ce40c12d66c187afbd63b704 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Mon, 30 Oct 2023 17:04:40 +0100
Subject: [PATCH 18/71] Minor tweaks + {{fsdocs-favicon-src}}

---
 docs/_template.html                        |  4 ++--
 docs/content/fsdocs-default.css            | 15 ++++++++++-----
 src/FSharp.Formatting.Common/Templating.fs |  3 +++
 src/fsdocs-tool/ProjectCracker.fs          |  9 +++++++--
 4 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/docs/_template.html b/docs/_template.html
index 8c68dc987..dc6bda96e 100644
--- a/docs/_template.html
+++ b/docs/_template.html
@@ -10,7 +10,7 @@
     
     
     
-    
+    
     
     
     {{fsdocs-head-extra}}
@@ -36,7 +36,7 @@
                 {{fsdocs-list-of-namespaces}}
- Header menu logo + Header menu logo {{fsdocs-collection-name}}
diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index c536c19c0..2626707b3 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -155,6 +155,10 @@ margin: 0; } +html { + overflow-y: hidden; +} + body { line-height: 1.5; -webkit-font-smoothing: antialiased; @@ -382,7 +386,7 @@ main { } aside, main { - min-height: calc(100vh - var(--header-height)); + height: calc(100vh - var(--header-height)); } aside { @@ -393,6 +397,7 @@ main { border-right: 1px solid var(--header-border); grid-row: var(--aside-grid-row); grid-column: var(--aside-grid-column); + overflow-y: auto; } main { @@ -486,7 +491,7 @@ h4, h5, h6 { h2 { font-size: var(--font-700); - margin-top: var(--spacing-600); + margin-top: var(--spacing-500); margin-bottom: var(--spacing-400); } @@ -512,7 +517,7 @@ a { p { line-height: 1.8; - margin-top: var(--spacing-200); + margin-top: var(--spacing-300); } ol li { @@ -542,7 +547,7 @@ code, table.pre, pre { } table.pre, pre.fssnip.highlighted { - margin: var(--spacing-200) 0; + margin: var(--spacing-300) 0; padding: var(--spacing-200); } @@ -570,7 +575,7 @@ pre.fssnip.highlighted > code, table.pre .fssnip, table.pre .fssnip code { } /* Custom scrollbar styling */ -main, table.pre, code { +main, aside, table.pre, code { overflow-x: auto; max-width: 100%; diff --git a/src/FSharp.Formatting.Common/Templating.fs b/src/FSharp.Formatting.Common/Templating.fs index 94b860f84..889285138 100644 --- a/src/FSharp.Formatting.Common/Templating.fs +++ b/src/FSharp.Formatting.Common/Templating.fs @@ -104,6 +104,9 @@ module ParamKeys = /// A parameter key known to FSharp.Formatting let ``fsdocs-logo-src`` = ParamKey "fsdocs-logo-src" + /// A parameter key known to FSharp.Formatting + let ``fsdocs-favicon-src`` = ParamKey "fsdocs-favicon-src" + /// A parameter key known to FSharp.Formatting let ``fsdocs-package-license-expression`` = ParamKey "fsdocs-package-license-expression" diff --git a/src/fsdocs-tool/ProjectCracker.fs b/src/fsdocs-tool/ProjectCracker.fs index 1d01fb647..8d848598d 100644 --- a/src/fsdocs-tool/ProjectCracker.fs +++ b/src/fsdocs-tool/ProjectCracker.fs @@ -203,6 +203,7 @@ module Crack = FsDocsReleaseNotesLink: string option FsDocsSourceFolder: string option FsDocsSourceRepository: string option + FsDocsFaviconSource: string option FsDocsTheme: string option FsDocsWarnOnMissingDocs: bool PackageProjectUrl: string option @@ -228,6 +229,7 @@ module Crack = "UsesMarkdownComments" "FsDocsCollectionNameLink" "FsDocsLogoSource" + "FsDocsFaviconSource" "FsDocsTheme" "FsDocsLogoLink" "FsDocsLicenseLink" @@ -317,6 +319,7 @@ module Crack = FsDocsReleaseNotesLink = msbuildPropString "FsDocsReleaseNotesLink" FsDocsLogoLink = msbuildPropString "FsDocsLogoLink" FsDocsLogoSource = msbuildPropString "FsDocsLogoSource" + FsDocsFaviconSource = msbuildPropString "FsDocsFaviconSource" FsDocsTheme = msbuildPropString "FsDocsTheme" FsDocsWarnOnMissingDocs = msbuildPropBool "FsDocsWarnOnMissingDocs" |> Option.defaultValue false UsesMarkdownComments = msbuildPropBool "UsesMarkdownComments" |> Option.defaultValue false @@ -515,6 +518,7 @@ module Crack = FsDocsReleaseNotesLink = projectInfos |> List.tryPick (fun info -> info.FsDocsReleaseNotesLink) FsDocsLogoLink = projectInfos |> List.tryPick (fun info -> info.FsDocsLogoLink) FsDocsLogoSource = projectInfos |> List.tryPick (fun info -> info.FsDocsLogoSource) + FsDocsFaviconSource = projectInfos |> List.tryPick (fun info -> info.FsDocsFaviconSource) FsDocsSourceFolder = projectInfos |> List.tryPick (fun info -> info.FsDocsSourceFolder) FsDocsSourceRepository = projectInfos |> List.tryPick (fun info -> info.FsDocsSourceRepository) FsDocsTheme = projectInfos |> List.tryPick (fun info -> info.FsDocsTheme) @@ -556,10 +560,11 @@ module Crack = ParamKeys.``fsdocs-collection-name-link`` (Some(info.FsDocsCollectionNameLink |> Option.defaultValue projectUrl)) param None ParamKeys.``fsdocs-copyright`` info.Copyright + param None ParamKeys.``fsdocs-logo-src`` (Some(defaultArg info.FsDocsLogoSource "img/logo.png")) param None - ParamKeys.``fsdocs-logo-src`` - (Some(defaultArg info.FsDocsLogoSource (sprintf "%simg/logo.png" root))) + ParamKeys.``fsdocs-favicon-src`` + (Some(defaultArg info.FsDocsFaviconSource "img/favicon.ico")) param None ParamKeys.``fsdocs-theme`` (Some(defaultArg info.FsDocsTheme "default")) param None From ba8da7036de5f2849c1fea30dd06acd33f89f586 Mon Sep 17 00:00:00 2001 From: nojaf Date: Mon, 30 Oct 2023 18:24:11 +0100 Subject: [PATCH 19/71] Add active class for menu item in navigation. --- docs/content/fsdocs-default.css | 6 +- src/FSharp.Formatting.ApiDocs/GenerateHtml.fs | 10 +- .../GenerateMarkdown.fs | 12 ++- src/FSharp.Formatting.Common/Menu.fs | 11 ++- src/FSharp.Formatting.Common/Templating.fs | 8 ++ src/FSharp.Formatting.Literate/Contexts.fs | 3 + src/FSharp.Formatting.Literate/Formatting.fs | 5 +- src/fsdocs-tool/BuildCommand.fs | 91 ++++++++++++------- 8 files changed, 101 insertions(+), 45 deletions(-) diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 2626707b3..a7a6b6e3b 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -348,9 +348,13 @@ main { } } - &:hover { + &:hover, &.active { border-color: var(--text-color); } + + &.active { + font-weight: 600; + } } @media screen and (min-width: 768px) { diff --git a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs index 325b4c37c..97df4d73a 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs @@ -617,9 +617,10 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) = let link = model.IndexFileUrl(root, collectionName, qualify, model.FileExtensions.InUrl) [ { Menu.MenuItem.Link = link - Menu.MenuItem.Content = title } ] + Menu.MenuItem.Content = title + Menu.MenuItem.IsActive = true } ] - Menu.createMenu menuTemplateFolder.Value "API Reference" menuItems + Menu.createMenu menuTemplateFolder.Value false "API Reference" menuItems else let categorise = Categorise.model model @@ -634,9 +635,10 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) = let name = ns.Name { Menu.MenuItem.Link = link - Menu.MenuItem.Content = name }) + Menu.MenuItem.Content = name + Menu.MenuItem.IsActive = false }) - Menu.createMenu menuTemplateFolder.Value "Namespaces" menuItems + Menu.createMenu menuTemplateFolder.Value false "Namespaces" menuItems else listOfNamespacesNavAux otherDocs nsOpt |> List.map (fun html -> html.ToString()) diff --git a/src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs b/src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs index fe0a75b5e..12b940795 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs @@ -367,9 +367,10 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) = let link = model.IndexFileUrl(root, collectionName, qualify, model.FileExtensions.InUrl) [ { Menu.MenuItem.Link = link - Menu.MenuItem.Content = title } ] + Menu.MenuItem.Content = title + Menu.MenuItem.IsActive = false } ] - Menu.createMenu menuTemplateFolder.Value "API Reference" menuItems + Menu.createMenu menuTemplateFolder.Value false "API Reference" menuItems else let categorise = Categorise.model model @@ -384,9 +385,10 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) = let name = ns.Name { Menu.MenuItem.Link = link - Menu.MenuItem.Content = name }) + Menu.MenuItem.Content = name + Menu.MenuItem.IsActive = false }) - Menu.createMenu menuTemplateFolder.Value "Namespaces" menuItems + Menu.createMenu menuTemplateFolder.Value false "Namespaces" menuItems else listOfNamespacesAux otherDocs nav nsOpt |> List.map (fun html -> html.ToString()) @@ -432,7 +434,7 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) = () - for (nsIndex, ns) in Seq.indexed collection.Namespaces do + for nsIndex, ns in Seq.indexed collection.Namespaces do let content = MarkdownDocument(namespaceContent (nsIndex, ns), Map.empty) diff --git a/src/FSharp.Formatting.Common/Menu.fs b/src/FSharp.Formatting.Common/Menu.fs index 4968b3a3f..1ffe71947 100644 --- a/src/FSharp.Formatting.Common/Menu.fs +++ b/src/FSharp.Formatting.Common/Menu.fs @@ -4,7 +4,10 @@ open System open System.IO open FSharp.Formatting.Templating -type MenuItem = { Link: string; Content: string } +type MenuItem = + { Link: string + Content: string + IsActive: bool } let private snakeCase (v: string) = System.Text.RegularExpressions.Regex @@ -12,7 +15,7 @@ let private snakeCase (v: string) = .Replace(" ", "_") .ToLower() -let createMenu (input: string) (header: string) (items: MenuItem list) : string = +let createMenu (input: string) (isCategoryActive: bool) (header: string) (items: MenuItem list) : string = let pwd = Directory.GetCurrentDirectory() let menuTemplate = File.ReadAllText(Path.Combine(pwd, input, "_menu_template.html")) let menuItemTemplate = File.ReadAllText(Path.Combine(pwd, input, "_menu-item_template.html")) @@ -27,13 +30,15 @@ let createMenu (input: string) (header: string) (items: MenuItem list) : string SimpleTemplating.ApplySubstitutionsInText [| ParamKeys.``fsdocs-menu-item-link``, link ParamKeys.``fsdocs-menu-item-content``, title - ParamKeys.``fsdocs-menu-item-id``, id |] + ParamKeys.``fsdocs-menu-item-id``, id + ParamKeys.``fsdocs-menu-item-active-class``, (if isCategoryActive then "active" else "") |] menuItemTemplate) |> String.concat "\n" SimpleTemplating.ApplySubstitutionsInText [| ParamKeys.``fsdocs-menu-header-content``, header ParamKeys.``fsdocs-menu-header-id``, snakeCase header + ParamKeys.``fsdocs-menu-header-active-class``, (if isCategoryActive then "active" else "") ParamKeys.``fsdocs-menu-items``, menuItems |] menuTemplate diff --git a/src/FSharp.Formatting.Common/Templating.fs b/src/FSharp.Formatting.Common/Templating.fs index 889285138..773b18078 100644 --- a/src/FSharp.Formatting.Common/Templating.fs +++ b/src/FSharp.Formatting.Common/Templating.fs @@ -164,6 +164,10 @@ module ParamKeys = /// A parameter key known to FSharp.Formatting, available in _menu_template.html let ``fsdocs-menu-header-id`` = ParamKey "fsdocs-menu-header-id" + /// A parameter key known to FSharp.Formatting, available in _menu_template.html + /// This will be an empty string if the category is not active. + let ``fsdocs-menu-header-active-class`` = ParamKey "fsdocs-menu-header-active-class" + /// A parameter key known to FSharp.Formatting, available in _menu_template.html let ``fsdocs-menu-items`` = ParamKey "fsdocs-menu-items" @@ -176,6 +180,10 @@ module ParamKeys = /// A parameter key known to FSharp.Formatting, available in _menu-item_template.html let ``fsdocs-menu-item-id`` = ParamKey "fsdocs-menu-item-id" + /// A parameter key known to FSharp.Formatting, available in _menu-item_template.html + /// /// This will be an empty string if the item is not active. + let ``fsdocs-menu-item-active-class`` = ParamKey "fsdocs-menu-item-active-class" + /// A parameter key known to FSharp.Formatting, available when frontmatter is used correctly let ``fsdocs-previous-page-link`` = ParamKey "fsdocs-previous-page-link" diff --git a/src/FSharp.Formatting.Literate/Contexts.fs b/src/FSharp.Formatting.Literate/Contexts.fs index 07a8a395f..a42707acc 100644 --- a/src/FSharp.Formatting.Literate/Contexts.fs +++ b/src/FSharp.Formatting.Literate/Contexts.fs @@ -73,6 +73,9 @@ type internal LiterateDocModel = /// The kind of output generated OutputKind: OutputKind + + /// Used for the navigation section, to indicate the list item as active + IsActive: bool } // Get the URI for the resource when it is part of an overall site diff --git a/src/FSharp.Formatting.Literate/Formatting.fs b/src/FSharp.Formatting.Literate/Formatting.fs index de0a70f3f..815495ad9 100644 --- a/src/FSharp.Formatting.Literate/Formatting.fs +++ b/src/FSharp.Formatting.Literate/Formatting.fs @@ -262,4 +262,7 @@ module internal Formatting = CategoryIndex = categoryIndex Index = index IndexText = indexText - Substitutions = substitutions } + Substitutions = substitutions + // No don't know this until later. + // See DocContent.GetNavigationEntries + IsActive = false } diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs index df86a6cf2..5c578688f 100644 --- a/src/fsdocs-tool/BuildCommand.fs +++ b/src/fsdocs-tool/BuildCommand.fs @@ -578,7 +578,12 @@ type internal DocContent uri = model.Uri(root) } | _ -> () |] - member _.GetNavigationEntries(input, docModels: (string * bool * LiterateDocModel) list) = + member _.GetNavigationEntries + ( + input, + docModels: (string * bool * LiterateDocModel) list, + currentPagePath: string option + ) = let modelsForList = [ for thing in docModels do match thing with @@ -587,12 +592,16 @@ type internal DocContent && model.OutputKind = OutputKind.Html && not (Path.GetFileNameWithoutExtension(inputFileFullPath) = "index") -> - model + { model with + IsActive = + match currentPagePath with + | None -> false + | Some currentPagePath -> currentPagePath = inputFileFullPath } | _ -> () ] let modelsByCategory = modelsForList - |> List.groupBy (fun model -> model.Category) + |> List.groupBy (fun (model) -> model.Category) |> List.sortBy (fun (_, ms) -> match ms.[0].CategoryIndex with | Some s -> @@ -602,19 +611,12 @@ type internal DocContent Int32.MaxValue) | None -> Int32.MaxValue) - let orderList (list: LiterateDocModel list) = + let orderList (list: (LiterateDocModel) list) = list - |> List.sortBy (fun model -> - match model.Index with - | Some s -> - (try - int32 s - with _ -> - Int32.MaxValue) - | None -> Int32.MaxValue) + |> List.sortBy (fun model -> Option.defaultValue Int32.MaxValue model.Index) if Menu.isTemplatingAvailable input then - let createGroup (header: string) (items: LiterateDocModel list) : string = + let createGroup (isCategoryActive: bool) (header: string) (items: LiterateDocModel list) : string = //convert items into menuitem list let menuItems = orderList items @@ -623,18 +625,20 @@ type internal DocContent let title = System.Web.HttpUtility.HtmlEncode model.Title { Menu.MenuItem.Link = link - Menu.MenuItem.Content = title }) + Menu.MenuItem.Content = title + Menu.MenuItem.IsActive = model.IsActive }) - Menu.createMenu input header menuItems + Menu.createMenu input isCategoryActive header menuItems // No categories specified if modelsByCategory.Length = 1 && (fst modelsByCategory.[0]) = None then let _, items = modelsByCategory.[0] - createGroup "Documentation" items + createGroup false "Documentation" items else modelsByCategory |> List.map (fun (header, items) -> let header = Option.defaultValue "Other" header - createGroup header items) + let isActive = items |> List.exists (fun m -> m.IsActive) + createGroup isActive header items) |> String.concat "\n" else [ @@ -644,22 +648,34 @@ type internal DocContent for model in snd modelsByCategory.[0] do let link = model.Uri(root) + let activeClass = if model.IsActive then "active" else "" - li [ Class "nav-item" ] [ a [ Class "nav-link"; (Href link) ] [ encode model.Title ] ] + li + [ Class $"nav-item %s{activeClass}" ] + [ a [ Class "nav-link"; (Href link) ] [ encode model.Title ] ] else // At least one category has been specified. Sort each category by index and emit // Use 'Other' as a header for uncategorised things for (cat, modelsInCategory) in modelsByCategory do let modelsInCategory = orderList modelsInCategory + let categoryActiveClass = + if modelsInCategory |> List.exists (fun m -> m.IsActive) then + "active" + else + "" + match cat with - | Some c -> li [ Class "nav-header" ] [ !!c ] - | None -> li [ Class "nav-header" ] [ !! "Other" ] + | Some c -> li [ Class $"nav-header %s{categoryActiveClass}" ] [ !!c ] + | None -> li [ Class $"nav-header %s{categoryActiveClass}" ] [ !! "Other" ] for model in modelsInCategory do let link = model.Uri(root) + let activeClass = if model.IsActive then "active" else "" - li [ Class "nav-item" ] [ a [ Class "nav-link"; (Href link) ] [ encode model.Title ] ] ] + li + [ Class $"nav-item %s{activeClass}" ] + [ a [ Class "nav-link"; (Href link) ] [ encode model.Title ] ] ] |> List.map (fun html -> html.ToString()) |> String.concat " \n" @@ -1675,12 +1691,9 @@ type CoreBuildOptions(watch) = ) let docModels = docContent.Convert(this.input, defaultTemplate, extraInputs) - let actualDocModels = docModels |> List.map fst |> List.choose id - let extrasForSearchIndex = docContent.GetSearchIndexEntries(actualDocModels) - - let navEntries = docContent.GetNavigationEntries(this.input, actualDocModels) + let navEntriesWithoutActivePage = docContent.GetNavigationEntries(this.input, actualDocModels, None) let headTemplateContent = let headTemplatePath = Path.Combine(this.input, "_head.html") @@ -1709,20 +1722,36 @@ type CoreBuildOptions(watch) = latestDocContentSearchIndexEntries <- extrasForSearchIndex latestDocContentGlobalParameters <- - [ ParamKeys.``fsdocs-list-of-documents``, navEntries + [ ParamKeys.``fsdocs-list-of-documents``, navEntriesWithoutActivePage ParamKeys.``fsdocs-head-extra``, headTemplateContent ParamKeys.``fsdocs-body-extra``, bodyTemplateContent ] latestDocContentPhase2 <- (fun globals -> - printfn "" printfn "Write Content:" - for (_thing, action) in docModels do - action globals - - )) + for (optDocModel, action) in docModels do + let globals = + match optDocModel with + | None -> globals + | Some(currentPagePath, _, _) -> + // Update the nav entries with the current page doc model + let navEntries = + docContent.GetNavigationEntries( + this.input, + actualDocModels, + Some currentPagePath + ) + + globals + |> List.map (fun (pk, v) -> + if pk <> ParamKeys.``fsdocs-list-of-documents`` then + pk, v + else + ParamKeys.``fsdocs-list-of-documents``, navEntries) + + action globals)) let runDocContentPhase2 () = protect "Content generation (phase 2)" (fun () -> From 7ac178f31fe46dbbf8ed9a492ec65e647b3d4f9c Mon Sep 17 00:00:00 2001 From: nojaf Date: Thu, 2 Nov 2023 17:07:49 +0100 Subject: [PATCH 20/71] Add on this page section. --- docs/_template.html | 4 + docs/content/fsdocs-default.css | 78 +++++++++++++++++-- src/FSharp.Formatting.ApiDocs/GenerateHtml.fs | 1 + .../FSharp.Formatting.Common.fsproj | 1 + .../PageContentList.fs | 25 ++++++ src/FSharp.Formatting.Common/Templating.fs | 3 + src/FSharp.Formatting.Literate/Formatting.fs | 36 ++++++++- .../HtmlFormatting.fs | 6 +- 8 files changed, 147 insertions(+), 7 deletions(-) create mode 100644 src/FSharp.Formatting.Common/PageContentList.fs diff --git a/docs/_template.html b/docs/_template.html index dc6bda96e..4fd593516 100644 --- a/docs/_template.html +++ b/docs/_template.html @@ -66,6 +66,10 @@ {{fsdocs-content}} {{fsdocs-tooltips}}
+
+

On this page

+ {{fsdocs-page-content-list}} +
diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index a7a6b6e3b..9e9a1e6c6 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -35,6 +35,7 @@ --container-lg: 1024px; --container-xl: 1200px; --container-xxl: 1400px; + --container-xxxl: 1800px; --aside-width: 250px; --header-height: 60px; --body-grid-template-columns: var(--aside-width) minmax(0, 1fr); @@ -303,6 +304,7 @@ aside { main { height: calc(100vh - var(--header-height)); + scroll-behavior: smooth; } #content { @@ -313,6 +315,42 @@ main { } } +#fsdocs-page-content-list { + display: none; + padding: var(--spacing-300); + background-color: var(--header-background); + border-left: 1px solid var(--header-border); + + > p { + font-size: var(--font-100); + line-height: 1.5; + color: var(--text-color); + font-weight: 500; + margin: 0 0 var(--spacing-50); + } + + & ul { + list-style: none; + padding: 0; + margin: 0; + + & li { + border-left: 1px solid var(--header-border); + + &:hover, &:focus { + border-color: var(--text-color); + } + + & a { + color: var(--text-color); + text-decoration: none; + padding: var(--spacing-50) var(--spacing-100); + display: block; + } + } + } +} + /* menu items */ .menu { padding: 0; @@ -351,7 +389,7 @@ main { &:hover, &.active { border-color: var(--text-color); } - + &.active { font-weight: 600; } @@ -438,14 +476,44 @@ main { } @media screen and (min-width: 1200px) { - #content { - max-width: calc(var(--container-xl) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); + main { + display: flex; + flex-flow: row wrap; + + > #content { + margin-left: auto; + margin-right: auto; + max-width: calc(var(--container-xl) - var(--aside-width) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); + flex: 1; + } + + > #fsdocs-page-content-list { + display: block; + + /* Hide the side-menu on the API doc pages */ + /* :has is not cross browser, won't work in Firefox */ + + &:has(.empty) { + display: none; + } + + width: var(--aside-width); + position: sticky; + top: 0; + height: 100%; + } } } @media screen and (min-width: 1400px) { - #content { - max-width: calc(var(--container-xxl) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); + main > #content { + max-width: calc(var(--container-xxl) - var(--aside-width) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); + } +} + +@media screen and (min-width: 1800px) { + main > #content { + max-width: calc(var(--container-xxxl) - var(--aside-width) - var(--aside-width) - var(--spacing-300) - var(--spacing-300)); } } diff --git a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs index 97df4d73a..e2305d804 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs @@ -658,6 +658,7 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) = yield (ParamKeys.``fsdocs-source``, "") yield (ParamKeys.``fsdocs-tooltips``, "") yield (ParamKeys.``fsdocs-page-title``, pageTitle) + yield (ParamKeys.``fsdocs-page-content-list``, PageContentList.EmptyContent) yield! globalParameters |] let collection = model.Collection diff --git a/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj b/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj index c12c8f62f..581241b74 100644 --- a/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj +++ b/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj @@ -14,6 +14,7 @@ + diff --git a/src/FSharp.Formatting.Common/PageContentList.fs b/src/FSharp.Formatting.Common/PageContentList.fs new file mode 100644 index 000000000..11b95fe4e --- /dev/null +++ b/src/FSharp.Formatting.Common/PageContentList.fs @@ -0,0 +1,25 @@ +module FSharp.Formatting.Common.PageContentList + +open FSharp.Formatting.HtmlModel +open FSharp.Formatting.HtmlModel.Html + +type PageHeaderInfo = + { Level: int + Href: string + Text: string } + +[] +let EmptyContent = "
" + +let mkPageContentMenu (items: PageHeaderInfo list) = + if List.isEmpty items then + EmptyContent + else + + let listItems = + items + |> List.map (fun item -> li [ Class $"level-%i{item.Level}" ] [ a [ Href item.Href ] [ !!item.Text ] ]) + + let html = ul [] listItems + + html.ToString() diff --git a/src/FSharp.Formatting.Common/Templating.fs b/src/FSharp.Formatting.Common/Templating.fs index 773b18078..6d36740e6 100644 --- a/src/FSharp.Formatting.Common/Templating.fs +++ b/src/FSharp.Formatting.Common/Templating.fs @@ -83,6 +83,9 @@ module ParamKeys = /// A parameter key known to FSharp.Formatting let ``fsdocs-content`` = ParamKey "fsdocs-content" + /// A parameter key known to FSharp.Formatting + let ``fsdocs-page-content-list`` = ParamKey "fsdocs-page-content-list" + /// A parameter key known to FSharp.Formatting let ``fsdocs-collection-name-link`` = ParamKey "fsdocs-collection-name-link" diff --git a/src/FSharp.Formatting.Literate/Formatting.fs b/src/FSharp.Formatting.Literate/Formatting.fs index 815495ad9..421ccc3a1 100644 --- a/src/FSharp.Formatting.Literate/Formatting.fs +++ b/src/FSharp.Formatting.Literate/Formatting.fs @@ -1,6 +1,7 @@ namespace FSharp.Formatting.Literate open System.IO +open System.Xml open FSharp.Formatting.Literate open FSharp.Formatting.CodeFormat open FSharp.Formatting.Markdown @@ -234,6 +235,8 @@ module internal Formatting = yield! sourceSubstitutions yield! nextPreviousPageSubstitutions ] + + let formattedDocument = format doc.MarkdownDocument @@ -243,12 +246,43 @@ module internal Formatting = ctx.CodeReferenceResolver ctx.MarkdownDirectLinkResolver + // We process the html to collect the table of content. + // We can't use the doc.MarkdownDocument because we cannot easily get the generated id values. + // It is safer to parse the html. + let pageHeaders = + try + let doc = XmlDocument() + doc.LoadXml($"
%s{formattedDocument.Trim([| '\r'; '\n' |])}
") + let xpathQuery = "//*[self::h1 or self::h2 or self::h3 or self::h4]/a" + let nodes = doc.SelectNodes(xpathQuery) + + let pageHeaderInfo = + if isNull nodes then + [] + else + nodes + |> Seq.cast + |> Seq.map (fun xmlNode -> + let level = xmlNode.ParentNode.Name.TrimStart('h') |> int + + { Level = level + Href = xmlNode.Attributes.["href"].Value + Text = xmlNode.InnerText } + : FSharp.Formatting.Common.PageContentList.PageHeaderInfo) + |> Seq.toList + + FSharp.Formatting.Common.PageContentList.mkPageContentMenu pageHeaderInfo + with ex -> + System.String.Empty + let tipsHtml = doc.FormattedTips // Construct new Markdown document and write it let substitutions = substitutions0 - @ [ ParamKeys.``fsdocs-content``, formattedDocument; ParamKeys.``fsdocs-tooltips``, tipsHtml ] + @ [ ParamKeys.``fsdocs-content``, formattedDocument + ParamKeys.``fsdocs-tooltips``, tipsHtml + ParamKeys.``fsdocs-page-content-list``, pageHeaders ] let indexText = (match ctx.OutputKind with diff --git a/src/FSharp.Formatting.Markdown/HtmlFormatting.fs b/src/FSharp.Formatting.Markdown/HtmlFormatting.fs index 32777b227..dde0dbd76 100644 --- a/src/FSharp.Formatting.Markdown/HtmlFormatting.fs +++ b/src/FSharp.Formatting.Markdown/HtmlFormatting.fs @@ -78,7 +78,11 @@ let rec internal formatSpan (ctx: FormattingContext) span = | AnchorLink(id, _) -> ctx.Writer.Write(" ") | EmbedSpans(cmd, _) -> formatSpans ctx (cmd.Render()) - | Literal(str, _) -> ctx.Writer.Write(str) + | Literal(str, _) -> + if str.Contains(''') then + ctx.Writer.Write(htmlEncode str) + else + ctx.Writer.Write(str) | HardLineBreak(_) -> ctx.Writer.Write("
" + ctx.Newline) | IndirectLink(body, _, LookupKey ctx.Links (link, title), _) | DirectLink(body, link, title, _) -> From 9cc492c6123a9901d5bc0388d1c77abb5ab22d65 Mon Sep 17 00:00:00 2001 From: nojaf Date: Thu, 2 Nov 2023 17:43:21 +0100 Subject: [PATCH 21/71] Use regex parsing instead of xml. --- .../PageContentList.fs | 36 +++++++++++-------- src/FSharp.Formatting.Literate/Formatting.fs | 29 +-------------- 2 files changed, 23 insertions(+), 42 deletions(-) diff --git a/src/FSharp.Formatting.Common/PageContentList.fs b/src/FSharp.Formatting.Common/PageContentList.fs index 11b95fe4e..f94349686 100644 --- a/src/FSharp.Formatting.Common/PageContentList.fs +++ b/src/FSharp.Formatting.Common/PageContentList.fs @@ -1,25 +1,33 @@ module FSharp.Formatting.Common.PageContentList +open System.Text.RegularExpressions open FSharp.Formatting.HtmlModel open FSharp.Formatting.HtmlModel.Html -type PageHeaderInfo = - { Level: int - Href: string - Text: string } - [] let EmptyContent = "
" -let mkPageContentMenu (items: PageHeaderInfo list) = - if List.isEmpty items then - EmptyContent - else +/// We process the html to collect the table of content. +/// We can't use the doc.MarkdownDocument because we cannot easily get the generated id values. +/// It is safer to parse the html. +let mkPageContentMenu (html: string) = + let headingLinkPattern = "([^<]+)" + + let regex = Regex(headingLinkPattern) + + let extractHeadingLinks (matchItem: Match) = + let level = int matchItem.Groups.[1].Value + let href = matchItem.Groups.[2].Value + let linkText = matchItem.Groups.[3].Value - let listItems = - items - |> List.map (fun item -> li [ Class $"level-%i{item.Level}" ] [ a [ Href item.Href ] [ !!item.Text ] ]) + li [ Class $"level-%i{level}" ] [ a [ Href href ] [ !!linkText ] ] - let html = ul [] listItems + let listItems = + regex.Matches(html) + |> Seq.cast + |> Seq.map extractHeadingLinks + |> Seq.toList - html.ToString() + match listItems with + | [] -> EmptyContent + | items -> string (ul [] items) diff --git a/src/FSharp.Formatting.Literate/Formatting.fs b/src/FSharp.Formatting.Literate/Formatting.fs index 421ccc3a1..db480e2a5 100644 --- a/src/FSharp.Formatting.Literate/Formatting.fs +++ b/src/FSharp.Formatting.Literate/Formatting.fs @@ -246,34 +246,7 @@ module internal Formatting = ctx.CodeReferenceResolver ctx.MarkdownDirectLinkResolver - // We process the html to collect the table of content. - // We can't use the doc.MarkdownDocument because we cannot easily get the generated id values. - // It is safer to parse the html. - let pageHeaders = - try - let doc = XmlDocument() - doc.LoadXml($"
%s{formattedDocument.Trim([| '\r'; '\n' |])}
") - let xpathQuery = "//*[self::h1 or self::h2 or self::h3 or self::h4]/a" - let nodes = doc.SelectNodes(xpathQuery) - - let pageHeaderInfo = - if isNull nodes then - [] - else - nodes - |> Seq.cast - |> Seq.map (fun xmlNode -> - let level = xmlNode.ParentNode.Name.TrimStart('h') |> int - - { Level = level - Href = xmlNode.Attributes.["href"].Value - Text = xmlNode.InnerText } - : FSharp.Formatting.Common.PageContentList.PageHeaderInfo) - |> Seq.toList - - FSharp.Formatting.Common.PageContentList.mkPageContentMenu pageHeaderInfo - with ex -> - System.String.Empty + let pageHeaders = FSharp.Formatting.Common.PageContentList.mkPageContentMenu formattedDocument let tipsHtml = doc.FormattedTips From 5972b48222e49cf807baa372330ed58e62dfbb12 Mon Sep 17 00:00:00 2001 From: nojaf Date: Fri, 3 Nov 2023 08:44:47 +0100 Subject: [PATCH 22/71] Tweaks after testing F# Compiler site. --- docs/_template.html | 1 + docs/content/fsdocs-default.css | 2 +- docs/content/fsdocs-theme.js | 5 +++++ 3 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 docs/content/fsdocs-theme.js diff --git a/docs/_template.html b/docs/_template.html index 4fd593516..b9ba28a52 100644 --- a/docs/_template.html +++ b/docs/_template.html @@ -73,6 +73,7 @@ + {{fsdocs-body-extra}} \ No newline at end of file diff --git a/docs/content/fsdocs-default.css b/docs/content/fsdocs-default.css index 9e9a1e6c6..e5d969a08 100644 --- a/docs/content/fsdocs-default.css +++ b/docs/content/fsdocs-default.css @@ -36,7 +36,7 @@ --container-xl: 1200px; --container-xxl: 1400px; --container-xxxl: 1800px; - --aside-width: 250px; + --aside-width: 260px; --header-height: 60px; --body-grid-template-columns: var(--aside-width) minmax(0, 1fr); --aside-grid-row: 2; diff --git a/docs/content/fsdocs-theme.js b/docs/content/fsdocs-theme.js new file mode 100644 index 000000000..124be0f9c --- /dev/null +++ b/docs/content/fsdocs-theme.js @@ -0,0 +1,5 @@ +// Automatically scroll to the active aside menu item. +const activeItem = document.querySelector("aside .nav-item.active"); +if (activeItem) { + activeItem.scrollIntoView(); +} \ No newline at end of file From 1ec3a50bf77e81e126177886ff5176e34ca56aa9 Mon Sep 17 00:00:00 2001 From: nojaf Date: Fri, 3 Nov 2023 08:57:50 +0100 Subject: [PATCH 23/71] Update release notes for v20 alpha 1. --- RELEASE_NOTES.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index c8063ad05..fa31bb556 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,6 +2,19 @@ ### Removed * `FsDocsNavbarPosition` is no longer respected. Use CSS variables instead. See [docs](https://fsprojects.github.io/FSharp.Formatting/templates/leftside/styling.html). +* ⚠️ Search was completely removed and will be revisited in future versions. + +### Changed +* The default template was updated and is not compatible with previous versions. + +### Added +* Dark mode is available out of the box. +* `{{fsdocs-head-extra}}` can included additional html before the closing `` when `_head.html` exists. +* `{{fsdocs-body-extra}}` can included additional html before the closing `` when `_body.html` exists. +* MSBuild property `` can be used to configure the favicon. +* `active` class is added to the active menu item in `{{fsdocs-list-of-documents}}`. + If menu templating is used, `{{fsdocs-menu-header-active-class}}` and `{{fsdocs-menu-item-active-class}}` are avaiable. +* `{{fsdocs-page-content-list}}` contains an unordered list of the header (`h1` till `h4`) of the current page. (if available) ## 19.1.1 From fdd9af4d895f496a5d1aee0481c08c6ef3cf21a1 Mon Sep 17 00:00:00 2001 From: nojaf Date: Fri, 3 Nov 2023 12:55:25 +0100 Subject: [PATCH 24/71] Fix failing unit test --- src/FSharp.Formatting.Markdown/HtmlFormatting.fs | 6 +----- tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs | 3 ++- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/src/FSharp.Formatting.Markdown/HtmlFormatting.fs b/src/FSharp.Formatting.Markdown/HtmlFormatting.fs index dde0dbd76..32777b227 100644 --- a/src/FSharp.Formatting.Markdown/HtmlFormatting.fs +++ b/src/FSharp.Formatting.Markdown/HtmlFormatting.fs @@ -78,11 +78,7 @@ let rec internal formatSpan (ctx: FormattingContext) span = | AnchorLink(id, _) -> ctx.Writer.Write(" ") | EmbedSpans(cmd, _) -> formatSpans ctx (cmd.Render()) - | Literal(str, _) -> - if str.Contains(''') then - ctx.Writer.Write(htmlEncode str) - else - ctx.Writer.Write(str) + | Literal(str, _) -> ctx.Writer.Write(str) | HardLineBreak(_) -> ctx.Writer.Write("
" + ctx.Newline) | IndirectLink(body, _, LookupKey ctx.Links (link, title), _) | DirectLink(body, link, title, _) -> diff --git a/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs b/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs index 2f40960e1..8ab53a099 100644 --- a/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs +++ b/tests/FSharp.ApiDocs.Tests/ApiDocsTests.fs @@ -88,7 +88,8 @@ let substitutions = [ ParamKeys.``fsdocs-collection-name``, "F# TestProject" ParamKeys.``fsdocs-authors``, "Your Name" ParamKeys.``fsdocs-repository-link``, "http://github.com/fsprojects/fsharp-test-project" - ParamKeys.root, "/root/" ] + ParamKeys.root, "/root/" + ParamKeys.``fsdocs-favicon-src``, "img/favicon.ico" ] let generateApiDocs (libraries: string list) (format: OutputFormat) useMdComments uniq = try From 1a4a830e7a32bc1d3c92f2d589f8c52f89b3b8ec Mon Sep 17 00:00:00 2001 From: nojaf Date: Fri, 3 Nov 2023 12:55:53 +0100 Subject: [PATCH 25/71] Migrate to keep a change log. --- Directory.Build.props | 8 +- Directory.Packages.props | 1 + RELEASE_NOTES.md | 862 ++++++++++++++++++--------------------- build.fsx | 47 +-- 4 files changed, 407 insertions(+), 511 deletions(-) diff --git a/Directory.Build.props b/Directory.Build.props index ca1214e3e..013df25cb 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -25,8 +25,14 @@ F# fsharp formatting markdown code fssnip literate programming https://github.com/fsprojects/FSharp.Formatting https://fsprojects.github.io/FSharp.Formatting - https://raw.githubusercontent.com/fsprojects/FSharp.Formatting/master/docs/files/img/logo.png + logo.png Apache-2.0 git + ../../RELEASE_NOTES.md + + + + + \ No newline at end of file diff --git a/Directory.Packages.props b/Directory.Packages.props index 3b3d56946..c31a53aa4 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -24,5 +24,6 @@ + \ No newline at end of file diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index fa31bb556..951551ea9 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,4 +1,6 @@ -## 20.0.0-alpha-001 +# Changelog + +## 20.0.0-alpha-001 - 2023-11-03 ### Removed * `FsDocsNavbarPosition` is no longer respected. Use CSS variables instead. See [docs](https://fsprojects.github.io/FSharp.Formatting/templates/leftside/styling.html). @@ -13,231 +15,230 @@ * `{{fsdocs-body-extra}}` can included additional html before the closing `` when `_body.html` exists. * MSBuild property `` can be used to configure the favicon. * `active` class is added to the active menu item in `{{fsdocs-list-of-documents}}`. - If menu templating is used, `{{fsdocs-menu-header-active-class}}` and `{{fsdocs-menu-item-active-class}}` are avaiable. +If menu templating is used, `{{fsdocs-menu-header-active-class}}` and `{{fsdocs-menu-item-active-class}}` are avaiable. * `{{fsdocs-page-content-list}}` contains an unordered list of the header (`h1` till `h4`) of the current page. (if available) -## 19.1.1 +## 19.1.1 - 2023-10-10 * Fix code rendering on firefox. [#851](https://github.com/fsprojects/FSharp.Formatting/pull/851) -## 19.1.0 +## 19.1.0 - 2023-09-15 * Only reload css file when changed. [#845](https://github.com/fsprojects/FSharp.Formatting/pull/845) * Add previous and next page url substitutions. [#846](https://github.com/fsprojects/FSharp.Formatting/pull/846) -## 19.0.0 +## 19.0.0 - 2023-08-22 * Update FCS to 43.7.400 -## 18.1.1 +## 18.1.1 - 2023-08-02 * Pass `--multiemit-` as default option for `FsiEvaluator`. -## 18.1.0 +## 18.1.0 - 2023-04-13 * Collapsible ApiDocs member info [#778](https://github.com/fsprojects/FSharp.Formatting/issues/778). The issue was fixed collaboratively in an [Amplifying F# session](https://amplifying-fsharp.github.io/) with a recording that can be found [here](https://amplifying-fsharp.github.io/sessions/2023/03/31/). -## 18.0.0 +## 18.0.0 - 2023-03-29 * Update FCS to 43.7.200 * Target `net6.0` for `fsdocs-tool` [#799](https://github.com/fsprojects/FSharp.Formatting/issues/799) -## 17.4.1 +## 17.4.1 - 2023-03-29 * Update ipynb output metadata [#809](https://github.com/fsprojects/FSharp.Formatting/issues/809) -## 17.4.0 +## 17.4.0 - 2023-03-09 * One FSI evaluator per docs file [#737](https://github.com/fsprojects/FSharp.Formatting/issues/737) -## 17.3.0 +## 17.3.0 - 2023-03-06 * Better test project detection [#800](https://github.com/fsprojects/FSharp.Formatting/issues/800) -## 17.2.3 +## 17.2.3 - 2023-02-21 * Fix external docs link [#794](https://github.com/fsprojects/FSharp.Formatting/issues/794) -## 17.2.2 +## 17.2.2 - 2023-01-16 * Improvement for `` [#789](https://github.com/fsprojects/FSharp.Formatting/issues/789) -## 17.2.1 +## 17.2.1 - 2023-01-14 * Fix support for `` [#786](https://github.com/fsprojects/FSharp.Formatting/issues/786) -## 17.2.0 +## 17.2.0 - 2022-12-28 * Resolve markdown links in raw html [#769](https://github.com/fsprojects/FSharp.Formatting/issues/769) -## 17.1.0 +## 17.1.0 - 2022-11-22 * [Add syntax highlighting to API docs](https://github.com/fsprojects/FSharp.Formatting/pull/780) -## 17.0.0 +## 17.0.0 - 2022-11-17 * Update to .NET 7.0.100 -## 16.1.1 +## 16.1.1 - 2022-09-07 * [Fix arguments naming and escape operator name in usageHtml](https://github.com/fsprojects/FSharp.Formatting/pull/765/) -## 16.1.0 +## 16.1.0 - 2022-08-30 * Update to .NET 6.0.400 * Update to Ionide.ProjInfo 0.60 -## 16.0.4 +## 16.0.4 - 2022-08-30 * [Fix indexers in output](https://github.com/fsprojects/FSharp.Formatting/pull/767) -## 16.0.3 +## 16.0.3 - 2022-08-30 * [Fix link translation when using relative input path](https://github.com/fsprojects/FSharp.Formatting/issues/764) -## 16.0.2 +## 16.0.2 - 2022-08-23 * [Improves markdown emphasis parsing.](https://github.com/fsprojects/FSharp.Formatting/pull/763) -## 16.0.1 - -* Custom templaying for menus +## 16.0.1 - 2023-08-16 +* Custom templating for menus -## 15.0.3 +## 15.0.3 - 2023-08-15 * Fixes Markdown parser gets multiple-underscores-inside-italics wrong [#389](https://github.com/fsprojects/FSharp.Formatting/issues/389) -## 15.0.2 +## 15.0.2 - 2023-08-05 * Trim the `--fscoptions` before passing them as `otherflags`. ([comment #616](https://github.com/fsprojects/FSharp.Formatting/issues/616#issuecomment-1200877765)) -## 15.0.1 +## 15.0.1 - 2023-07-01 * fix https://github.com/fsprojects/FSharp.Formatting/issues/749 -## 15.0.0 +## 15.0.0 - 2022-03-20 * Update to .NET 6 -## 14.0.1 +## 14.0.1 - 2021-11-11 * Fixes 703, 700 - `--strict` is now considerably stricter, and more diagnostics being shown -## 14.0.0 +## 14.0.0 - 2021-11-10 * Fix [Getting ReturnType from ApiDocMember without Html already embedded](https://github.com/fsprojects/FSharp.Formatting/issues/708) -## 13.0.1 +## 13.0.1 - 2021-11-10 * Skip the output folder when processing -## 13.0.0 +## 13.0.0 - 2021-11-10 * Remove unused TransformAndOutputDocument from API * Fixes Can't yet format InlineHtmlBlock #723 * Fixes `` blocks are emitting `
` blocks with escapes no longer escaped #712
 
-## 12.0.2
+## 12.0.2 - 2021-11-10
 
 * Remove front-matter output from notebooks
 
-## 12.0.1
+## 12.0.1 - 2021-11-10
 
 * Improve package description
 
-## 12.0.0
+## 12.0.0 - 2021-11-07
 
 * [Allow input-->output link translation](https://github.com/fsprojects/FSharp.Formatting/pull/718)
 
-## 11.5.1
+## 11.5.1 - 2021-10-30
 
 * [Allow user-set ids for xmldoc example nodes](https://github.com/fsprojects/FSharp.Formatting/pull/704)
 
-## 11.5.0
+## 11.5.0 - 2021-10-30
 
 * [Remove MSBuild assemblies from library nugets](https://github.com/fsprojects/FSharp.Formatting/pull/715)
 
-## 11.4.4
+## 11.4.4 - 2021-10-11
 
 * [Websocket CPU efficiency improvements](https://github.com/fsprojects/FSharp.Formatting/pull/711)
 
-## 11.4.3
+## 11.4.3 - 2021-08-17
 
 * Style blockquotes
 
-## 11.4.2
+## 11.4.2 - 2021-07-29
 
 * [Download links broken](https://github.com/fsprojects/FSharp.Formatting/issues/696)
 * [Duplicating HTML tags for FSX and IPYNB output](https://github.com/fsprojects/FSharp.Formatting/issues/695)
 
-## 11.4.1
+## 11.4.1 - 2021-07-23
 
 * [Fixed navbar scrolling](https://github.com/fsprojects/FSharp.Formatting/issues/672#issuecomment-885532640)
 
-## 11.4.0
+## 11.4.0 - 2021-07-22
 
 * [Fixed some CSS](https://github.com/fsprojects/FSharp.Formatting/pull/688/)
 
-## 11.3.0
+## 11.3.0 - 2021-07-22
 
 * [Bump to FSharp.Compiler.Service 40.0](https://github.com/fsprojects/FSharp.Formatting/pull/682)
 * [Fix bottom margin in default CSS](https://github.com/fsprojects/FSharp.Formatting/pull/687)
 * [Improve github and signature links](https://github.com/fsprojects/FSharp.Formatting/pull/681)
 * [Fix typo in location for custom CSS](https://github.com/fsprojects/FSharp.Formatting/pull/684)
 
-## 11.2.0
+## 11.2.0 - 2021-05-17
 
 * scrollable navbar #677 by nhirschey 
 * Show field type for record fields #674
 * Add --ignoreprojects flag  #676 by chengh42 
 
-## 11.1.0
+## 11.1.0 - 2021-04-15
 * Add frontmatter, category, categoryindex, index, title
 
-## 11.0.4
+## 11.0.4 - 2021-04-15
 * testing package publish
 
-## 11.0.3
+## 11.0.3 - 2021-04-14
 * testing package publish
 
-## 11.0.2
+## 11.0.2 - 2021-04-14
 * add favicon.ico to template and use F# logo as default favicon for generated sites
 
-## 11.0.1
+## 11.0.1 - 2021-04-14
 * update to Ionide.ProjInfo
 * use computed args for references in API doc generation
 * Fix #616
 * Fix #662
 * Fix #646
 
-## 10.1.1
+## 10.1.1 - 2021-04-13
 * Switch to cleaner default styling based on DiffSharp styles
 * Change `fsdocs-menu` to `fsdocs-nav`
 
-## 10.0.8
+## 10.0.8 - 2021-04-13
 * Add cref copy buttons by default
 
-## 10.0.7
+## 10.0.7 - 2021-04-13
 * Fix more formatting and switch to `fsdocs-member-usage` instead of `fsdocs-member-name`
 
-## 10.0.2
+## 10.0.2 - 2021-04-13
 * Permit `cref:T:System.Console` code references in markdown content
 
-## 10.0.1
+## 10.0.1 - 2021-04-12
 * Apply substitutions to content
 * Add `fsdocs-source-filename` and `fsdocs-source-basename` substitutions
 
-## 9.0.4
+## 9.0.4 - 2021-03-24
 * Trim spaces from examples (TrimEnd only)
 
-## 9.0.3
+## 9.0.3 - 2021-03-24
 * Trim spaces from examples
 
-## 9.0.1
+## 9.0.1 - 2021-02-11
 * Proper fix for elide multi-language docs from navigation and site search index
 
-## 9.0.0
+## 9.0.0 - 2021-02-11
 * Rename --property flag to --properties
 * Elide multi-language docs from navigation and site search index
 
-## 8.0.1
+## 8.0.1 - 2021-01-21
 * [Prevent CLI parameters from being discarded](https://github.com/fsprojects/FSharp.Formatting/pull/634)
 * [Update Dockerfile and NuGet.config for binder](https://github.com/fsprojects/FSharp.Formatting/pull/636)
 
-## 8.0.0
+## 8.0.0 - 2021-01-14
 * [update FCS, allow fsdocs to roll forward to net5.0](https://github.com/fsprojects/FSharp.Formatting/pull/621)
 * [Refactor the templating engine and the command tool cache](https://github.com/fsprojects/FSharp.Formatting/pull/615)
 * [Refactor the project cracker](https://github.com/fsprojects/FSharp.Formatting/pull/618)
@@ -246,14 +247,14 @@
 * Add more complete info on how to upgrade
 * [CommandTool: add hot reload to the watch command](https://github.com/fsprojects/FSharp.Formatting/pull/629)
 
-## 7.2.9
+## 7.2.9 - 2020-09-22
 
 * Document how to do math in XML comments
 * Add --strict flag to fsdocs for stricter checking
 * Add --property flag to fsdocs to pass properties to dotnet msbuild
 * Better diangostics and logging for fsdocs
 
-## 7.2.8
+## 7.2.8 - 2020-09-09
 
 * [ApiDocs: examples not showing for types and modules](https://github.com/fsprojects/FSharp.Formatting/issues/599)
 
@@ -261,504 +262,413 @@
 
 * Remove untyped Sections from ApiDocComment since individual supported sections are now available
 
-## 7.2.7
+## 7.2.7 - 2020-09-09
 
 * [ApiDocs: cref to members are not resolving to best possible link](https://github.com/fsprojects/FSharp.Formatting/issues/598)
 
 * [ApiDocs: namespace docs are showing in module/type summaries as well](https://github.com/fsprojects/FSharp.Formatting/issues/597)
 
-## 7.2.6
+## 7.2.6 - 2020-08-07
+
+* In ApiDocsModel, separate out the parameter, summary, remarks sections etc.
+
+* In ApiDocsModel, integrate the parameter types with the parameter docs (when using XML docs)
+
+* In HTML generation for API docs, locate the github link top right 
+
+* In ApiDocsModel.Generate, optionally give warnings when XML doc is missing or parameter names are incorrect. Activate using 
+
+* In ApiDocsModel, change "Parameters" to "Substitutions"
+
+* Fix formatting of (most) custom operators
+
+* Fix formatting of op_XYZ binary and unary operators 
+
+## 7.2.5 - 2020-08-06
+
+* change `...` to ` ...  `
+
+* change `3` to `...`
+
+## 7.2.4 - 2020-08-06
 
-- In ApiDocsModel, separate out the parameter, summary, remarks sections etc.
+* support `...`
 
-- In ApiDocsModel, integrate the parameter types with the parameter docs (when using XML docs)
+* support `...`
 
-- In HTML generation for API docs, locate the github link top right 
+* support `...`
 
-- In ApiDocsModel.Generate, optionally give warnings when XML doc is missing or parameter names are incorrect. Activate using 
+* support `...`
 
-- In ApiDocsModel, change "Parameters" to "Substitutions"
+* support ``
 
-- Fix formatting of (most) custom operators
+* allow  `` in XML doc comments
 
-- Fix formatting of op_XYZ binary and unary operators 
+* allow  `` in XML doc comments
 
+* document XML doc things supported
 
-## 7.2.5
+## 7.2.2 - 2020-08-05
 
-- change `...` to ` ...  `
+* instruct about settings
 
-- change `3` to `...`
+## 7.2.1 - 2020-08-05
 
-## 7.2.4
+* fix images in nuget
 
-- support `...`
+## 7.2.0 - 2020-08-05
 
-- support `...`
+* include templates
 
-- support `...`
+## 7.1.8 - 2020-08-05
 
-- support `...`
+* bump version
 
-- support ``
+## 7.1.6 - 2020-08-04
 
-- allow  `` in XML doc comments
+* bump version
 
-- allow  `` in XML doc comments
+## 7.1.5 - 2020-08-04
 
-- document XML doc things supported
+* fix navbar position option fixed-left
 
-## 7.2.2
+## 7.1.4 - 2020-08-04
 
-- instruct about settings
+* fixed property computation 
 
-## 7.2.1
+## 7.1.3 - 2020-08-04
 
-- fix images in nuget
+* fixed typo for `LICENCE.md`
 
-## 7.2.0
+* all classes to have `fsdocs-` prefix
 
-- include templates
+## 7.1.2 - 2020-08-04
 
-## 7.1.8
+* fixed all classes to have `fsdocs-` prefix
 
-- bump version
+* added documentation on styling
 
-## 7.1.6
+## 7.1.1 - 2020-08-04
 
-- bump version
+* fixed root
 
-## 7.1.5
+## 7.1.0 - 2020-08-04
 
-- fix navbar position option fixed-left
+* add text content of markdown and scripts to generated search index
 
-## 7.1.4
+* overhaul the substitution names used by FSharp.Formatting and expected in the template. The table is in the docs and below
 
-- fixed property computation 
+* generate {{fsdocs-list-of-documents}} substitution and use it in both API docs and content
 
-## 7.1.3
+* generate {{fsdocs-list-of-namespaces}} substitution and use it in both API docs and content
 
-- fixed typo for `LICENCE.md`
+* fix link model so {{root}} is always respected
 
-- all classes to have `fsdocs-` prefix
+* Add `qualify` parameter that asks to qualify all names by the collection name e.g. FSharp.Core
 
-## 7.1.2
+* Respect per-project settings, e.g. if one nuget package has a different set of authors or home page to another
 
-- fixed all classes to have `fsdocs-` prefix
+* Add documentation about styling
 
-- added documentation on styling
+* Allow fixed-left and fixed-right positions for the navbar
 
-## 7.1.1
+* Add `{{fsdocs-logo-link}}` parameter to default template
 
-- fixed root
+* Add `{{fsdocs-logo-link}}` parameter to default template
 
-## 7.1.0
+* generate HTML giving hyperlinks for types with cross-links
 
-- add text content of markdown and scripts to generated search index
+* switch to left bootstrap nav bar in template for a table of contents
 
-- overhaul the substitution names used by FSharp.Formatting and expected in the template. The table is in the docs and below
+* improve sizings
 
-- generate {{fsdocs-list-of-documents}} substitution and use it in both API docs and content
+* move to one copy of template in docs/_template.html 
 
-- generate {{fsdocs-list-of-namespaces}} substitution and use it in both API docs and content
+* ApiDocsTypeDefinition and ApiDocsModule merged to ApiDocsEntity
 
-- fix link model so {{root}} is always respected
+* Default template now expects logo in img/logo.png
 
-- Add `qualify` parameter that asks to qualify all names by the collection name e.g. FSharp.Core
+* Improvements in default HTML generation
 
-- Respect per-project settings, e.g. if one nuget package has a different set of authors or home page to another
+* ApiDocComment.Blurb renamed to ApiDocComment.Summary and only populated with summary text for things read from XML
 
-- Add documentation about styling
+* simplify tool instructions
 
-- Allow fixed-left and fixed-right positions for the navbar
+* add info about upgrading
 
-- Add `{{fsdocs-logo-link}}` parameter to default template
+## 6.1.0 - 2020-07-21
+* fix mistake in laying down `extras` directory 
 
-- Add `{{fsdocs-logo-link}}` parameter to default template
+## 6.0.9 - 2020-07-21
+* put extra content in `extras` directory in nuget package and include Dockerfile and NuGet.config
 
-- generate HTML giving hyperlinks for types with cross-links
+## 6.0.8 - 2020-07-21
+* show extended type in generated docs for extension members
+* include fsdocs-styles.css, fsdocs-search.js, fsdocs-tips.js in built site 'content' directory by default
+* use default template from nuget package by default
 
-- switch to left bootstrap nav bar in template for a table of contents
+## 6.0.7 - 2020-07-20
+* fix formatting of generic parameters so they don't show inference variables for members
 
-- improve sizings
+## 6.0.6 - 2020-07-20
+* fix default styling
 
-- move to one copy of template in docs/_template.html 
+## 6.0.5 - 2020-07-20
+* improve display in FSharp.Formatting API docs and add more information
 
-- ApiDocsTypeDefinition and ApiDocsModule merged to ApiDocsEntity
+## 6.0.4 - 2020-07-20
+* Watch defaults to `tmp/watch`
 
-- Default template now expects logo in img/logo.png
+## 6.0.3 - 2020-07-20
+* Add `(*** include-fsi-output **)`
+* Add `(*** include-fsi-merged-output **)`
+* Add server to `dotnet watch` and by default switch to local host
+* Always inject `fsi.AddPrinter`, `fsi.AddHtmlPrinter` etc. into the programming model for literate scripts
 
-- Improvements in default HTML generation
+## 6.0.2 - 2020-07-19
 
-- ApiDocComment.Blurb renamed to ApiDocComment.Summary and only populated with summary text for things read from XML
+* Remove the `api` command from the command line tool (`build` generalises it)
+* Add missing search.js
 
-- simplify tool instructions
+## 6.0.1 - 2020-07-19
 
-- add info about upgrading
+* build the Lunr `index.json` from every execution of `fsdocs build`
+* Make the search index entries available as part of the ApiDocs model
+* Add search box to generated docs
+* Add `ApiDocs` prefix to all types in `ApiDocsModel`
+* Remove `Details` from `ApiDocsModel`
 
-## 6.1.0
-- fix mistake in laying down `extras` directory 
+## 5.0.5 - 2020-07-14
 
-## 6.0.9
-- put extra content in `extras` directory in nuget package and include Dockerfile and NuGet.config
+* Correct behaviour of '--clean'
 
-## 6.0.8
-- show extended type in generated docs for extension members
-- include fsdocs-styles.css, fsdocs-search.js, fsdocs-tips.js in built site 'content' directory by default
-- use default template from nuget package by default
+## 5.0.4 - 2020-07-14
 
-## 6.0.7
-- fix formatting of generic parameters so they don't show inference variables for members
+* Fix emit of odd character in latex output
 
-## 6.0.6
-- fix default styling
+## 5.0.3 - 2020-07-14
 
-## 6.0.5
-- improve display in FSharp.Formatting API docs and add more information
+* Paket update and remove workaround code
+* add '--clean' to fsdocs 
 
-## 6.0.4
-- Watch defaults to `tmp/watch`
+## 5.0.2 - 2020-07-14
+* Update to FCS v36.0
+* Add .ipynb output option for documents
+* Add .fsx output option for documents
+* Literate.WriteHtml --> Literate.ToHtml/Literate.WriteHtml overloads
+* MetadataFormat.Generate --> ApiDocs.GenerateHtml/ApiDocs.GenerateModel overloads
+* Fix Literate.* to do approximate (non-razor) templating/  
+* Remove Razor support
+* HTML templates now use `{{prop-name}}`
+* FSharp.CodeFormat --> FSharp.Formatting.CodeFormat
+* FSharp.Markdown --> FSharp.Formatting.Markdown
+* FSharp.Literate --> FSharp.Formatting.Literate and FSharp.Formatting.Literate.Evaluation
+* FSharp.MetadataFormat --> FSharp.Formatting.ApiDocs
+* FSharp.ApiDocs uses HTML substitution for templating, no Razor
+* Add "include-it" and "include-output" with implied reference to the immediately preceding snippet
+* For command line tool
+Rename fsformatting to fsdocs
+Update command line parser
+"fsformatting literate process-directory" --> "fsdocs convert"
+"fsformatting metadata-format generate" --> "fsdocs api"
+"--dllFiles" --> "--dlls"
+"--outDir" --> "--output"
+"--outputDirectory" --> "--output"
+"--output" is optional (defaults to 'output')
+"--inputDirectory" --> "--input"
+Add --nonpublic
+Add --xmlComments
+Automatically populate metadata from project settings.
+* Add `fsdocs build` command to the documentation generator that has lots of sensible defaults.
 
-## 6.0.3
-- Add `(*** include-fsi-output **)`
-- Add `(*** include-fsi-merged-output **)`
-- Add server to `dotnet watch` and by default switch to local host
-- Always inject `fsi.AddPrinter`, `fsi.AddHtmlPrinter` etc. into the programming model for literate scripts
+## 4.1.0 - 2020-06-01
+* Support preview F# language features.
+* Add support for customizing assigned CSS class.
 
-## 6.0.2
+## 4.0.1 - 2020-05-12
+* Add .NET Core support for all libraries.
+* Update to FSCS v35.0.
+* Add helpers for CustomOperationAttribute.
 
-- Remove the `api` command from the command line tool (`build` generalises it)
-- Add missing search.js
+## 4.0.0-rc2 - 2020-04-24
+* Update to FSCS v34.1.
 
-## 6.0.1
+## 4.0.0-rc2 - 2020-04-24
+* Update to FSCS v34.
 
-- build the Lunr `index.json` from every execution of `fsdocs build`
-- Make the search index entries available as part of the ApiDocs model
-- Add search box to generated docs
-- Add `ApiDocs` prefix to all types in `ApiDocsModel`
-- Remove `Details` from `ApiDocsModel`
+## 4.0.0-rc2 - 2020-04-24
+* Fix packaging issues.
 
-## 5.0.5
+## 4.0.0-rc2 - 2020-04-24
+* Add .NET Core support for all libraries.
+* Update to latest FSharp.Compiler.Service
+
+## 3.1.0 - 2019-04-12
+* remove beta tag since it is already widely used
+
+## 3.0.0-beta01 - 2016-08-01
+* Update to latest FSharp.Compiler.Service
+* No longer filter FSHarp.Core based on optdata/sigdata (it is now always bundled)
+
+## 3.0.0-beta01 - 2016-08-01
+* FSharp.Formatting.Literate for netstandard2.0
+
+## 3.0.0-beta01 - 2016-08-01
+* Fix usage formatting - https://github.com/fsprojects/FSharp.Formatting/issues/472
+
+## 3.0.0-beta01 - 2016-08-01
+* Added support for attributes on modules, types and members
+* Updated razor templates to show attributes and added a warning for obsolete API
+
+## 3.0.0-beta01 - 2016-08-01
+* Upgrade FSharp.Compiler.Service to be compatible with FAKE 5
+
+## 3.0.0-beta01 - 2016-08-01
+* Fix some links on the website - https://github.com/fsprojects/FSharp.Formatting/pull/458
+* Another link on the website - https://github.com/fsprojects/FSharp.Formatting/pull/454
+* Support highlighting for paket.dependencies `storage` keyword - https://github.com/fsprojects/FSharp.Formatting/pull/451
+* In order to upgrade follow instructions at https://fsprojects.github.io/FSharp.Formatting/upgrade_from_v2_to_v3.html
+
+## 3.0.0-beta01 - 2016-08-01
+* Improve Stacktrace on Script file processing
+
+## 3.0.0-beta01 - 2016-08-01
+* Fix System.ValueType dep.
+
+## 3.0.0-beta01 - 2016-08-01
+* Include razor component.
+
+## 3.0.0-beta01 - 2016-08-01
+* Always generate anchors when using command line tool.
+
+## 3.0.0-beta01 - 2016-08-01
+* Don't hide errors in fsformatting tool (Literate).
+* Improve error message by using inner exceptions.
+
+## 3.0.0-beta01 - 2016-08-01
+* Don't hide errors in fsformatting tool.
+
+## 3.0.0-beta01 - 2016-08-01
+* MarkdownSpan and MarkdownParagraph now use named DUs
+* Add range to MarkdownParagraph and MarkdownSpan (https://github.com/fsprojects/FSharp.Formatting/pull/411)
+* FSharp.Formatting no longer has a strong dependency on Razor (https://github.com/fsprojects/FSharp.Formatting/pull/425)
+* FSharp.Formatting no longer depends on VFPT.Core (https://github.com/fsprojects/FSharp.Formatting/pull/432)
+* Add beta packages to AppVeyor feed.
+* Update FSharp.Compiler.Service component.
+
+## 2.14.4 - 2016-06-02
+* Use `#I __SOURCE_DIRECTORY__` in the loads script (more reliable)
+
+## 2.14.3 - 2016-05-26
+* Fixes issues with comments and keywords in Paket highlighter (#408)
+* Fix tooltip flickering in CSS (#406)
+* End blockquote on a line with an empty blockquote (fix #355) (#400)
+
+## 2.14.2 - 2016-04-06
+* Add code to parse table rows correctly (#394)
+* Also fixes (#388) Markdown parser doesn't recognize inline code `x | y` inside table cell
+
+## 2.14.1 - 2016-04-05
+* Temporarily pin FSharp.Compiler.Service (#395)
+* Cache is new keyword in Paket (#392)
+
+## 2.13.6 - 2016-02-29
+* Added TypeScript to the CSharpFormat project (#386)
+
+## 2.13.5 - 2016-01-25
+* Fixes issues in PaketFormat (#381) - colorize HTTP and file prefix
+* Reliable getTypeLink (#380) - avoid crashes
 
-- Correct behaviour of '--clean'
+## 2.13.4 - 2016-01-20
+* Colors paket keywords (#379)
 
-## 5.0.4
+## 2.13.3 - 2016-01-18
+* Adds PaketFormat to not color URLs as comments in Paket files (#349)
 
-- Fix emit of odd character in latex output
+## 2.13.2 - 2016-01-12
+* Improve the load script to fix FsLab issue (https://github.com/fslaborg/FsLab/issues/98)
 
-## 5.0.3
+## 2.13.1 - 2016-01-12
+* Make logging to file optional using environment variable
 
-- Paket update and remove workaround code
-- add '--clean' to fsdocs 
+## 2.13.0 - 2015-12-29
+* Be compatible with the common-mark spec for 'Fenced code blocks' and 'Indented code blocks'.
+See https://github.com/fsprojects/FSharp.Formatting/pull/343.
+Please follow-up by adding support for more sections of the spec!
+Just add the section to https://github.com/fsprojects/FSharp.Formatting/blob/master/tests/FSharp.Markdown.Tests/CommonMarkSpecTest.fs#L20
+and fix the newly enabled tests.
+* Add CompiledName to members with F# specific naming (https://github.com/fsprojects/FSharp.Formatting/pull/372)
 
-## 5.0.2
-- Update to FCS v36.0
-- Add .ipynb output option for documents
-- Add .fsx output option for documents
-- Literate.WriteHtml --> Literate.ToHtml/Literate.WriteHtml overloads
-- MetadataFormat.Generate --> ApiDocs.GenerateHtml/ApiDocs.GenerateModel overloads
-- Fix Literate.* to do approximate (non-razor) templating/  
-- Remove Razor support
-- HTML templates now use `{{prop-name}}`
-- FSharp.CodeFormat --> FSharp.Formatting.CodeFormat
-- FSharp.Markdown --> FSharp.Formatting.Markdown
-- FSharp.Literate --> FSharp.Formatting.Literate and FSharp.Formatting.Literate.Evaluation
-- FSharp.MetadataFormat --> FSharp.Formatting.ApiDocs
-- FSharp.ApiDocs uses HTML substitution for templating, no Razor
-- Add "include-it" and "include-output" with implied reference to the immediately preceding snippet
-- For command line tool
-        Rename fsformatting to fsdocs
-        Update command line parser
-        "fsformatting literate process-directory" --> "fsdocs convert"
-        "fsformatting metadata-format generate" --> "fsdocs api"
-        "--dllFiles" --> "--dlls"
-        "--outDir" --> "--output"
-        "--outputDirectory" --> "--output"
-        "--output" is optional (defaults to 'output')
-        "--inputDirectory" --> "--input"
-        Add --nonpublic
-        Add --xmlComments
-        Automatically populate metadata from project settings.
-- Add `fsdocs build` command to the documentation generator that has lots of sensible defaults.
-
-## 4.1.0
-- Support preview F# language features.
-- Add support for customizing assigned CSS class.
-
-## 4.0.1
-- Add .NET Core support for all libraries.
-- Update to FSCS v35.0.
-- Add helpers for CustomOperationAttribute.
-
-## 4.0.0-alpha04
-- Update to FSCS v34.1.
-
-## 4.0.0-alpha03
-- Update to FSCS v34.
-
-## 4.0.0-alpha02
-- Fix packaging issues.
-
-## 4.0.0-alpha01
-- Add .NET Core support for all libraries.
-- Update to latest FSharp.Compiler.Service
-
-## 3.1.0
-- remove beta tag since it is already widely used
-
-## 3.0.0-beta14 
- - Update to latest FSharp.Compiler.Service
- - No longer filter FSHarp.Core based on optdata/sigdata (it is now always bundled)
- 
-## 3.0.0-beta13 
- - FSharp.Formatting.Literate for netstandard2.0
-
-## 3.0.0-beta12 (29, July, 2018)
- - Fix usage formatting - https://github.com/fsprojects/FSharp.Formatting/issues/472
-
-## 3.0.0-beta11 (06, May, 2018)
- - Added support for attributes on modules, types and members
- - Updated razor templates to show attributes and added a warning for obsolete API
-
-## 3.0.0-beta10 (08, April, 2018)
- - Upgrade FSharp.Compiler.Service to be compatible with FAKE 5
-
-## 3.0.0-beta09 (04, February, 2018
- - Fix some links on the website - https://github.com/fsprojects/FSharp.Formatting/pull/458
- - Another link on the website - https://github.com/fsprojects/FSharp.Formatting/pull/454
- - Support highlighting for paket.dependencies `storage` keyword - https://github.com/fsprojects/FSharp.Formatting/pull/451
- - In order to upgrade follow instructions at https://fsprojects.github.io/FSharp.Formatting/upgrade_from_v2_to_v3.html
-
-## 3.0.0-beta08 (03 December, 2017)
- - Improve Stacktrace on Script file processing
- 
-## 3.0.0-beta07 (07 August, 2017)
- - Fix System.ValueType dep.
- 
-## 3.0.0-beta06 (16 June, 2017)
- - Include razor component.
- 
-## 3.0.0-beta05 (11 June, 2017)
- - Always generate anchors when using command line tool.
- 
-## 3.0.0-beta04 (28 May, 2017)
- - Don't hide errors in fsformatting tool (Literate).
- - Improve error message by using inner exceptions.
-
-## 3.0.0-beta03 (27 May, 2017)
- - Don't hide errors in fsformatting tool.
-
-## 3.0.0-beta02 (26 May, 2017)
- - MarkdownSpan and MarkdownParagraph now use named DUs
- - Add range to MarkdownParagraph and MarkdownSpan (https://github.com/fsprojects/FSharp.Formatting/pull/411)
- - FSharp.Formatting no longer has a strong dependency on Razor (https://github.com/fsprojects/FSharp.Formatting/pull/425)
- - FSharp.Formatting no longer depends on VFPT.Core (https://github.com/fsprojects/FSharp.Formatting/pull/432)
- - Add beta packages to AppVeyor feed.
- - Update FSharp.Compiler.Service component.
-
-## 2.14.4 (3 June, 2016)
- - Use `#I __SOURCE_DIRECTORY__` in the loads script (more reliable)
-
-## 2.14.3 (26 May, 2016)
- - Fixes issues with comments and keywords in Paket highlighter (#408)
- - Fix tooltip flickering in CSS (#406)
- - End blockquote on a line with an empty blockquote (fix #355) (#400)
-
-## 2.14.2 (6 April, 2016)
- - Add code to parse table rows correctly (#394)
- - Also fixes (#388) Markdown parser doesn't recognize inline code `x | y` inside table cell
-
-## 2.14.1 (5 April, 2016)
- - Temporarily pin FSharp.Compiler.Service (#395)
- - Cache is new keyword in Paket (#392)
-
-## 2.13.6 (29 February, 2016)
- - Added TypeScript to the CSharpFormat project (#386)
-
-## 2.13.5 (25 January, 2016)
- - Fixes issues in PaketFormat (#381) - colorize HTTP and file prefix
- - Reliable getTypeLink (#380) - avoid crashes
-
-## 2.13.4 (20 January, 2016)
- - Colors paket keywords (#379)
-
-## 2.13.3 (18 January, 2016)
- - Adds PaketFormat to not color URLs as comments in Paket files (#349)
-
-## 2.13.2 (12 January, 2016)
- - Improve the load script to fix FsLab issue (https://github.com/fslaborg/FsLab/issues/98)
-
-## 2.13.1 (12 January, 2016)
- - Make logging to file optional using environment variable
-
-## 2.13.0 (30 December, 2015)
- - Be compatible with the common-mark spec for 'Fenced code blocks' and 'Indented code blocks'.
-   See https://github.com/fsprojects/FSharp.Formatting/pull/343.
-   Please follow-up by adding support for more sections of the spec!
-   Just add the section to https://github.com/fsprojects/FSharp.Formatting/blob/master/tests/FSharp.Markdown.Tests/CommonMarkSpecTest.fs#L20
-   and fix the newly enabled tests.
- - Add CompiledName to members with F# specific naming (https://github.com/fsprojects/FSharp.Formatting/pull/372)
-
-## 2.12.1 (24 December, 2015)
- - update dependencies
- - Upgrade the CommandTool to F# 4 and bundle FSharp.Core with sigdata and optdata.
- - Fix crash when a fenced code block starts with an empty line (https://github.com/fsprojects/FSharp.Formatting/pull/361)
- - Support for all known xml elements (https://github.com/fsprojects/FSharp.Formatting/pull/331)
-
-## 2.12.0 (18 October, 2015)
- - Update dependencies to be compatible with FSharp.Compiler.Service >=1.4.0.3
-
-## 2.11.1-alpha1 (14 October, 2015)
- - Adds methods for cross-type links #330 (https://github.com/fsprojects/FSharp.Formatting/pull/330)
-
-## 2.11.0 (28 September, 2015)
- - Fix https://github.com/fsprojects/FSharp.Formatting/issues/271
- - Don't fail as long as we can recover / continue.
- - Fix https://github.com/fsprojects/FSharp.Formatting/issues/201
-
-## 2.10.3 (12 September, 2015)
- - Require compatible F# Compiler Service in Nuspec (fix #337)
-
-## 2.10.2 (12 September, 2015)
- - Fix load script (wrap logging setup in try catch properly)
-
-## 2.10.1 (12 September, 2015)
- - paket update && fix compilation (#338)
- - Wrap logging setup in try catch
-
-## 2.10.0 (26 July, 2015)
- - Add detailed logging and new FSharp.Formatting.Common.dll file
- - Fix bug in C# code formatting tool (FormatHtml)
-
-## 2.9.10 (27 June, 2015)
- - Support multiple snippets in Literate.Parse (This is obsolete, but needed for www.fssnip.net.)
-
-## 2.9.9 (22 June, 2015)
- - Fix HTML escaping of code blocks with unknown languages (#321, #322)
-
-## 2.9.6 (8 May, 2015)
- - Generate 'fssnip' class for non-F# 
 tags for consistency
-
-## 2.9.5 (6 May, 2015)
- - Provide an option to disable `fsi.AddPrinter` (#311)
- - Generated line numbers for HTML are the same for F# and non-F#
-
-## 2.9.4 (30 April, 2015)
- - Use `otherFlags` parameter (#308)
- - Format code in Markdown comments (#307, #36)
-
-## 2.9.3 (29 April, 2015)
- - Simplify using FCS interaction using Yaaf.Scripting (#305)
- - Do not load dependencies when initializing evaluator
- - Undo require exact version of F# Compiler Service
-
-## 2.9.2 (24 April, 2015)
- - Require exact version of F# Compiler Service
-
-## 2.9.1 (21 April, 2015)
- - Add back RazorEngine.dll (#302)
-
-## 2.9.0 (20 April, 2015)
- - Properly encode '>' entities (#84)
- - Generate line numbers for non-F# code (#227)
- - Support headings on the same line as comment (#147)
- - Fixes in HTML encoding of non-F# code snippets (#249, #213)
- - Remove Razor mono workaround (#279)
- - Add a public API to process a customized LiterateDocument (#282)
- - Add an API to process a customized LiterateDocument (#289)
- - Use template path if it is rooted (#281)
- - Enable evaluation tests for literate scripts
- - Create `fsi` object without `FSharp.Compiler.Interactive.Settings.dll`
- - Fix #229 (Key already exists exception when parsing an assembly)
- - Update to Visual Studio 2013 (only)
- - Update LaTeX colors using CSS Light theme (#278)
-
-## 2.8.0 (and before 20 April, 2015)
-* 1.0.15 - Added latex support, tables and better formatting with line numbers
-* 2.0.0 - New project structure, adding MetadataFormat
-* 2.0.1 - Fixed handling of # in headers
-* 2.0.2 - Change tool tip font for better readability
-* 2.0.3 - Fixed Markdown escaping, nested modules and types in FsHtmlDoc
-* 2.0.4 - Support escaping in inline code
-* 2.1.0-beta - Metadata and literate formatting now support Razor, include templates in NuGet package
-* 2.1.1-beta - Fix logo in nuget package
-* 2.1.2-beta - Fix nuget package
-* 2.1.3-beta - Fix the Root property for templating
-* 2.1.4 - Includes templates, support Razor for literate templates, bugs fixed
-* 2.1.5 - Improve default templates for open-source projects
-* 2.1.6 - Improve default templates for open-source projects (again)
-* 2.2.0 - Refactor literate tools
-* 2.2.1 - Remove (now unused) error handler parameter in literate (use ParseScript instead)
-* 2.2.2 - Nicer CSS style for API reference docs
-* 2.2.3 - Better recognition of links
-* 2.2.4-beta - Experimental - get snippet from file, some evaluation stuff
-* 2.2.5-beta - Add formatting for non-fsharp code, remove indents when importing snippet
-* 2.2.6-beta - Add page-source parameter for Razor tempalting
-* 2.2.7-beta - Generate docs for some F# types, formatting improvements
-* 2.2.8-beta - Add inline Latex support (thanks to Xiang Zhang!)
-* 2.2.9-beta - Update templates, support multiple DLLs in metadata format
-* 2.2.10-beta - Avoid locking assembly files in AssemblyResolve event
-* 2.2.11-beta - Generate links to source code, change default font, move styles to styles folder in package
-* 2.2.12-beta - Better compatibility for the default font style
-* 2.3.1-beta - Using new compiler services API, improved docs
-* 2.3.2-beta - Update to FSharp.Compiler.Service v0.0.10
-* 2.3.3-beta - Update FSharp.Compiler.Service and add fsdocs-tool package
-* 2.3.4-beta - Fix dependency in NuGet package
-* 2.3.5-beta - Omit non-public members from metadata docs by default
-* 2.3.6-beta - Update documentation, fixes for Mono compatibility
-* 2.3.7-beta - Add auto-formatting for links and output sample usage for DU cases
-* 2.3.8-beta - Update FSharp.Compiler.Service to v0.0.17
-* 2.3.9-beta - Update FSharp.Compiler.Service to v0.0.20, include inherited members when the base type was ommited from the documentation, fix properties displaying as methods, fix functions with unit input rendering incorrectly
-* 2.3.10-beta - Support output embedding in literate scripts
-* 2.3.11-beta - Support output embedding in command line tool
-* 2.4.0 - Incrementing version and stop using the beta versioning
-* 2.4.1 - Support for generating docs for type providers
-* 2.4.2 - Improved static parameter support, evaluation and math mode, support XML docs
-* 2.4.3 - Fix documentation, nicer github source links template
-* 2.4.4 - Live referesh in command line
-* 2.4.5 - Include tool tips when generating HTML using WriteHtml
-* 2.4.6 - Use --quiet (by default) to avoid calling default printer
-* 2.4.7 - Report errors from FsiEvaluator and stylesheet tweaks
-* 2.4.8 - Support do-not-eval and expose StdErr from eval failed event
-* 2.4.9 - Improve LaTeX formatting and make evaluator customizable
-* 2.4.10 - Automatically wrap LaTeX code in math mode blocks
-* 2.4.11 - Improved handling of end comments and http/https links at end of lines
-* 2.4.12 - Be more flexible about URL generating, protect against exceptions, fix bugs and typos
-* 2.4.13 - Fix evaluation bug; Return characters for horizontal lines
-* 2.4.14 - Update NuGet dependencies
-* 2.4.15 - Support combination of commands (e.g. hide, define-output), add do-not-eval-file
-* 2.4.16 - Improve formatting of literate scripts (generate tables around pre)
-* 2.4.17 - Fix comment parsing when whitespace
-* 2.4.18 - Expose literate paragraph transformation
-* 2.4.19 - Update command line tool to .NET 4
-* 2.4.20 - Add operator formatting to JavaScript langauge
-* 2.4.21 - Update to the most recent F# Compiler Service
-* 2.4.22 - Require specific versions in NuGet dependencies
-* 2.4.23 - Support generation of anchors in HTML documents
-* 2.4.24 - Include stylesheet for anchors & enable this for F# Formatting docs
-* 2.4.25 - Version with fixed dependencies, released using Paket!
-* 2.4.25 - Use Razor caching to drastically improve performance.
-* 2.4.26 - Proper release after nuget incident.
-* 2.4.27 - Better mono support and new logo.
-* 2.4.28 - Fix dependencies
-* 2.4.29 - Revert
-* 2.4.30 - Fsharp.Formatting MetadataFormat no longer crashes on C# dlls
-* 2.4.31 - Basic cache for RazorRender instances in FSharp.Formatting.Literate
-* 2.4.32 - Fixed regressions introduced by latest FCS
-* 2.4.33 - Fix cache using incomplete key
-* 2.4.34 - Better C# support / Don't depend on broken FCS
-* 2.4.36 - Better mono support
-* 2.4.37 - Fixed XML file resolution, support "cref", improve XML comment parsing, better logging and C# support
-* 2.5.0 - Update to latest FSharp.Compiler.Service
-* 2.5.1 - Fix handling of codeblocks inside and after lists
-* 2.6.0 - Bundle RazorEngine and System.Web.Razor to avoid dependency clashes
-* 2.6.1 - Support for Github flavoured markdown code blocks
-* 2.6.2 - Update to a new version of RazorEngine.
-* 2.6.3 - Better handling of F# snippets with invalid Unicode characters
-* 2.7.0 - Update to .NET 4.5 and use VS Power Tools for highlighting; Support categories on namespaces; Fix newlines
-* 2.7.1 - Colorize operators in the default template
-* 2.7.2 - Improve colours and ILRepack VS Power Tools (fix #261)
-* 2.7.3 - Revert ILRepack - fails on Mono (cc #261)
-* 2.7.4 - Add simple load script for easy referencing from FSX files
-* 2.7.5 - Update to net45 (fix #266 on windows), add search path to load script, fix EntityFramework bug (#270)
-* 2.8.0 - Redesgined file caching for Razor, documentation improvements, marking some thing internal
+## 2.12.1 - 2015-12-24
+* update dependencies
+* Upgrade the CommandTool to F# 4 and bundle FSharp.Core with sigdata and optdata.
+* Fix crash when a fenced code block starts with an empty line (https://github.com/fsprojects/FSharp.Formatting/pull/361)
+* Support for all known xml elements (https://github.com/fsprojects/FSharp.Formatting/pull/331)
+
+## 2.12.0 - 2015-10-18
+* Update dependencies to be compatible with FSharp.Compiler.Service >=1.4.0.3
+
+## 2.11.1-alpha1 - 2015-10-14
+* Adds methods for cross-type links #330 (https://github.com/fsprojects/FSharp.Formatting/pull/330)
+
+## 2.11.0 - 2015-09-28
+* Fix https://github.com/fsprojects/FSharp.Formatting/issues/271
+* Don't fail as long as we can recover / continue.
+* Fix https://github.com/fsprojects/FSharp.Formatting/issues/201
+
+## 2.10.3 - 2015-09-12
+* Require compatible F# Compiler Service in Nuspec (fix #337)
+
+## 2.10.2 - 2015-09-11
+* Fix load script (wrap logging setup in try catch properly)
+
+## 2.10.1 - 2015-09-11
+* paket update && fix compilation (#338)
+* Wrap logging setup in try catch
+
+## 2.10.0 - 2015-07-26
+* Add detailed logging and new FSharp.Formatting.Common.dll file
+* Fix bug in C# code formatting tool (FormatHtml)
+
+## 2.9.10 - 2015-06-27
+* Support multiple snippets in Literate.Parse (This is obsolete, but needed for www.fssnip.net.)
+
+## 2.9.9 - 2015-06-22
+* Fix HTML escaping of code blocks with unknown languages (#321, #322)
+
+## 2.9.6 - 2015-05-08
+* Generate 'fssnip' class for non-F# 
 tags for consistency
+
+## 2.9.5 - 2015-05-06
+* Provide an option to disable `fsi.AddPrinter` (#311)
+* Generated line numbers for HTML are the same for F# and non-F#
+
+## 2.9.4 - 2015-04-30
+* Use `otherFlags` parameter (#308)
+* Format code in Markdown comments (#307, #36)
+
+## 2.9.3 - 2015-04-28
+* Simplify using FCS interaction using Yaaf.Scripting (#305)
+* Do not load dependencies when initializing evaluator
+* Undo require exact version of F# Compiler Service
+
+## 2.9.2 - 2015-04-24
+* Require exact version of F# Compiler Service
+
+## 2.9.1 - 2015-04-21
+* Add back RazorEngine.dll (#302)
+
+## 2.9.0 - 2015-04-20
+* Properly encode '>' entities (#84)
+* Generate line numbers for non-F# code (#227)
+* Support headings on the same line as comment (#147)
+* Fixes in HTML encoding of non-F# code snippets (#249, #213)
+* Remove Razor mono workaround (#279)
+* Add a public API to process a customized LiterateDocument (#282)
+* Add an API to process a customized LiterateDocument (#289)
+* Use template path if it is rooted (#281)
+* Enable evaluation tests for literate scripts
+* Create `fsi` object without `FSharp.Compiler.Interactive.Settings.dll`
+* Fix #229 (Key already exists exception when parsing an assembly)
+* Update to Visual Studio 2013 (only)
+* Update LaTeX colors using CSS Light theme (#278)
diff --git a/build.fsx b/build.fsx
index 747b352c7..91b9daff3 100644
--- a/build.fsx
+++ b/build.fsx
@@ -1,13 +1,13 @@
 #r "nuget: Fun.Build, 0.3.8"
-#r "nuget: Fake.Core.ReleaseNotes, 6.0.0"
-#r "nuget: Fake.DotNet.AssemblyInfoFile, 6.0.0"
+#r "nuget: Fake.IO.FileSystem, 6.0.0"
+#r "nuget: Ionide.KeepAChangelog, 0.1.8"
 
-open System.Xml.Linq
-open Fake.Core
-open Fake.DotNet
+open System.IO
 open Fake.IO.Globbing.Operators
 open Fake.IO.FileSystemOperators
 open Fake.IO
+open Ionide.KeepAChangelog
+open Ionide.KeepAChangelog.Domain
 open Fun.Build
 
 let root = __SOURCE_DIRECTORY__
@@ -29,7 +29,13 @@ let artifactsDir = root @@ "artifacts"
 let fsdocTool = artifactsDir @@ "fsdocs"
 
 // Read release notes document
-let release = ReleaseNotes.load "RELEASE_NOTES.md"
+let releaseNugetVersion, _, _ =
+    let changeLog = FileInfo(__SOURCE_DIRECTORY__  "RELEASE_NOTES.md")
+
+    match Parser.parseChangeLog changeLog with
+    | Error(msg, error) -> failwithf "%s msg\n%A" msg error
+    | Ok result -> result.Releases |> List.head
+
 let solutionFile = "FSharp.Formatting.sln"
 
 pipeline "CI" {
@@ -38,33 +44,6 @@ pipeline "CI" {
         run $"dotnet fantomas {__SOURCE_FILE__} src tests docs --check"
     }
 
-    stage "AssemblyInfo" {
-        // Generate assembly info files with the right version & up-to-date information
-        run (fun _ ->
-            let info =
-                [ AssemblyInfo.Product project
-                  AssemblyInfo.Description summary
-                  AssemblyInfo.Version release.AssemblyVersion
-                  AssemblyInfo.FileVersion release.AssemblyVersion
-                  AssemblyInfo.InformationalVersion release.NugetVersion
-                  AssemblyInfo.Copyright license ]
-
-            AssemblyInfoFile.createFSharp "src/Common/AssemblyInfo.fs" info
-            AssemblyInfoFile.createCSharp "src/Common/AssemblyInfo.cs" info
-
-            let versionProps =
-                XElement(
-                    XName.Get "Project",
-                    XElement(
-                        XName.Get "PropertyGroup",
-                        XElement(XName.Get "Version", release.NugetVersion),
-                        XElement(XName.Get "PackageReleaseNotes", String.toLines release.Notes)
-                    )
-                )
-
-            versionProps.Save("version.props"))
-    }
-
     stage "Clean" {
         run (fun _ ->
             !!artifactsDir ++ "temp" |> Shell.cleanDirs
@@ -91,7 +70,7 @@ pipeline "CI" {
         // Τhe tool has been uninstalled when the
         // artifacts folder was removed in the Clean stage.
         run
-            $"dotnet tool install --no-cache --version %s{release.NugetVersion} --add-source \"%s{artifactsDir}\" --tool-path \"%s{artifactsDir}\" fsdocs-tool"
+            $"dotnet tool install --no-cache --version %A{releaseNugetVersion} --add-source \"%s{artifactsDir}\" --tool-path \"%s{artifactsDir}\" fsdocs-tool"
 
         run $"\"{fsdocTool}\" build --strict --clean --properties Configuration=Release"
         run $"dotnet tool uninstall fsdocs-tool --tool-path \"%s{artifactsDir}\""

From de3a20c3edd002628a1990523a07952c8fdb1150 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Fri, 3 Nov 2023 13:01:56 +0100
Subject: [PATCH 26/71] Remove previously generated file.

---
 src/FSharp.Formatting.ApiDocs/FSharp.Formatting.ApiDocs.fsproj | 3 ---
 .../FSharp.Formatting.CodeFormat.fsproj                        | 3 ---
 src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj   | 1 -
 .../FSharp.Formatting.Literate.fsproj                          | 3 ---
 .../FSharp.Formatting.Markdown.fsproj                          | 3 ---
 src/fsdocs-tool/fsdocs-tool.fsproj                             | 3 ---
 6 files changed, 16 deletions(-)

diff --git a/src/FSharp.Formatting.ApiDocs/FSharp.Formatting.ApiDocs.fsproj b/src/FSharp.Formatting.ApiDocs/FSharp.Formatting.ApiDocs.fsproj
index de05efa8f..1255480ce 100644
--- a/src/FSharp.Formatting.ApiDocs/FSharp.Formatting.ApiDocs.fsproj
+++ b/src/FSharp.Formatting.ApiDocs/FSharp.Formatting.ApiDocs.fsproj
@@ -4,9 +4,6 @@
     netstandard2.1
   
   
-    
-      Common\AssemblyInfo.fs
-    
     
       Common\Collections.fs
     
diff --git a/src/FSharp.Formatting.CodeFormat/FSharp.Formatting.CodeFormat.fsproj b/src/FSharp.Formatting.CodeFormat/FSharp.Formatting.CodeFormat.fsproj
index d52fc8314..b6a901eea 100644
--- a/src/FSharp.Formatting.CodeFormat/FSharp.Formatting.CodeFormat.fsproj
+++ b/src/FSharp.Formatting.CodeFormat/FSharp.Formatting.CodeFormat.fsproj
@@ -4,9 +4,6 @@
     netstandard2.1
   
   
-    
-      Common\AssemblyInfo.fs
-    
     
       Common\Collections.fs
     
diff --git a/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj b/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj
index 581241b74..a51b21bac 100644
--- a/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj
+++ b/src/FSharp.Formatting.Common/FSharp.Formatting.Common.fsproj
@@ -6,7 +6,6 @@
     true
   
   
-    
     
     
     
diff --git a/src/FSharp.Formatting.Literate/FSharp.Formatting.Literate.fsproj b/src/FSharp.Formatting.Literate/FSharp.Formatting.Literate.fsproj
index e5aaeeaed..fda3ea260 100644
--- a/src/FSharp.Formatting.Literate/FSharp.Formatting.Literate.fsproj
+++ b/src/FSharp.Formatting.Literate/FSharp.Formatting.Literate.fsproj
@@ -5,9 +5,6 @@
     true
   
   
-    
-      Common\AssemblyInfo.fs
-    
     
       Common\Collections.fs
     
diff --git a/src/FSharp.Formatting.Markdown/FSharp.Formatting.Markdown.fsproj b/src/FSharp.Formatting.Markdown/FSharp.Formatting.Markdown.fsproj
index 51e8c0e40..2a91fe9b9 100644
--- a/src/FSharp.Formatting.Markdown/FSharp.Formatting.Markdown.fsproj
+++ b/src/FSharp.Formatting.Markdown/FSharp.Formatting.Markdown.fsproj
@@ -4,9 +4,6 @@
     netstandard2.1
   
   
-    
-      Common\AssemblyInfo.fs
-    
     
       Common\Collections.fs
     
diff --git a/src/fsdocs-tool/fsdocs-tool.fsproj b/src/fsdocs-tool/fsdocs-tool.fsproj
index 603eec50e..f30c81c08 100644
--- a/src/fsdocs-tool/fsdocs-tool.fsproj
+++ b/src/fsdocs-tool/fsdocs-tool.fsproj
@@ -16,9 +16,6 @@
   
     
   
-    
-      Common\AssemblyInfo.fs
-    
     
     
     

From 3a25f3c8f9707a481566294cd726291087bf7e43 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Fri, 3 Nov 2023 13:09:53 +0100
Subject: [PATCH 27/71] Add action to trigger nuget push.

---
 .github/workflows/modern-theme.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/modern-theme.yml b/.github/workflows/modern-theme.yml
index 52703ef7f..b7ce69956 100644
--- a/.github/workflows/modern-theme.yml
+++ b/.github/workflows/modern-theme.yml
@@ -1,4 +1,4 @@
-name: Modern theme
+name: Build and Test and Publish (main)
 
 on: workflow_dispatch
 

From 47810cacb37a191d780a0d3eacdf0b13d5091a4c Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Fri, 3 Nov 2023 14:46:00 +0100
Subject: [PATCH 28/71] Only add {{root}} in extra templates.

---
 src/fsdocs-tool/BuildCommand.fs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/fsdocs-tool/BuildCommand.fs b/src/fsdocs-tool/BuildCommand.fs
index 5c578688f..fcf5ff7b6 100644
--- a/src/fsdocs-tool/BuildCommand.fs
+++ b/src/fsdocs-tool/BuildCommand.fs
@@ -1702,6 +1702,7 @@ type CoreBuildOptions(watch) =
                         ""
                     else
                         File.ReadAllText headTemplatePath
+                        |> SimpleTemplating.ApplySubstitutionsInText [ ParamKeys.root, root ]
 
                 let bodyTemplateContent =
                     let bodyTemplatePath = Path.Combine(this.input, "_body.html")
@@ -1710,6 +1711,7 @@ type CoreBuildOptions(watch) =
                         ""
                     else
                         File.ReadAllText bodyTemplatePath
+                        |> SimpleTemplating.ApplySubstitutionsInText [ ParamKeys.root, root ]
 
                 let results =
                     Map.ofList

From 25c1e1d08c3513058552398afbbf532728c533c5 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Fri, 3 Nov 2023 15:04:56 +0100
Subject: [PATCH 29/71] Add changelog entry for alpha 2

---
 RELEASE_NOTES.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 951551ea9..7202066ee 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,5 +1,10 @@
 # Changelog
 
+## 20.0.0-alpha-002 - 2023-11-03
+
+### Fixed
+* `{{root}}` is now available as substitution in `_body.html` and `_head.html`.
+
 ## 20.0.0-alpha-001 - 2023-11-03
 
 ### Removed

From c4eb60600dd9502ac37c388a90b6fd5f03e44933 Mon Sep 17 00:00:00 2001
From: nojaf 
Date: Sat, 4 Nov 2023 14:21:26 +0100
Subject: [PATCH 30/71] Move 'On this page' section outside main element.

---
 docs/_template.html             | 10 +++---
 docs/content/fsdocs-default.css | 63 ++++++++++++++++-----------------
 docs/content/fsdocs-theme.js    | 16 +++++++--
 3 files changed, 49 insertions(+), 40 deletions(-)

diff --git a/docs/_template.html b/docs/_template.html
index b9ba28a52..b9a0a5da5 100644
--- a/docs/_template.html
+++ b/docs/_template.html
@@ -47,7 +47,7 @@
         
     
 
-