"The web interface to the version control system doesn't parse the here-string correctly" isn't really a criticism of the PostgreSQL extension. It's a bug in the syntax highlighting.

The COMMENT feature isn't even a good choice for a VIEW, PROCEDURE, or FUNCTION, each of which already supports comments inline in the object definition on the server. No, the main benefits are adding comments to objects that DON'T retain them, like a TABLE, COLUMN, CONSTRAINT, ROLE, etc.

Since the project consists of multiple SQL files already, a workaround might be to split out all the “comment on” statements from each file into new files following them.

So in file 02-… you have your “create schema”, “create view” and so on. And then in file 03-… you have only the “comment on” statements that go with the things from file 02. And then file 04-… contains “create schema” and “create view” and so on, and file 05-… has the “comment on” statements for file 04-….

And in addition you could then add dash dash comments in 02 and 04 referring to files 03 and 05. And in file 03 and 05 at the top mention that these are valid SQL for PostgreSQL and that GitHub has trouble rendering them properly.

It’s a bit messy of course, but that’s why I say it’s a possible workaround rather than a great solution. Could be worth considering and trying, anyway.