remark-imagetools

Contents

• What is this?
• When should I use this?
• Install
• Usage
• Configuration
• Examples
• Contributing
• Thanks
• License

What is this?

This plugin is part of the remark plugin infrastructure and meant to be used in conjunction with imagetools from Jonas Kruckenberg. A typical use case would be writing Markdown content using the mdsvex plugin for svelte. Let's say you want to use an image desert.webp with a certain width. Doing this with imagetools is quite easy:

---
title: example
---
<script>
    import desertpic from './desert.jpg?w=400&format=webp';
</script>

![Nice desert picture]({desertpic.src})

Looks simple enough but I thought this could be better. Creating the URL might become cumbersome and doesn't look very nice. In addition to that you have to put this script block in there.

This is where the remark-imagetools plugin comes into play. If you add it to the list of remark plugins you can change the above code to this:

---
title: example
images:
    - name: desertpic
      width: 400
      format: webp
---

![Nice desert picture]({desertpic.src})

This is much more readable and we got rid of the script block. However we can go much further as you typically have similar requirements for all of your images. That's where you can provide presets with the initialization of the plugin. The code than can be simplified even further (assuming the existence of a profile mobile):

---
title: example
images:
    - name: desertpic
      preset: mobile
---

![Nice desert picture]({desertpic.src})

In addition to that you can just make your changes to the preset in case you are making design changes. So there is no need to go through all the URLs.

When should I use this?

Mostly if you want to use images in multiple variations without the need to setup a corresponding toolchain. imagetools makes this process pretty straight forward. Furthermore it's meant to be used in conjunction with Markdown and the svelte extension mdsvex is a perfect fit for this.

Install

This package is ESM only. In Node.js (version 18+), install with pnpm:

pnpm i -D @kasisoft/remark-imagetools

Usage

• Setup your Svelte project and install mdsvex (see mdsvexdocs)
• Your project will now contain a file named mdsvex.config.js.
  • Import the plugin:

    import { Debug, remarkImagetools } from '@kasisoft/remark-imagetools';

  • Update the array of remark plugins without a configuration:

    const config = defineConfig({
        ...
        remarkPlugins: [remarkImagetools],
        ...
    });

  • with a configuration (note: each entry is a list here):

    const myconfig = {
        debug: Debug.All,
        presets: [
            {
                name: "mobile",
                width: 400,
                format: webp
    
            },
            {
                name: "sourceset",
                width: [100, 200, 400],
                format: webp
            }
        ]
    };
    const config = defineConfig({
        ...
        remarkPlugins: [
            [remarkImagetools, myconfig]
        ],
        ...
    });

Configuration

The configuration is fully typed using Typescript. ImagetoolsOptions is defined as followed:

export interface ImageConfigPreset {

    /* The name for this preset. Must be unique. */
    name     : string;

    /* The width(s) to use for the images. */
    width?   : number | number[];

    /* The height(s) to use for the images. */
    height?  : number | number[];

    /* Options allowing to do some image manipulations. */
    options? : string | string[],

    /* The file format to use */
    format?  : 'heic' | 'heif' |'avif' | 'jpeg' | 'jpg' | 'png' | 'tiff' | 'webp' | 'gif';

} /* ENDINTERFACE */


export interface ImagetoolsOptions {

    /* Debug.{None, Default, RootBefore, RootAfter, ScriptBefore, ScriptAfter, All}
     * It's okay to use a list of string values for the debugging levels.
     * For instance: ['RootBefore', 'RootAfter']
     */
    debug              : Debug | string | string[];

    /* Generate ts lang attribute for non existent script nodes */
    scriptTS?           : boolean;

    /* The name for the images property in the frontmatter. Default to 'images' */
    attributeName?      : string;

    presets?            : ImageConfigPreset[];

} /* ENDINTERFACE */

• debug : Debug - Combine flags of Debug in order to generate debug statements:
  • Debug.None: no output (just a convenience value)
  • Debug.Default: some basic output
  • Debug.RootBefore: prints the ast before the transformation
  • Debug.RootAfter: prints the ast after the transformation
  • Debug.ScriptBefore: prints the script node before the transformation
  • Debug.ScriptAfter: prints the script node after the transformation
  • Debug.All: enables all outputs (convenience value)
  • Using an array of strings representing these debug settings is also possible. For instance:
    • ['ScriptBefore', 'RootAfter']
• scriptTS : boolean - By default a lang="ts" will be added to each create script tag. If set to false this won't happen.
• attributeName: The name of the attribute within the frontmatter which defaults to images.
• presets: A list of presets essentially providing named configurations.

Examples

You can find an example project with various use cases here:

• https://github.com/kasisoft/remark-example

Contributing

If you want to contribute I'm happy for any kind of feedback or bug reports. Please create issues and pull requests as you like but be aware that it may take some time for me to react.

Thanks

• Svelte - For providing a great, fast and easy comprehensible framework.
• MSDVEX - For the nice intergration of Markdown in Svelte

• imagetools - For a great tool simplifying the use of image variations.

• remark - For a great platform to modify/transform the content.

License

MIT © Kasisoft.com - [email protected]