metalsmith-preview

A Metalsmith plugin for generating custom text previews.

Usage no npm install needed!

<script type="module">
  import metalsmithPreview from 'https://cdn.skypack.dev/metalsmith-preview';
</script>

README

metalsmith-preview

npm version build status downloads

A Metalsmith plugin for generating custom text previews.

This plugin generates a customizable text preview for each source file. Previews can be generated based on word count, character count, or custom markers placed within the source text. Each preview is assigned to a file metadata key that can be referenced using the desired template engine.

Table of Contents

  1. Installation
  2. Examples
  3. Options
  4. License

Installation

$ npm install metalsmith-preview

⬆ back to top

Examples

Configuration in metalsmith.json:

Word Preview

{
  "plugins": {
    "metalsmith-preview": {
      "words": 10
    }
  }
}

Source file src/index.md:

Lorem ipsum dolor sit amet consectetur adipiscing elit, fermentum bibendum metus justo congue
tortor eget, phasellus aptent nunc nibh quis fusce.

Results in preview:

"Lorem ipsum dolor sit amet consectetur adipiscing elit, fermentum bibendum..."

Character Preview

Exact Count

{
  "plugins": {
    "metalsmith-preview": {
      "characters": 16
    }
  }
}

Note: Dots are used for spaces to illustrate the example.

Source file src/index.md:

∙Lorem∙ipsum∙dolor∙sit∙amet

Results in preview:

"∙Lorem∙ipsum∙..."

No Leading or Trailing Whitespace

{
  "plugins": {
    "metalsmith-preview": {
      "characters": {
          "count": 16,
          "trim": true
      }
    }
  }
}

Note: Dots are used for spaces to illustrate the example.

Source file src/index.md:

∙Lorem∙ipsum∙dolor∙sit∙amet

Results in preview:

"Lorem∙ipsum..."

Marker Preview

Enclosed Text

{
  "plugins": {
    "metalsmith-preview": {
      "marker": {
          "start": "{{ previewStart }}",
          "end": "{{ previewEnd }}"
      }
    }
  }
}

Source file src/index.md:

Lorem ipsum dolor sit amet consectetur adipiscing elit, {{ previewStart}}fermentum bibendum metus
justo congue{{ previewEnd }} tortor eget, phasellus aptent nunc nibh quis fusce.

Results in build/index.md:

Lorem ipsum dolor sit amet consectetur adipiscing elit, fermentum bibendum metus
justo congue tortor eget, phasellus aptent nunc nibh quis fusce.

And results in preview:

"fermentum bibendum metus justo congue..."

Leading Text

{
  "plugins": {
    "metalsmith-preview": {
      "marker": {
          "end": "{{ previewEnd }}"
      }
    }
  }
}

Source file src/index.md:

Lorem ipsum dolor sit amet{{ previewEnd }} consectetur adipiscing elit, fermentum bibendum metus
justo congue tortor eget, phasellus aptent nunc nibh quis fusce.

Results in build/index.md:

Lorem ipsum dolor sit amet consectetur adipiscing elit, fermentum bibendum metus
justo congue tortor eget, phasellus aptent nunc nibh quis fusce.

And results in preview:

"Lorem ipsum dolor sit amet..."

Ending Text

{
  "plugins": {
    "metalsmith-preview": {
      "marker": {
          "start": "{{ previewStart }}"
      }
    }
  }
}

Source file src/index.md:

Lorem ipsum dolor sit amet consectetur adipiscing elit, fermentum bibendum metus justo congue
tortor eget, {{ previewstart }}phasellus aptent nunc nibh quis fusce.

Results in build/index.md:

Lorem ipsum dolor sit amet consectetur adipiscing elit, fermentum bibendum metus justo congue
tortor eget, phasellus aptent nunc nibh quis fusce.

And results in preview:

"phasellus aptent nunc nibh quis fusce...."

⬆ back to top

Options

Pass options to metalsmith-preview using the Metalsmith Javascript API or CLI. These are the available plugin options:

Option Type Description
pattern string[]\|string Pattern used to match file names.
key string Key used to assign the preview value.
ignoreExistingKey boolean Whether to overwrite an existing preview key.
continueIndicator string Value appended to the preview.
strip regex\|string Regular expression or string to strip from the preview.
words number\|string Word limit used to generate previews.
characters number\|string\|object Character limit used to generate previews; this can be used as a number or an object containing configuration options.
characters.count number\|string Character limit used to generate previews.
characters.trim boolean Whether to trim whitespace from the character preview.
marker object Data marker(s) that indicate the desired preview.
marker.start string Generate a preview starting from this marker if present in the source file.
marker.end string Generate a preview ending at this marker if present in the source file.

Defaults

{
  "plugins": {
    "metalsmith-preview": {
      "pattern": "**/*",
      "key": "preview",
      "ignoreExisting": false,
      "continueIndicator": "...",
      "strip": /\[|\]\[.*?\]|<.*?>|[*_<>]/g,
      "words": 0,
      "characters": 0,
      "marker": {
        "start": "{{ previewStart }}",
        "end": "{{ previewEnd }}"
      }
    }
  }
}

Order of Operation

When options are set for word, character, and/or marker previews in the same configuration object, metalsmith-preview defaults first to a word preview, then to a character preview, and finally to a marker preview.

Option Details

pattern

Fed directly into multimatch as the mechanism to select source files.

key

Attached to each Metalsmith file object. Contains the preview text.

ignoreExistingKey

Overwrites an existing file key that has the same name as key when set to true. The default behavior is to do nothing if a duplicate key already exists in the Metalsmith file object.

continueIndicator

Appended at the end of the preview text as a visual indicator that more content exists. When used with the character preview, the length of the continueIndicator string counts against the specified character limit.

strip

Matched against the extracted preview text as a final step in generating the preview. The default behavior strips HTML and Markdown tags from the preview string.

words

Indicates the number of words to extract from the source text. If words is greater than the number of available words in the file, the plugin uses all words in the file.

characters

Indicates the number of characters to extract from the source text. If characters is greater than the number of available characters in the file, the plugin uses all characters in the file. Does not trim leading or trailing whitespace by default.

Used with a number:

{
  "characters": 42
}

Used with an object:

{
  "characters": {
    "count": 42,
    "trim": true
  }
}
charactersCount

Indicates the number of characters to extract from the source text when characters is an object.

charactersTrim

Indicates whether to trim leading and trailing whitespace from the character preview.

marker

Requires a configuration object when generating a marker-based preview.

markerStart

Extracts preview text starting from the first character after this marker.

markerEnd

Extracts preview text ending at the final character before this marker.

⬆ back to top

License

MIT

⬆ back to top