I was starting to try and tackle adding better support for all of GitHub's themes in the VSCode GitHub Markdown preview extension. Namely this issue: https://github.com/mjbvz/vscode-github-markdown-preview-style/issues/89. That lead me to realize it'd be easiest if I could export each of the theme's color variables by themselves to allow easier swapping between them. Looking into this tool I there wasn't a way to easily export the theme variables by themselves because of the applyColors function when in "single" mode. This whole change started as a way to add an option around that.
Summary
Added an option to preserve variables in output even when outputting a single theme, preserveVariables
Added an option to only output variables, onlyVariables
Added an option to only output the styles without variables to be used alongside the variable only files, onlyStyles
Added an option to change the root selector used in the output to whatever people want, rootSelector
I did this because I noticed the extension changed it to .github-markdown-body and it's easy to do in the source of the files here instead of a manual process. This also allows any consuming systems to easily set their own root class if they want. this probably should've been a separate PR though...
Added a JSDoc block for the primary getCSS API method, including the new options, to make it easier for consumers to use without digging into the code
Added comments to the CSS output including what theme was exported
In single mode this is at the top of the file, in auto mode this is included inside the prefers-color-scheme blocks.
Added [data-theme="THEME"] selectors to the theme blocks when exporting any variable blocks
The goal was to help make it easier for any consumers to allow easy theme changing by changing the data on the root element but this also probably could've been a separate PR
Expanded test file generation to include all current themes and include exports for the variable only method to demonstrate using those files together
Expanded the CLI to support all the new options I added as well as various combinations in auto mode
Added some input validation for the CLI and the API method
Throughout my changes I aimed to preserve the existing behavior for both the CLI and the API method. All existing calls to the function should behave as they used to and all calls to the CLI version should output the same results. I wanted to expand the functionality not change it.
I will admit the changes started to expand in scope quickly as I got into the flow of working on this so if it's better to break into multiple PRs or remove some of them I'd totally understand.
Testing
Run npm test
Open dist/index.html and cycle through all the options in the upper right
Verify the css files under dist/ look correct
Open dist/vars/index.html and cycle through all the options in the upper right
Verify the css files under dist/vars look correct and that they only include the color variables
Verify the dist/vars/base.css includes all the styles with var(--variable) statements but no colors
hyrious
commented
1 year ago
Background
I was starting to try and tackle adding better support for all of GitHub's themes in the VSCode GitHub Markdown preview extension. Namely this issue: https://github.com/mjbvz/vscode-github-markdown-preview-style/issues/89. That lead me to realize it'd be easiest if I could export each of the theme's color variables by themselves to allow easier swapping between them. Looking into this tool I there wasn't a way to easily export the theme variables by themselves because of the
applyColorsfunction when in "single" mode. This whole change started as a way to add an option around that.Summary
preserveVariablesonlyVariablesonlyStylesrootSelector.github-markdown-bodyand it's easy to do in the source of the files here instead of a manual process. This also allows any consuming systems to easily set their own root class if they want. this probably should've been a separate PR though...getCSSAPI method, including the new options, to make it easier for consumers to use without digging into the codeprefers-color-schemeblocks.[data-theme="THEME"]selectors to the theme blocks when exporting any variable blocksThroughout my changes I aimed to preserve the existing behavior for both the CLI and the API method. All existing calls to the function should behave as they used to and all calls to the CLI version should output the same results. I wanted to expand the functionality not change it.
I will admit the changes started to expand in scope quickly as I got into the flow of working on this so if it's better to break into multiple PRs or remove some of them I'd totally understand.
Testing
npm testdist/index.htmland cycle through all the options in the upper rightdist/look correctdist/vars/index.htmland cycle through all the options in the upper rightdist/varslook correct and that they only include the color variablesdist/vars/base.cssincludes all the styles withvar(--variable)statements but no colors