Documentation of protobufs is broken with multiline comments
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 161
- Forks
- 1.9k
- PR merge metrics
- No merged PRs in 30d
Description
Preflight checklist
- I could not find a solution in the existing issues, docs, nor discussions.
- I agree to follow this project's Code of Conduct.
- I have read and am following this repository's Contribution Guidelines.
- I have joined the Ory Community Slack.
- I am signed up to the Ory Security Patch Newsletter.
Ory Network Project
No response
Describe the bug
Documentation generated from protobuf files which contain a newline will generate a broken table.
Reproducing the bug
run: make buf inside the keto project. The generated file docs/.generated/proto-api.mdx is well formated. Tables contain newlines with </br> tags. The file protof/buf.md does not.
Open the docs/keto/reference/proto-api.mdx file inside the docs project. The tables now contain actual newlines, breaking the tables, and resulting in garbled docs
Relevant log output
No response
Relevant configuration
No response
Version
keto v0.11.1-alpha.0
On which operating system are you observing this issue?
None
In which environment are you deploying?
None
Additional Context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by running make buf in the keto project and compare docs/.generated/proto-api.mdx with protof/buf.md. Then inspect how the generated content reaches docs/keto/reference/proto-api.mdx; done means multiline comments remain table-safe and the rendered documentation no longer has broken tables or garbled text.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100