Has anyone solved how to syncronise readme.md with constants in code?

Application
#1

Doesn’t have to be a spec extension proposal, but just speculation on application.

I’m wondering if anyone has thought about how readme.md can be automatically updated.

There is two approaches:

  • A script that reads readme.md for certain markups or tables and converts it into code that is used by a codebase.
  • A script that reads a codebase and updates the readme.md file to the latest value.

This has the advantage of keeping the readme.md up to date with any constants or settings in the codebase.

#2

not readme per se, but documentation is often (auto-)generated from comments in code (i.e. jsDoc) on every minor version bump

#3

I would suggest to use pandoc and a filter.

#4

the Node.js community seems to have many tools to juggle Markdown, some of them supporting CommonMark.
Yesterday I stumbled upon some tool using this one (I have no idea if it is good or fits exactly your needs): https://www.npmjs.com/package/gitdown

#5

It’s a good idea to have an application release process that is followed for each new version - there are likely other things that need to be manually reviewed, for example the version number. You could write another script to check for changes in your app, but keep in mind that this also needs to be maintained.

1 Like