Hi, I would like to point out a potential problem with pre-commit usage of doctoc. Since doctoc always updates files, which contain any headings, regardless of changes since the last run, it will always modify files and cause the pre-commit hook to fail and revert the changes.

This makes, in my opinion, doctoc unusable as a pre-commit hook as is, since it will cause every commit which would update a markdown file fail. The only option you are left with (and please correct me if I'm wrong) is to either skip pre-commit on that commit or remove doctoc from your pre-commit-config.yaml.

Suggestion

Since pre-commit aims more towards hooks which only check but, do not modify any files (such as linters, etc. ) the only way I see doctoc being used as a hook, would be if it only updated the files which had their structure changed since the last doctoc run or it had a mode in which it would simply run this check and fail, if some files needed updates. (Since both of them require this check to happen, it makes sense to implement it either way)

The way doctoc is working right now (and again, this is just my opinion and I'm open to being corrected) is not compatible with the direction pre-commit is heading. So in my humble opinion, the pre-commit integration in the current state is deprecated and it should either be addressed, or marked as suc. Again, I'm open for discussion.