Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix automated formatting for .mdx files #2942

Closed
JoblersTune opened this issue Sep 4, 2024 · 1 comment · Fixed by #3147
Closed

Fix automated formatting for .mdx files #2942

JoblersTune opened this issue Sep 4, 2024 · 1 comment · Fixed by #3147
Labels
good first issue Good for newcomers hacktoberfest pkg: documentation Changes in the documentation package. type: quality Changes to code quality

Comments

@JoblersTune
Copy link
Collaborator

JoblersTune commented Sep 4, 2024

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).

@JoblersTune JoblersTune added type: quality Changes to code quality pkg: documentation Changes in the documentation package. labels Sep 4, 2024
@github-project-automation github-project-automation bot moved this to Backlog in Rafiki Sep 4, 2024
@mkurapov mkurapov removed this from Documentation Sep 10, 2024
@JoblersTune JoblersTune added the good first issue Good for newcomers label Sep 20, 2024
@mkurapov
Copy link
Contributor

mkurapov commented Oct 2, 2024

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

@github-project-automation github-project-automation bot moved this from Backlog to Done in Rafiki Dec 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Good for newcomers hacktoberfest pkg: documentation Changes in the documentation package. type: quality Changes to code quality
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

2 participants