|
| 1 | +const fs = require('fs'); |
| 2 | +const path = require('path'); |
| 3 | + |
| 4 | +const directoryPath = path.join(__dirname, '../', 'parsers'); |
| 5 | +let parsers = []; |
| 6 | +const fileNames = fs.readdirSync(directoryPath); |
| 7 | + |
| 8 | +const directories = fileNames.filter(fileName => !fileName.includes('.ts')); |
| 9 | + |
| 10 | +parsers = directories.map(directory => { |
| 11 | + const readmeParserPath = path.join(__dirname, '../', 'parsers', directory, 'README.md'); |
| 12 | + const parserContent = fs.readFileSync(readmeParserPath, { encoding: 'utf8', flag: 'r' }); |
| 13 | + |
| 14 | + const parserDescription = parserContent.match(/This parser helps you (.*)/)[1]; |
| 15 | + const capitalizedParserDescription = |
| 16 | + parserDescription.charAt(0).toUpperCase() + parserDescription.slice(1); |
| 17 | + const exampleLink = `https://github.com/Specifyapp/parsers/blob/master/parsers/${directory}/README.md#usage`; |
| 18 | + const parserLink = `https://github.com/Specifyapp/parsers/blob/master/parsers/${directory}`; |
| 19 | + |
| 20 | + return { |
| 21 | + title: directory, |
| 22 | + description: capitalizedParserDescription, |
| 23 | + parserLnk, |
| 24 | + exampleLink, |
| 25 | + }; |
| 26 | +}); |
| 27 | + |
| 28 | +const markdownFullPage = `--- |
| 29 | +description: >- |
| 30 | + Parsers are functions allowing you to transform design tokens and assets |
| 31 | + coming from Specify to fit your needs and company standards. |
| 32 | +--- |
| 33 | +
|
| 34 | +# Parsers |
| 35 | +
|
| 36 | +## Why you need parsers |
| 37 | +
|
| 38 | +<figure><img src="../front/documentation/.gitbook/assets/where-parsers-happen-dark.jpg" alt=""><figcaption><p>Parsers help you transform raw design tokens and assets returned by Specify to match your company standards</p></figcaption></figure> |
| 39 | +
|
| 40 | +By default, without any parsers, Specify will return your design data as raw data: |
| 41 | +
|
| 42 | +* Design tokens are returned in JSON |
| 43 | +* Assets are returned as files |
| 44 | +
|
| 45 | +There are high chances you need to transform those design data to fit your needs. Parsers help you do just that. |
| 46 | +
|
| 47 | +## What are parsers? |
| 48 | +
|
| 49 | +Parsers are functions allowing you to transform design tokens and assets coming from Specify to fit your needs and company standards. |
| 50 | +
|
| 51 | +<figure><img src="../front/documentation/.gitbook/assets/how-parsers-work.jpg" alt=""><figcaption><p>An example output pipeline that pulls colors from Specify, sorts them alphabetically and transforms them as CSS Custom Properties</p></figcaption></figure> |
| 52 | +
|
| 53 | +A parser does the following job: |
| 54 | +
|
| 55 | +1. Receives design data as input |
| 56 | +2. Transforms this design data |
| 57 | +3. Returns the transformed data |
| 58 | +
|
| 59 | +The data returned by a parser can either be: |
| 60 | +
|
| 61 | +* Design data that can be used by another parser coming next in your transformation pipeline |
| 62 | +* A file so it can be used by people, frameworks, or scripts |
| 63 | +
|
| 64 | +{% hint style="info" %} |
| 65 | +Parsers are what make Specify powerful and flexible. They help you be in total control of the design data you pull from Specify. |
| 66 | +{% endhint %} |
| 67 | +
|
| 68 | +Parsers are ordered and takes specific input to generate specific output. This way, we can easily test the input coming from the previous parser to check if the whole parsers process will work. |
| 69 | +
|
| 70 | +## Categories |
| 71 | +
|
| 72 | +Parsers are classified in 2 categories: technology and utility. |
| 73 | +
|
| 74 | +### Technology |
| 75 | +
|
| 76 | +Technology parsers help you transform your design tokens to specific technologies and formats (CSS Custom properties, SCSS, Tailwind, a Javascript theme object compatible with React Native...) |
| 77 | +
|
| 78 | +Some examples: |
| 79 | +
|
| 80 | +* [to-react-native](https://github.com/Specifyapp/parsers/tree/master/parsers/to-react-native) |
| 81 | +* [to-css-custom-properties](https://github.com/Specifyapp/parsers/tree/master/parsers/to-css-custom-properties) |
| 82 | +* [to-scss-variables](https://github.com/Specifyapp/parsers/tree/master/parsers/to-scss-variables) |
| 83 | +* [to-tailwind](https://github.com/Specifyapp/parsers/tree/master/parsers/to-tailwind) |
| 84 | +
|
| 85 | +### Utility |
| 86 | +
|
| 87 | +Utility parsers take care of "smaller" transformation. Like converting a pixel value to \`rem\` or transforming a string to kebabcase. |
| 88 | +
|
| 89 | +Some examples: |
| 90 | +
|
| 91 | +* [convert-font](https://github.com/Specifyapp/parsers/tree/master/parsers/convert-font) |
| 92 | +* [kebabcasify](https://github.com/Specifyapp/parsers/tree/master/parsers/kebabcasify) |
| 93 | +* [px-to-rem](https://github.com/Specifyapp/parsers/tree/master/parsers/px-to-rem) |
| 94 | +
|
| 95 | +## All parsers available |
| 96 | +
|
| 97 | +All parsers are open source and available on [the following GitHub repository](https://github.com/Specifyapp/parsers). |
| 98 | +
|
| 99 | +`; |
| 100 | + |
| 101 | +const markdownHeader = `| Parser | Description | Usage Example | |
| 102 | +|---|---|---|`; |
| 103 | + |
| 104 | +const parsersMarkdown = parsers.reduce((acc, currentParser) => { |
| 105 | + const { title, description, exampleLink } = currentParser; |
| 106 | + if (!acc) { |
| 107 | + return `${markdownHeader} |
| 108 | +| [${title}](${parserLink}) | ${description} | [Example](${exampleLink}) |`; |
| 109 | + } |
| 110 | + return `${acc} |
| 111 | +| [${title}](${parserLink}) | ${description} | [Example](${exampleLink}) |`; |
| 112 | +}, ''); |
| 113 | + |
| 114 | +const summaryFilePath = path.join(__dirname, '../output/', 'parsers.md'); |
| 115 | +fs.writeFileSync(summaryFilePath, markdownFullPage + parsersMarkdown, { |
| 116 | + encoding: 'utf8', |
| 117 | + flag: 'w', |
| 118 | +}); |
0 commit comments