amzn / style-dictionary

A build system for creating cross-platform styles.
https://styledictionary.com
Apache License 2.0
3.92k stars 556 forks source link

New Markdown (tables) format #1340

Open julien-deramond opened 1 month ago

julien-deramond commented 1 month ago

Context

I’ve been exploring Style Dictionary but haven't come across a built-in feature to generate Markdown files, nor issues or PRs mentioning it. I'm not familiar with all the features, so I've maybe missed something :)

While this might be a niche use case, I am currently in a situation where I need to generate Markdown tables from the JSON files. In addition to generating Android, iOS, and web files, I also need Markdown tables to reference in documentation.

After some experimentation, I was able to create a basic solution using the registerFormat method. Although it's a rough implementation and only tested for simple cases, it works as a proof of concept. Here's the snippet I used:

StyleDictionary.registerFormat({
  name: 'markdown',
  format: async ({ dictionary, options }) => {
    return (
      '| Name | Value | Type |\n' +
      '| ---- | ----- | ---- |\n' +
      dictionary.allTokens
        .map(function (token) {
          return `| ${token.name} | ${
            options.usesDtcg ? JSON.stringify(token.original.$value) : token.original.value
          } | ${token.original.type} |`
        })
        .join('\n')
    )
  },
})

Proposal

If there's currently no feature for generating Markdown tables output, would you be open to adding this as a new format? I’d be happy to refine the code further and submit a proper PR if there’s interest in supporting Markdown tables export as part of the project.

Let me know your thoughts, and I'd be glad to contribute!

jorenbroekema commented 1 month ago

Yeah this is definitely a welcome contribution, although I would also add the following props:

We can marginally improve it with other fields too, more nice-to-haves and takes a bit more work

vprothais commented 1 month ago

For the color preview you might take advantage of github and gitlab not standardized markdown. If you write a color between backtick : #ff0000 they show a little colored box (as you can see).