svelte-preprocess-escape

A Svelte preprocesor that allows escaping content within components or elements. In simpler terms: this lets you open a compiler escape hatch to render Svelte code within Svelte components. This is particularly useful for displaying example Svelte code (or whatever else you might want) within code blocks.

IMPORTANT: The implementation here is pretty rough/experimental, hasn't been significantly dogfooded or tested, and was designed only to solve something within my own particular problem space. This may work reasonably well for you -- or not at all.

Installing

npm install svelte-preprocess-escape --save-dev

Or, if you're using Yarn:

yarn add svelte-preprocess-escape --dev

Basic Usage Example

// svelte.config.js
import escape from 'svelte-preprocess-escape' // the preprocessor is default-exported
import preprocess from 'svelte-preprocess'

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // If using svelte-preprocess, ensure `escape()` precedes it in the
  // preprocessor list
  preprocess: [escape(), preprocess()],
  kit: {
    adapter: adapter(),
    target: '#svelte'
  },
  ...
}

<!-- component.svelte -->
<h1>Regular Old Markup</h1>

<pre>
  <code escape-content>
    <script lang="ts">
      const f = () => {
        return true
      }
    </script>
  
    <style lang="scss">
      a {
        color: red;
      }
    </style>
  </code>
</pre>

In this example, since the escape-content attribute is present on the <code> element, the content therein will simply render as text, maintaining any indendation (thanks to <pre>). The preprocessor automatically dedents the content, so it renders as you'd expect.

Note that the preprocessor will simply ignore any nested instances of elements or components marked with escape-content, so there's no option to nest within them, nor is there an option to break out of them.

Options

You can supply a few options as an object to the exported function:

| Property | Type | Default | Description | |-------------|----------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | tag | string | escape-content | The attribute name to supply. E.g., | | extensions | string[] | ['.svelte'] | The file extensions the preprocessor will be available to act on | | highlighter | function | | An optional highlighter function, useful for performing code highlighting on the escaped contents. Must conform to the signature (code: string, filename?: string) => string |

Building

This project uses the built-in packaging functionality of SvelteKit to generate the package code. To build outside of the usual package management environment:

git clone [email protected]:boatilus/svelte-preprocess-escape.git
cd svelte-preprocess-escape
npm install
npm package

This will produce a /package directory containing the TypeScript source transpiled to JavaScript, as well as a TypeScript definition file.

License

MIT