Avoid wrapping on RBS quick reference table #8831
Conversation
website/docs/rbs-support.md
Outdated
| @@ -436,7 +744,7 @@ You can also consider using [`T::Enum`](tenum.md). | |||
|
|
|||
| ### `T.let` assertions | |||
|
|
|||
| [`T.let`](type-assertions.md#tlet) assertions can be expressed using RBS | |||
| [`T.let`](type-assertions#tlet) assertions can be expressed using RBS | |||
There was a problem hiding this comment.
Please do not remove these .md comments.
I wonder if Shopify has some sort of editor tooling which is removing these on save—I have already asked one of your colleagues to not do this, so I'll refer you to that comment for the justification
There was a problem hiding this comment.
My mistake, I didn't intend to change those!
I wonder if Shopify has some sort of editor tooling which is removing these on save—I have already asked one of your colleagues to not do this, so I'll refer you to that comment for the justification
It's possible, but Cursor may have gotten confused, as I explicitly asked it to remove the .md extensions from <a href="/docs/blah.md"> links because those didn't work when I ran the docs server locally. I should have checked the result more closely.
I'll put them back on the Markdown links. Do you know if there's a way to make it work for both GitHub and the docs website when linking around ```ruby blocks? AFAIK, I can't use [Markdown](/links) to wrap around those, and I assume Docusaurus only applies it's compatibility transformation to those
8000
links. 🤔
There was a problem hiding this comment.
Unfortunately I think with raw HTML there's nothing we can do. We have the same shortcoming in the TypeScript <-> Sorbet Reference page.
There was a problem hiding this comment.
Yeah, I confirmed Docusaurus (or at least version 1.x, which is what we're using) only looks at inline and reference style Markdown links.
I've put those links back, but stuck to non-.md hrefs for the raw HTML links.
The `type_parameters` example is long and causes line wrapping of itself, and other code snippets. We can avoid this by switching to a multiline code block for the Sorbet column of this table (which also has the benefit of allowing us to highlight Ruby syntax). This comes at the cost of needing to switch to an HTML table (interlaced with Markdown) which is harder to edit. However, this tradeoff is acceptable, as we should optimize for documentation readers, not for documentation authors (and LLMs can help edit the docs anyway).
Motivation
The
type_parametersexample is long and causes line wrapping of itself, and other code snippets.We can avoid this by switching to a multiline code block for the Sorbet column of this table (which also has the benefit of allowing us to highlight Ruby syntax).
This comes at the cost of needing to switch to an HTML table (interlaced with Markdown) which is harder to edit. However, this tradeoff is acceptable, as we should optimize for documentation readers, not for documentation authors (and LLMs can help edit the docs anyway).
Test plan
This is a documentation only change, other than the Docusaurus config change, which should be covered by existing tests. I've also tried out rendering the docs, and it renders as expected (see screenshots above).