[Repo Assist] Add dotnet fsdocs convert command for single-file conversion

[github-actions]

🤖 This PR was created by Repo Assist, an automated AI assistant.

Closes #811

Summary

This adds a new convert verb to the fsdocs CLI tool, enabling conversion of a single .md, .fsx, or .ipynb file to HTML (or another output format) without needing to build a full documentation site.

Usage examples:

# Convert a markdown file to HTML (output: doc.html in current directory)
dotnet fsdocs convert --input doc.md

# Convert an F# script to HTML with a specific output path
dotnet fsdocs convert --input script.fsx --output script.html

# Convert a notebook to HTML using a custom template
dotnet fsdocs convert --input notebook.ipynb --template _template.html

# Convert to another format
dotnet fsdocs convert --input doc.md --outputformat latex

# Evaluate F# code while converting
dotnet fsdocs convert --input demo.fsx --eval

# Add line numbers
dotnet fsdocs convert --input script.fsx --linenumbers

# Pass extra substitution parameters
dotnet fsdocs convert --input doc.md --parameters fsdocs-title "My Doc"

Changes

• src/FSharp.Formatting.Literate/Literate.fs: Added Literate.ConvertPynbFile public API method (parallel to the existing ConvertMarkdownFile and ConvertScriptFile)
• src/fsdocs-tool/BuildCommand.fs: Added ConvertCommand class with [(Verb("convert"))]
• src/fsdocs-tool/Program.fs: Registered ConvertCommand in the entry point
• RELEASE_NOTES.md: Added changelog entry

Options

Option	Default	Description
--input	(required)	Input file (.md, .fsx, .ipynb)
--output	(basename).(ext)	Output file path
--template	(none)	Template file (raw content written if omitted)
--outputformat	html	Output format: html, ipynb, latex, fsx, markdown
--eval	false	Evaluate F# fragments
--linenumbers	false	Add line numbers
--parameters		Extra substitution key-value pairs

When no template is provided, raw HTML content is written (just the body, no surrounding page chrome) — the same behaviour as calling Literate.ConvertMarkdownFile with no template.

Root Cause

The Literate library already exposed ConvertMarkdownFile and ConvertScriptFile for programmatic use, and the DocContent class inside the build command already performs per-file conversion. This PR wires those existing capabilities up to a new CLI verb and adds the missing ConvertPynbFile method.

Test Status

• ✅ Build succeeded (0 errors, warnings only for pre-existing System.Drawing.Common vulnerability)
• ✅ All 381 tests pass (192 Markdown, 101 Literate, 68 ApiDocs, 20 CodeFormat)
• ✅ Code formatted with Fantomas

Generated by Repo Assist for issue #811

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@b87234850bf9664d198f28a02df0f937d0447295. View source at https://github.com/githubnext/agentics/tree/b87234850bf9664d198f28a02df0f937d0447295/workflows/repo-assist.md.

[nojaf]

/repo-assist it might be time to split these commands up to multiple files.

[dsyme]

Yup these "/repo-assist" in PR comments still not working

[dsyme]

Handling this in s a separate issue #1022

[dsyme]

/repo-assist Add comprehensive unit tests for all new code and integration tests for all new features

[github-actions]

Commit pushed: b5e1d1a

Generated by Repo Assist

[github-actions]

🤖 This is an automated response from Repo Assist.

I've added comprehensive unit tests and integration tests for the new code in this PR. All 10 new tests pass. Here's a summary of what was added:

Unit tests for Literate.ConvertPynbFile (in LiterateTests.fs)

Test	Covers
ConvertPynbFile converts notebook to HTML without template	Basic HTML output from .ipynb
ConvertPynbFile converts notebook to HTML with template	HTML output with template substitution
ConvertPynbFile converts notebook to Markdown output kind	OutputKind.Markdown
ConvertPynbFile converts notebook to FSX output kind	OutputKind.Fsx

Integration tests for ConvertCommand.Execute() (in DocContentTests.fs)

Test	Covers
ConvertCommand converts .md file to HTML	.md → HTML via CLI command
ConvertCommand converts .fsx file to HTML	.fsx → HTML via CLI command
ConvertCommand converts .ipynb file to HTML	.ipynb → HTML via CLI command
ConvertCommand converts .md file to Markdown output format	--outputformat markdown
ConvertCommand returns error code for non-existent input file	Error handling: missing file returns exit code 1
ConvertCommand returns error code for unsupported file extension	Error handling: .html input returns exit code 1

Generated by Repo Assist for issue #1019

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@f2c5cf1e4af58e09a93ba0703c6bf084711b265f. View source at https://github.com/githubnext/agentics/tree/f2c5cf1e4af58e09a93ba0703c6bf084711b265f/workflows/repo-assist.md.

[dsyme]

/repo-assist I tried this out and it worked OK. However note how pandoc has this:

pandoc notebook.ipynb -s -o notebook.html

where fsdocs convert has the longer

fsdocs convert --input build.fsx --output build.md --outputformat markdown

I'd like to see more like

fsdocs convert build.fsx -o build.md 

where

• input is positional
• output format is implicit from output extension if not overridden and detectable
• -o and other shorthands for arguments

Also I'd like to see the "Integration tests for ConvertCommand" moved to a set of tests for fsdocs-tool so maybe fsdocs-tool.Tests new assembly if that makes sense

[github-actions]

Commit pushed: be17647

Generated by Repo Assist

[github-actions]

🤖 This is an automated response from Repo Assist.

Thanks for the feedback! I've pushed an update to this PR with the CLI UX improvements you requested:

Changes made:

1. Positional input — the input file is now a positional argument (index 0), so you can write:

   fsdocs convert notebook.ipynb -o notebook.html
   

   instead of --input notebook.ipynb.

2. -o shorthand — --output now also accepts -o.

3. Output format inferred from extension — when --outputformat is not specified, the format is inferred from the -o file extension:

   • .html / .htm → html
   • .md → markdown
   • .ipynb → ipynb
   • .tex → latex
   • .fsx → fsx

   So fsdocs convert build.fsx -o build.md automatically produces Markdown output.

4. New fsdocs-tool.Tests project — the ConvertCommand integration tests have been moved from FSharp.Literate.Tests/DocContentTests.fs to a new tests/fsdocs-tool.Tests/ project. An additional test covers the format inference from extension.

All 7 new tests pass, and the existing 105 Literate tests still pass.

Generated by Repo Assist for issue #1019

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@f2c5cf1e4af58e09a93ba0703c6bf084711b265f. View source at https://github.com/githubnext/agentics/tree/f2c5cf1e4af58e09a93ba0703c6bf084711b265f/workflows/repo-assist.md.

[nojaf]

Hi @nhirschey, would you mind giving this a spin?