What convention should the doc generator use to import custom markdown into auto-generated docs?

[JSv4]

As discussed on the 5/24/22 TWG call, it would be great to to be able to reference some of our hand-prepared diagrams and documentation from within auto-generated documentation. For example, we want to be able to link to our conversion specification diagram from within the documentation pages for each of the types used in conversions. There's no way to do this currently, and our README keeps growing longer and longer.

On the call, we discussed using a convention whereby, if you want to add MD to the auto-generated documentation for a given schema, in that schema's folder, you add a markdown file with the same same as the schema file but with the markdown extension (e.g. MyObject.schema.json and MyObject.schema.md).

On further reflection, I've realized one problem with this is it makes it messier to export the schema files and load them into validators. It's obviously relatively trivial to filter out the .md extensions, but, it feels messy, and I like I can currently export the latest schema folder and load it in a validator without doing anything further. "Upgrading" to the latest ocf without extraneous stuff is really easy. Having a bunch of MD files in the same folders will make it messier.

Thoughts, @robwise, @pjohnmeyer, @Open-Cap-Table-Coalition/twg?