> why not put the content from the md file in the code

We do that :-)

https://joist-orm.io/modeling/documentation/#two-way-syncing

Technically the md file can have more free-form docs, but for the overview/fields headers that, by convention, map to the entity/field jsdocs, we do sync them over.