carbonate-code-snippets
v1.2.1
Published
Generates [carbon-now](https://carbon.now.sh/) screen captures for code snippets, ideally after each commit.
Downloads
5
Readme
carbonate-code-snippets
Generates carbon-now screen captures for code snippets, ideally after each commit.
Usage
npx carbonate-code-snippets <pre-defined theme name> <code snippets src root dir> <carbon pictures root dir> [<additional params>]
You can run it:
- manually locally:
npx -y [email protected] 4sh-learning code-snippet generated-code-snippet-pics
- from a github action: example here
- automatically, through a git
post-commit
hook (for instance configured by lefthook): example here
Additional params
You can pass additional params to the CLI in order to override provided theme preset :
config:<path to a preset json file>
: Allows to provide a manually-defined preset file
(can be useful for testing purposes, or if embedded themes are not suiting your needs)
Example:config:./my-custom-theme.json
param:<param name>=<param value>
: Allows to override specific properties from preset file Example:param:width=680px
How it works
It takes 3 input variables :
themeName
: Carbon theme which is going to be applied. Look atsrc/carbon-config.ts
file for available themes (ex:4sh-learning
)srcDir
: Root directory of (textual) your code snippets. Tree of this file hierarchy will be replicated intotargetDir
targetDir
: Root directory of your carbon pictures, replicatingsrcDir
directory/file tree.
Steps
- Look for additional CLI params and determine how preset config overrides are going to be applied
ConsideringcliConfigOverrides
as these preset configuration overrides. - Look for
${targetDir}/.last-generation-commit.sha1
file :- When found, make a
git diff
between commit in this file and currentHEAD
, and extract every changes detected insrcDir
from this diff. - When not found, consider that every files under
${srcDir}
are concerned by carbon generation.
- When found, make a
- Let's consider
updatedFiles
is the variable for the files that have been identified on previous step - Iterate over every
${updatedFiles}
, asupdatedFile
, then :- Identify carbon language to use based on
${updatedFile}
extension (seesrc/carbon-config.ts
'sFILE_EXTENSIONS_PER_LANGUAGE
) :
If none is found, considerauto
language
Let's considerlang
will capture this language. - Create a
carbon-config
file in a temp directory (consider file path to this file asconfigFilePath
), which will contain :src/carbon-config.ts
'sCONFIGS[themeName]
...- .. with overrides coming from
cliConfigOverrides
- .. with updated
language
field set to${lang}
- Call
carbon-now
CLI (from carbon-now-cli), with config${configFilePath}
,
for${updatedFile}
(from${srcDir}
) and translating path to${targetDir}
- Identify carbon language to use based on
- Once every file have been generated, update
${targetDir}/.last-generation-commit.sha1
to reflect currentHEAD
's commit - Creating a git commit (from changes in
${targetDir}
) then pushing this commit will be left at the discretion of the calling script
Limits
- File deletion into
srcDir
is not supported yet.
No workaround for this. - Multiple src directory synchronization.
Workaround: callcarbonate-code-snippets
multiple times with different(src, target)
directory pairs
Sincecarbonate-code-snippets
will not commit / push anything, you can have every generation included into a single git commit after the generations - Carbon picture re-generation (for instance, if we want to update theme, or change used theme)
Workaround: Delete${targetDir}/.last-generation-commit.sha1
then runcarbonate-code-snippets
.