I wrote a book for O'Reilly and they have something called O'Reilly Snippets which allows you to embed snippets from another file inside your asciidoc files. It

I wrote a book for O'Reilly and they have something called O'Reilly Snippets which allows you to embed snippets from another file inside your asciidoc files. It sort-of solves the problem noted in the OP. The problem I found with it was that I would add the snippet, then later in the chapter, I would refactor the code to better fit the story, and that worked, as long as you only needed one copy of the file. But, it didn't work if you introduced a basic version of the code and then later elaborated and expanded that code and wanted it to reside in the same file. Additionally, you have to keep the code in the same repository, which I didn't want to do since I published companion repositories (which couldn't contain the sources for the book, obviously) and I didn't want to maintain and synchronize two copies of a file. So I wrote a little preprocessor that ingested a subtle variation on the snippets O'Reilly pioneered. Normal snippets work. But also, you could specify a file and a SHA hash, and if it saw that, it would pull the file at the commit (just using git show). Then I could update the file inside the repository as the code progressed, and still have all the sample code. And my repository always had working code, no matter what branch or point in time I had checked out. It's here: https://github.com/xrd/oreilly-snippets/blob/master/README.md#special-additions-to-snippets https://github.com/xrd/oreilly-snippets/blob/master/README.m...