allow embedding resources in fsdocs convert html files

[nhirschey]

This is related to #1019, but I'm putting it in a separate issue to not hold that PR up.

With the proposed fsdocs convert function there's no easy way to pass my existing _template.html file (or the default fsdocs template) to the new fsdocs convert command without errors because the template relies on external css/js content. It would be nice to have functionality similar to pandocs --embed-resources command, so we could easily get the output on the right rather than the output on the left.

Proposal for commands:

// no external dependencies using the default FSharp.Formatting _template.html file as the basis
// this is useful if you want to use the fsdocs tool outside the "docs" structure where you might not have
// a _template.html file. Or if you are using the default tempate, 
// you do not have a _template.html file in your docs folder
fsdocs convert file.fsx --output file.html --template fsdocs --embed-resources

// no external dependencies using the site's customized _template.html file as the basis
fsdocs convert file.fsx --output file.html --template _template.html --embed-resources

The idea for these embed-resources output is that the output html should embed all the template's CSS and JS inline
and produce a single HTML file that renders correctly without companion files.

Key Changes from the Default Template

• Inline all CSS/JS from the content/ directory into <style> and <script> tags instead of /<script src> references
• Remove features irrelevant to single-file output: search, sidebar navigation, page menu
• Remove unsubstituted {{}} template variables that are not substituted by fsdocs convert.
• Keep: theme toggle, syntax highlighting, tooltips, copy buttons, responsive layout

[github-actions]

🤖 This is an automated response from Repo Assist.

Great feature request! The --embed-resources idea maps cleanly onto the pandoc model and would make fsdocs convert genuinely useful for sharing standalone documents or embedding them into other workflows.

Dependency: this feature sits on top of PR #1019 (the fsdocs convert command itself), so it will need to follow once that PR lands.

Implementation sketch:

Once fsdocs convert has produced the HTML from the processed script, a post-processing pass with --embed-resources would:

1. Parse the output HTML – scan for (link rel="stylesheet" href="...") and (script src="...") tags that point to local files.
2. Inline CSS – replace each (link rel="stylesheet" href="path/to/file.css") with (style)/* contents of file.css */(/style).
3. Inline JS – replace each (script src="path/to/file.js")(/script) with (script)/* contents of file.js */(/script).
4. Inline local images – replace (img src="path/to/img.png") (local paths only) with `(img src="(redacted)

The path resolution should be relative to the template directory (or the generated file's location), matching the same base that fsdocs build uses when copying the content/ directory.

Notes:

• Remote URLs ((redacted)) can be left as-is or optionally fetched — I'd suggest leaving them as-is by default, or adding a separate --embed-remote flag later.
• The default fsdocs template references several CSS/JS files from content/ (loaded relative to the output), so the path resolution logic needs to be consistent with how the template references those files.
• The resulting file will be significantly larger but truly self-contained — a good trade-off for the "share a single file" use case.

The proposed CLI design (--template fsdocs / --template _template.html + --embed-resources) looks sensible. If there's a preference to default to the built-in template when no _template.html exists in the project, a --template fsdocs flag as a special sentinel value makes that discoverable.

Generated by Repo Assist · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@10f087607af87e4e89439161f1e5d4724235f396

[dsyme]

@nhirschey Should --embed-resources just be the default?

[github-actions]

🤖 This is an automated response from Repo Assist.

@dsyme Reasonable case for yes — for fsdocs convert specifically the most natural mental model is "give me a single self-contained file I can send/share/embed", so breaking output that silently references missing CSS/JS would be more surprising than a slightly larger self-contained file.

A few considerations for making it the default:

For defaulting to embedded:

• fsdocs convert doesn't copy a content/ directory alongside the output, so the default non-embedded HTML would typically be broken unless the user manually serves it from the right directory
• The "share one file" use case is the whole point of convert vs build
• Pandoc made the same choice for their --embed-resources equivalent

For keeping it opt-in:

• Power users building a collection of converted files might want to share one content/ folder across all outputs
• Larger files by default

My suggestion: default to embedding for fsdocs convert (opposite of fsdocs build), and provide --no-embed-resources as the opt-out. The "broken by default" outcome for the non-embedding case is a stronger argument than the file-size concern.

Generated by Repo Assist · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5

[dsyme]

/repo-assist go for it, let's see a prototype PR

[github-actions]

Pull request created: #1072

Generated by Repo Assist

[github-actions]

🤖 This is an automated response from Repo Assist.

Done! A prototype PR is on its way — it implements the self-contained HTML output as discussed.

What the PR does:

• --embed-resources is on by default for HTML output when a template is used — all local CSS, JS, and images are inlined into the output file so it renders correctly when opened directly in a browser or shared as an attachment.
• --template fsdocs new sentinel value: reads the built-in default template from the embedded assembly resource, so you don't need a local _template.html.
• --no-embed-resources opt-out flag to keep external references (original behaviour).

Usage:

# Self-contained file with built-in styling — no companion files needed
fsdocs convert my-script.fsx --template fsdocs

# Custom template with auto-embedding (default)
fsdocs convert my-script.fsx --template _template.html

# Opt out
fsdocs convert my-script.fsx --template _template.html --no-embed-resources

The implementation is a regex-based HTML post-processor that runs after Literate.ConvertXxxFile writes the output. Remote URLs (Google Fonts, CDN icons, etc.) are left as external links — only local file paths are inlined. All 499 existing tests pass.

A couple of known rough edges for this prototype: the regex approach is simple and doesn't handle all edge cases (an HTML parser would be more robust); and remote resources (fonts, CDN icons) aren't fetched. Happy to iterate based on feedback.

Generated by Repo Assist for issue #1068 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@8e6d7c86bba37371d2d0eee1a23563db3e561eb5

[nhirschey]

@dsyme yes, I do think --embed-resources is the right default for this command. It’s what I had in mind when raising the original issue, to help debug presentation/output/styling of a single page without having to build everything.