interledger / rafiki

An open-source, comprehensive Interledger service for wallet providers, enabling them to provide Interledger functionality to their users.
https://rafiki.dev/
Apache License 2.0
260 stars 89 forks source link

Fix automated formatting for .mdx files #2942

Open JoblersTune opened 1 month ago

JoblersTune commented 1 month ago

Context

As part of the Rafiki repository we have our documentation site (built with Astro and styled with Starlight). The docs files are created in markdown.

The problem

The current formatting is making life hard for our docs writers because it wraps tables over multiple lines making them impossible to read, is also giving inconsistent behaviour in terms of enforcing single quotes, and makes elements like the CodeBlock fragile.

Example of issues with markdown tables: image (6)

See example discussion: This:

``` EXCHANGE_RATES_URL: http://cloud-nine-wallet/rates ```

Turns into this:

``` GET https://cloud-nine-wallet/rates ```

Which causes the block to render incorrectly. It should look like this: image

But after formatting it looks like this: image

The automated formatting passes if additional white space is used around the code ticks but it would be nice not to have a fragile system.

The solution

We've bypassed this by ignoring the documentation folder when applying prettier formatting but it would be nice to have a good formatting system for the markdown files as well. So, we need better mdx friendly formatting rules (with explanations for any specific use cases in the documentation README).

mkurapov commented 1 month ago

@JoblersTune tagging as hacktoberfest given you added a good first issue - would you mind reviewing it once/if someone opens a PR for it?