New Markdown (tables) format

[julien-deramond]

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]

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

• description (reads from token.$description or token.comment (legacy) property)
• original (reads from token.original.value/token.original.$value) -> can be left empty if it's the same as $value/value

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

• Reference chain, shows the entire chain of references that lead to the resolved value
• Value preview e.g. for colors putting a small color box div prefix, maybe some other token types can also show value previews

[vprothais]

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

• Gitlab ref : https://docs.gitlab.com/ee/user/markdown.html#colors
• Github ref : 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