I've been using a little literate-programming shell script for years, for various personal and professional projects. I find it makes a huge difference in my ability to hand off a code file to another developer, because I tend to document justifications and explanations for why the code is the way it is, where it came from, what else was tried, alternatives and variants, and how to understand aspects of it that are not obvious from the code.

My script doesn't try to shuffle code around, which has the advantage that if you are familiar with the general structure of the code, the documentation follows the same structure. (This may not be the best order to explain the theory of the program, as is noted in several introductions to literate programming).

Instead of code blocks, my little shell script has a per-line approach, where each code line is preceded by the name of the file to which it is extracted. This approach allows me to name a variant immediately after the filename, so that I can code alternative lines, and decide at the time of extraction which sets of lines to use. This is also useful for extracting multiple very similar files from a single markdown source. This use of variants has been very effective in supporting alternative implementations, since I can quickly switch between them by the list of variants I give the tool to extract.

https://github.com/catenate/sharedo/blob/main/lit.md