Hacker News Reader

Comment by samhw | Hacker News Reader

> The README is using a trick I'm increasingly leaning on: parts of that document - the --help output and the example database schema - are automatically generated using Cog

How does this interact with IDEs? Has anyone written a VSCode extension yet? I'd probably be reluctant to use something like this without IDE support. (Though I may well be in the minority, and I appreciate that for open source tools it's not necessarily reasonable to expect people to dedicate so much of their time to DX.)

View on HN

To regenerate the markdown file I run this command in the console:

    cog -r README.md

Presumably most IDEs have q mechanism that can run that command automatically, either when a file changes or just intermittently over time.

I use VS Code's markdown preview panel, which updates automatically when I manually run the "cog -r" command.

Nice! I didn't know about cog.

I've developed a simple "codeblocks" tool that to keep README.md up-to-date. In your example, here is how to insert the latest `--help` output:

    codeblocks usage-auth README.md -- google-drive-to-sqlite auth --help

Where "usage-auth" is the block language in README.md:

    Full `--help`:
    ```usage-auth
    Usage: ...
    ```

Checking is also possible:

    codeblocks --check usage-auth README.md -- google-drive-to-sqlite auth --help

It's not as generic as cog, but does not require writing codegen scripts inside Markdown file.

https://github.com/shamrin/codeblocks

Notable alternative for emacs users: Github supports rendering .org files, so you can have a README.org using babel (just remember to execute all code blocks before pushing).

hm I'm guessing..run the cog command in the VSCode terminal

Reply on news.ycombinator.com