diff --git a/FSharp.Formatting.sln b/FSharp.Formatting.sln index 72251a3cf..20bdb03f1 100644 --- a/FSharp.Formatting.sln +++ b/FSharp.Formatting.sln @@ -20,6 +20,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "project", "project", "{194B EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{312E452A-1068-4804-89E7-0AFBAD5F885F}" ProjectSection(SolutionItems) = preProject + docs\_body.html = docs\_body.html docs\_template.html = docs\_template.html docs\apidocs.fsx = docs\apidocs.fsx docs\codeformat.fsx = docs\codeformat.fsx @@ -29,6 +30,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{312E452A-1 docs\index.md = docs\index.md docs\literate.fsx = docs\literate.fsx docs\markdown.fsx = docs\markdown.fsx + docs\mermaid.md = docs\mermaid.md docs\styling.md = docs\styling.md docs\upgrade.md = docs\upgrade.md docs\users.md = docs\users.md diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 92ff6502e..3e1b18091 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,5 +1,10 @@ # Changelog +## [Unreleased] + +### Changed +* Rewrote the Mermaid documentation recipe as `docs/mermaid.md` (moved from the oddly-named `docs/sidebyside/sidemermaid.md`) to follow the approach used by the fantomas docs: diagrams are written as plain ```mermaid fenced code blocks, which GitHub renders natively, and an `_body.html` script promotes those blocks into `
` elements on fsdocs pages. The FSharp.Formatting docs now ship that script (`docs/_body.html`), so the recipe page actually demonstrates working diagrams. + ## [22.2.0] - 2026-08-31 ### Changed diff --git a/build.fsx b/build.fsx index dad4ce3db..e7c3c8803 100755 --- a/build.fsx +++ b/build.fsx @@ -110,4 +110,11 @@ pipeline "Verify" { runIfOnlySpecified true } +// Start the documentation site in watch mode with the locally built fsdocs tool. +// Runs until interrupted (Ctrl+C); the site is served on http://localhost:8901. +pipeline "Docs" { + stage "WatchDocs" { run "dotnet run --project src/fsdocs-tool -- watch" } + runIfOnlySpecified true +} + tryPrintPipelineCommandHelp () diff --git a/docs/_body.html b/docs/_body.html new file mode 100644 index 000000000..8413ae22e --- /dev/null +++ b/docs/_body.html @@ -0,0 +1,23 @@ + diff --git a/docs/content/fsdocs-theme.css b/docs/content/fsdocs-theme.css index cd0e6a975..3b1b78ce2 100644 --- a/docs/content/fsdocs-theme.css +++ b/docs/content/fsdocs-theme.css @@ -1 +1,9 @@ -/* Override any variables here */ \ No newline at end of file +/* Override any variables here */ + +.mermaid { + margin: 1rem auto; + & svg { + display: block; + margin: 0 auto; + } +} \ No newline at end of file diff --git a/docs/mermaid.md b/docs/mermaid.md new file mode 100644 index 000000000..ef11afb23 --- /dev/null +++ b/docs/mermaid.md @@ -0,0 +1,112 @@ +--- +title: Mermaid Diagrams +category: Examples +categoryindex: 2 +index: 4 +--- +# Example: Mermaid Diagrams + +[Mermaid](https://mermaid.js.org/) is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions into diagrams. + +The recommended way to use Mermaid with fsdocs is to write diagrams as plain fenced code blocks, and add a small script that turns those blocks into diagrams when the page loads. The Markdown stays portable: GitHub renders ` ```mermaid ` fences natively, and your fsdocs site shows the real diagrams. This very page uses the pattern below, so the diagrams you see are fenced code blocks promoted by a `_body.html` script. + +## Setup + +Create or edit a `_body.html` file in your `docs` folder. fsdocs injects it at the end of every page, after the content. The script imports mermaid and promotes fenced mermaid blocks to the `
` elements mermaid looks for: + +````html + +```` + +## Usage + +Write your diagram in a fenced code block with the `mermaid` language tag: + +````text +```mermaid +graph LR + A[Input docs] --> B[fsdocs build] + B --> C[HTML output] + B --> D[API reference] +``` +```` + +On this site, the block above is rendered as: + +```mermaid +graph LR + A[Input docs] --> B[fsdocs build] + B --> C[HTML output] + B --> D[API reference] +``` + +## More Examples + +Sequence diagram: + +```mermaid +sequenceDiagram + participant User + participant fsdocs + participant Browser + User->>fsdocs: dotnet fsdocs watch + fsdocs-->>Browser: Serve docs + User->>fsdocs: Edit .md or .fsx + fsdocs-->>Browser: Reload page +``` + +Class diagram: + +```mermaid +classDiagram + class ApiDocComment { + +Summary: string + +Remarks: string option + +Parameters: ApiDocSection list + } + class ApiDocMember { + +Name: string + +Comment: ApiDocComment + } + ApiDocMember --> ApiDocComment +``` + +## Tips + +- To customise the Mermaid theme, pass options to `mermaid.initialize()`, for example `theme: "base"` together with `themeVariables`. +- To centre the diagrams, add a rule for the promoted element to your `docs/content/fsdocs-theme.css`: + +```css +.mermaid { + margin: 1rem auto; + & svg { + display: block; + margin: 0 auto; + } +} +``` + +- You can also write `
` blocks directly in your Markdown. The promotion script only touches fenced code blocks, so both forms can coexist. +- See the [Mermaid documentation](https://mermaid.js.org/intro/) for the full list of supported diagram types. diff --git a/docs/sidebyside/sidemermaid.md b/docs/sidebyside/sidemermaid.md deleted file mode 100644 index bd51178c3..000000000 --- a/docs/sidebyside/sidemermaid.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Mermaid Diagrams -category: Examples -categoryindex: 2 -index: 4 ---- - -# Example: Mermaid Diagrams - -[Mermaid](https://mermaid.js.org/) is a JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions into diagrams. - -## Setup - -Add the Mermaid JavaScript library to your site by creating or editing a `_head.html` file in your `docs` folder: - -```html - -``` - -## Usage - -To embed a Mermaid diagram, wrap your Mermaid syntax in a `
` element with the `mermaid` CSS class: - -```html -
-graph LR - A[Input docs] --> B[fsdocs build] - B --> C[HTML output] - B --> D[API reference] -
-``` - -This renders as: - -
-graph LR - A[Input docs] --> B[fsdocs build] - B --> C[HTML output] - B --> D[API reference] -
- -## More Examples - -Sequence diagram: - -
-sequenceDiagram - participant User - participant fsdocs - participant Browser - User->>fsdocs: dotnet fsdocs watch - fsdocs-->>Browser: Serve docs - User->>fsdocs: Edit .md or .fsx - fsdocs-->>Browser: Reload page -
- -Class diagram: - -
-classDiagram - class ApiDocComment { - +Summary: string - +Remarks: string option - +Parameters: ApiDocSection list - } - class ApiDocMember { - +Name: string - +Comment: ApiDocComment - } - ApiDocMember --> ApiDocComment -
- -## Tips - -- You can also use `
` to centre the diagram on the page. -- To customise the Mermaid theme, pass options to `mermaid.initialize()` before the `import` call. -- See the [Mermaid documentation](https://mermaid.js.org/intro/) for the full list of supported diagram types.