Support Markdown in generated Docs

[psteinroe]

Hey,

with most of our business logic within postgres functions and triggers, we are making use of postgres comments to document what is going on where. It would be awesome to have the documentation generated in the dashboard support markdown, so we can write a proper documentation.

[thorwebdev]

This is a great idea, thank you. I've forwarded this to the team and will have them follow up 👍

[thorwebdev]

@psteinroe do you have a screenshot of how this looks like for you today? If you can't share that publicly, could you DM it to me? Thanks :)

[psteinroe]

docs-example.mov

Sure, there you go! :)

[MildTomato]

This is interesting.

@psteinroe what's the use case here?

are you wanting to copy the docs as markdown so you can paste it somewhere else?
I'm guessing it might be your own documentation / internal knowledge base for your project / a project readme ?

[psteinroe]

@MildTomato I am using Postgres comments to document our functions, tables and columns. I am assuming the docs in the dashboard are currently generated from the OpenAPI endpoint of PostgREST, which exposes these sql comments within the spec.

The use-case is mainly documentation. We have 70+ tables and 150+ functions and triggers. Since the code lives in migrations and is not static as it would be with e.g. a node server, a developer cannot see how everything is structured by looking at the code, and reading 200+ migration files is not practicable, too. Hence, our best option is to document everything using the comment feature of Postgres. As you can see in the video, the dashboard is currently designed to display only one or two lines of documentation, but not entire paragraphs or markdown.

The comment shown in the video is defined within a migration:

comment on table event is $$
An event is created everytime something interesting is happening in a conversation.
It is defined by metadata, a source and a target, where the source is conceptually the entity that caused the event and the target the entity that was affected by what has happened.
The table below lists all event types.

| Type                 | Description                                    | Source Types | Target Types |
|----------------------|------------------------------------------------|--------------|--------------|
| assign               | When a conversation is assigned to an employee | employee     | employee     |
| unassign             | When a conversation is unassigned              | employee     |              |
| subject_change       | When the conversation subject is changed       | employee     |              |
| close                | When a conversation is closed                  | employee     |              |
| reopen               | When a conversation is unarchived              | employee     |              |
| comment              | When an employee comments on a conversation    | employee     | comment      |
| mention              | When an employee is mentioned within a comment | comment      | employee     |
| inbound              | When an incoming message is received           | channel      | message      |
| outbound             | When an outbound message is sent               | channel      | message      |
| submit               | When an outbound message is submitted          | channel      | message      |
| tag                  | When a conversation is tagged                  | employee     | tag          |
| untag                | When a conversation is untagged                | employee     | tag          |
| submission_error     | When a channel cannot submit a message         | channel      | message      |
| sending_error        | When a channel cannot send a message           | channel      | message      |
| message_bounce_error | When a message cannot be delivered             | recipient    | message      |
$$;

[MildTomato]

Ahh got it.
Thanks for that, that's really helpful. Looks like a good idea.
Will bring it up with the dashboard team this week.