feat: add `markdown` and `markdown/table`

julien-deramond commented 1 month ago

[!WARNING]
This PR is heavily draft. Feel free to:

close this PR if too heavily draft and that it bothers the repo to have it opened :)

directly modify it if needed

Closes #1340

Description

This PR proposes to add a new markdown/table format that would render a table in Markdown format. This would be useful for documentation purposes, as it would allow for a more structured and readable output.

For instance, it would generate the following Markdown:

| Token | Description | Type | Value |
| --- | --- | --- | --- |
| aqua 0 |   | color | `#d9fcfb` |
| aqua 100 |   | color | `#c5f9f9` |
| aqua 200 |   | color | `#a5f2f2` |
| aqua 300 |   | color | `#76e5e2` |
| aqua 400 |   | color | `#33d6e2` |
| aqua 500 |   | color | `#17b8ce` |
| aqua 600 |   | color | `#0797ae` |
| aqua 700 |   | color | `#0b8599` |
| aqua 800 |   | color | `#0f6e84` |
| aqua 900 |   | color | `#035e73` |
| aqua 1000 |   | color | `#083d4f` |
| aqua 1100 |   | color | `#002838` |

that would be rendered this way:

Token	Type	Value
aqua 0	color	`#d9fcfb`
aqua 100	color	`#c5f9f9`
aqua 200	color	`#a5f2f2`
aqua 300	color	`#76e5e2`
aqua 400	color	`#33d6e2`
aqua 500	color	`#17b8ce`
aqua 600	color	`#0797ae`
aqua 700	color	`#0b8599`
aqua 800	color	`#0f6e84`
aqua 900	color	`#035e73`
aqua 1000	color	`#083d4f`
aqua 1100	color	`#002838`

In terms of usage, even if I'm not that familiar with all usages of Style Dictionary, I can imagine that it could be useful to also have a new markdown transform group that would allow rendering the tokens in Markdown format.

Features

`original` property

Mentioned in https://github.com/amzn/style-dictionary/issues/1340#issuecomment-2373798882:

"original (reads from token.original.value/token.original.$value) → can be left empty if it's the same as $value/value"

[ ] TODO: check how to implement it. Render a new dedicated column. If so, automatic or with a property named showOriginalColumn (or something like that).

`description` property

Mentioned in https://github.com/amzn/style-dictionary/issues/1340#issuecomment-2373798882:

"description (reads from token.$description or token.comment (legacy) property)"

This first version adds a showDescriptionColumn which makes it a voluntary gesture from the user. There could be another approach as described in https://github.com/amzn/style-dictionary/pull/1353#discussion_r1780921496 where there's nothing to configure as a user, and the description is automatically displayed if there's at least one description.

We could add some specific unit tests too.

Reference chain (nice to have)

Mentioned in https://github.com/amzn/style-dictionary/issues/1340#issuecomment-2373798882:

(nice to have) "reference chain, shows the entire chain of references that lead to the resolved value"

[ ] TODO: Let's prototype! Maybe optional for this first version?

Value preview (nice to have)

Mentioned in https://github.com/amzn/style-dictionary/issues/1340#issuecomment-2373798882:

(nice to have) "value preview e.g. for colors putting a small color box div prefix, maybe some other token types can also show value previews"

Unfortunately, Markdown doesn't inherently support colored text (or areas). For example, it's not possible to include colored text in GitHub comments or descriptions, or even READMEs, even when using something like <span style="color:orange;">Word up</span>. However, some Markdown processors do allow for HTML.

However, as mentioned in https://github.com/amzn/style-dictionary/issues/1340#issuecomment-2376168925, GitHub and GitLab render colors in a specific way when the value is surrounded by backticks. This could be used to render a color preview in the table.

For instance: #ffdd00

Based on this, I've surrounded all the values (not necessarily colors) by backticks in the table. This would render the color values in a colored box in GitHub and GitLab, but not in other Markdown processors. And the other values will also have a code-like appearance. It would avoid complexity and specificities for each type of token.

If we'd like to go further, we might add a new option/property to provide the rendering as a parameter, or to enable a rich preview, where we could use a colored rounded <div> for instance. This would be useful for all Markdown preprocessors that don't display nicely the colors; for instance, the Markdown documentation of GitLab.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

aws-amplify-us-west-1[bot] commented 1 month ago

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-1353.d16eby4ekpss5y.amplifyapp.com

julien-deramond commented 1 month ago

Marking it as 'ready for review' to get initial feedback from the core team before proceeding further.

jorenbroekema commented 1 month ago

Another note btw, for color values with color preview, this only works for issues, PRs and discussions, https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#supported-color-models

If we want color value previews that not only work in github markdown elsewhere but also for all markdown renderers, we may have to go with something more agnostic like this: https://stackoverflow.com/questions/11509830/how-to-add-color-to-githubs-readme-md-file (https://placehold.co/)

julien-deramond commented 1 month ago

Sorry this took a while, I was pretty swamped with some other work so I only just now was able to really take a close look at this and invest time in properly reviewing. I think we're definitely on the right track, but I do have quite a few suggestions :)

Thanks a lot for your time and your suggestions. I'll look at them closely to make evolve this PR as soon as possible; also swamped with tome other work, but step-by-step we'll manage to land something :)

amzn / style-dictionary