search

matrix-org / matrix-spec

The Matrix protocol specification
Apache License 2.0
170 stars 90 forks source link

Handlebars in API description files #1873

Open KitsuneRal opened 1 week ago

KitsuneRal commented 1 week ago

Link to problem area: https://github.com/matrix-org/matrix-spec/blob/main/data/api/client-server/content-repo.yaml#L226 and elsewhere in the same file.

Issue API description files can be used by code generation tools, and our own API viewer consumes them. While it's still sort of readable through the handlebars, I'd rather stick to Markdown in API files.

turt2live commented 1 week ago

fwiw, I did this deliberately to improve readability of the rendered spec - the fallback to text isn't great, but still readable enough.

I prefer we stay away from **Note**: syntax as much as possible, as we cannot keep the style consistent (sometimes bold, sometimes italic, sometimes lower/upper case, etc)