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.
$ npm install metalsmith-preview
Configuration in metalsmith.json
:
{
"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..."
{
"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∙..."
{
"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..."
{
"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..."
{
"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..."
{
"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...."
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. |
{
"plugins": {
"metalsmith-preview": {
"pattern": "**/*",
"key": "preview",
"ignoreExisting": false,
"continueIndicator": "...",
"strip": /\[|\]\[.*?\]|<.*?>|[*_<>]/g,
"words": 0,
"characters": 0,
"marker": {
"start": "{{ previewStart }}",
"end": "{{ previewEnd }}"
}
}
}
}
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.
Fed directly into multimatch as the mechanism to select source files.
Attached to each Metalsmith file object. Contains the preview text.
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.
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.
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.
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.
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
}
}
Indicates the number of characters to extract from the source text when characters
is an object.
Indicates whether to trim leading and trailing whitespace from the character preview.
Requires a configuration object when generating a marker-based preview.
Extracts preview text starting from the first character after this marker.
Extracts preview text ending at the final character before this marker.
MIT