feat: Detect comment syntax

[thompson-tomo]

I noticed that the syntax option is not documented. While writing the doc and checking the implementation the opportunity to streamline the implementation was identified. This streamlining helps with the documentation.

The changes are:

• syntax defaults to being detected based on file extension
• Syntax options now match syntax type ie html, jsx with determination occurring during filesystem scanning.

the benefit is we can support mixed environments ie mdx & md within the same workspace.

[Copilot]

Pull request overview

This PR updates doctoc’s comment “syntax” handling so comment markers can be detected per file (based on extension) during filesystem scanning, enabling mixed .md (HTML comments) and .mdx (JSX comments) documents in the same run. It also documents the --syntax option and adjusts/extends test fixtures around stdout and MDX coverage.

Changes:

• Detect and carry per-file syntax (html vs jsx) during file discovery, and pass it through to transform/content generation.
• Normalize syntax defaults and aliases (md→html, mdx→jsx) in transform/content generation and expand supported --syntax values.
• Add fixtures/tests for MDX and for --stdout behavior with directories.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
doctoc.js	Switches to per-file syntax (x.syntax) and adjusts --stdout directory handling + supported syntax list.
lib/file.js	Adds syntax mapping by extension and includes syntax on discovered file entries; moves ~ expansion into this module.
lib/transform.js	Defaults syntax to html and maps legacy aliases; updates marker detection to use html/jsx.
lib/content-generation.js	Renames comment type keys to html/jsx and maps legacy aliases in helpers.
README.md	Documents the --syntax option and supported values/aliases.
test/transform-stdout.js	Adds a --stdout test for a directory containing a single file and updates failure messaging.
test/transform-dryrun.js	Adds MDX coverage for dryrun/update-only and for non-dryrun execution.
test/fixtures/valid_stdout/readme.md	New fixture directory for --stdout directory-with-one-file behavior.
test/fixtures/invalid_stdout/content.md	New fixture directory for --stdout directory-with-multiple-files rejection.
test/fixtures/stdout_trace.log	Updates expected trace output to match new logging text.
test/fixtures/readme-with-custom-title.mdx	Adds an MDX fixture using JSX-style doctoc markers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thompson-tomo]

@AndrewSouthpaw here is another cli option which wasn't documented and by documenting it i discovered it was confusing. 😂

[AndrewSouthpaw]

Nice refactor overall — auto-detecting syntax from extensions and supporting mixed .md/.mdx workspaces is a solid improvement. A few issues below, one of which is a correctness bug.

[AndrewSouthpaw]

The md→html / mdx→jsx aliasing is now scattered across three files (here in commentedBlock, escapedStartTag, plus transform.js). Each call-site independently maps the aliases, and one was already missed (file.js filtering — see other comment).

Consider normalizing once at the entry point (either in doctoc.js before passing to findMarkdownFiles, or in a shared helper) so downstream code only ever sees 'html' or 'jsx'. That would let you delete these guards and the ones in transform.js.

[thompson-tomo]

Won't it be a breaking change if it is only normalized at entrypoint? Hence have normalized it using a helper.

[AndrewSouthpaw]

When the target is a single file, no syntax filtering is applied — the file is always returned regardless of --syntax. In directory mode, files are filtered by syntax. This means doctoc file.md --syntax jsx processes the file with JSX comments (wrong comment style for .md), but doctoc dir/ --syntax jsx correctly skips .md files. That seems unexpected.

[thompson-tomo]

Hmm, this was the previous behaviour before refactor. I have updated the readme to improve clarity.

[AndrewSouthpaw]

One last thing: test/file.js tests pass despite the filtering bug

The tests in test/file.js hit the broken code path but pass anyway because of [].every():

findMarkdownFiles(fixturesDir, 'md').every((file) => file.path.endsWith(".md"))

[].every(pred) returns true, so it always passes.

Also the third test says "undefined syntax" but passes 'md' — copy-paste error.

Can you clean these up while you're here?

[thompson-tomo]

@AndrewSouthpaw can you take another look as i think i have implemented all your feedback.

[AndrewSouthpaw]

Good progress — the normalizeSyntax helper fixes the filtering bug and centralization is cleaner. A few remaining items.

[AndrewSouthpaw]

test/file.js — the syntax=md and syntax=mdx tests still use .every() without a length check. Same pattern that masked the original bug. Now that filtering works they won't be empty, but a future regression would silently pass again with zero results. The undefined syntax test was properly fixed — worth applying the same length > 0 assertion to the other two.