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 carbonate-code-snippets@1.1.0 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 at src/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 into targetDir
• targetDir: Root directory of your carbon pictures, replicating srcDir directory/file tree.

Steps

• Look for additional CLI params and determine how preset config overrides are going to be applied
  Considering cliConfigOverrides 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 current HEAD, and extract every changes detected in srcDir from this diff.
  • When not found, consider that every files under ${srcDir} are concerned by carbon generation.
• Let's consider updatedFiles is the variable for the files that have been identified on previous step
• Iterate over every ${updatedFiles}, as updatedFile, then :

  • Identify carbon language to use based on ${updatedFile} extension (see src/carbon-config.ts's FILE_EXTENSIONS_PER_LANGUAGE) :
    If none is found, consider auto language
    Let's consider lang will capture this language.

  • Create a carbon-config file in a temp directory (consider file path to this file as configFilePath), which will contain :

    • src/carbon-config.ts's CONFIGS[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}

• Once every file have been generated, update ${targetDir}/.last-generation-commit.sha1 to reflect current HEAD'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: call carbonate-code-snippets multiple times with different (src, target) directory pairs
  Since carbonate-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 run carbonate-code-snippets.