` tag) of the rendered HTML `contents` of a file and added to its metadata `excerpt` key. 28 | 29 | ```js 30 | const excerpts = require('@metalsmith/excerpts') 31 | 32 | metalsmith.use(excerpts()) // default -> file.excerpt 33 | metalsmith.use(excerpts({ multipleFormats: true })) // -> file.excerpt.html & file.excerpt.text 34 | ``` 35 | 36 | ### Custom excerpts 37 | 38 | You can define a custom `excerpt` in the front-matter of specific files: 39 | 40 | ```md 41 | --- 42 | excerpt: This will be the excerpt 43 | --- 44 | 45 | This would be the excerpt if none was specified in the front-matter 46 | ``` 47 | 48 | ### Excerpts with tags stripped 49 | 50 | Sometimes you may need access to the text content of the excerpt without HTML tags. 51 | Pass the `multipleFormats: true` option to store an excerpt object with both HTML and text excerpts `{ html: '...', text: '...' }`: 52 | 53 | ```js 54 | metalsmith.use(excerpts({ multipleFormats: true })) 55 | ``` 56 | 57 | ### CLI usage 58 | 59 | Add the `@metalsmith/excerpts` key to your `metalsmith.json` plugins key: 60 | 61 | ```json 62 | { 63 | "plugins": [{ "@metalsmith/excerpts": { "multipleFormats": false } }] 64 | } 65 | ``` 66 | 67 | ## License 68 | 69 | [MIT](LICENSE) 70 | 71 | [npm-badge]: https://img.shields.io/npm/v/@metalsmith/excerpts.svg 72 | [npm-url]: https://www.npmjs.com/package/@metalsmith/excerpts 73 | [ci-badge]: https://app.travis-ci.com/metalsmith/excerpts.svg?branch=master 74 | [ci-url]: https://app.travis-ci.com/github/metalsmith/excerpts 75 | [metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true 76 | [metalsmith-url]: https://metalsmith.io 77 | [codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/excerpts 78 | [codecov-url]: https://coveralls.io/github/metalsmith/excerpts 79 | [license-badge]: https://img.shields.io/github/license/metalsmith/excerpts 80 | [license-url]: LICENSE 81 | -------------------------------------------------------------------------------- /lib/index.js: -------------------------------------------------------------------------------- 1 | const { extname } = require('path') 2 | const debug = require('debug')('@metalsmith/excerpts') 3 | const cheerio = require('cheerio') 4 | 5 | /** 6 | * Check if a `file` is HTML. 7 | * 8 | * @param {String} file 9 | * @return {Boolean} 10 | */ 11 | const html = (file) => /\.html?/.test(extname(file)) 12 | 13 | /** 14 | * @typedef {Object} Options 15 | * @property {Boolean} [multipleFormats] set to true to store both a `excerpt.html` and `excerpt.text` 16 | */ 17 | 18 | /** 19 | * A Metalsmith plugin to extract an excerpt from HTML files. 20 | * 21 | * @param {Options} [options] 22 | * @return {import('metalsmith').Plugin} 23 | */ 24 | function plugin(options) { 25 | return function excerpts(files, metalsmith, done) { 26 | setImmediate(done) 27 | 28 | options = options || {} 29 | 30 | Object.keys(files).forEach((file) => { 31 | debug('checking file: %s', file) 32 | if (!html(file)) { 33 | return 34 | } 35 | 36 | const data = files[file] 37 | 38 | if (typeof data.excerpt === 'string' && data.excerpt.length > 0) { 39 | return // Don't mutate data 40 | } 41 | 42 | debug('storing excerpt: %s', file) 43 | const $ = cheerio.load(data.contents.toString()) 44 | let p = $('p').first() 45 | while (p.children('img').length > 0) { 46 | p = p.next() 47 | } 48 | 49 | if (options.multipleFormats) { 50 | data.excerpt = { 51 | html: $.html(p).trim(), 52 | text: $.text(p).trim() 53 | } 54 | } else { 55 | data.excerpt = $.html(p).trim() 56 | } 57 | }) 58 | } 59 | } 60 | 61 | module.exports = plugin 62 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@metalsmith/excerpts", 3 | "version": "1.5.1", 4 | "description": "A Metalsmith plugin to extract an excerpt from HTML files.", 5 | "keywords": [ 6 | "excerpt", 7 | "metalsmith-plugin", 8 | "metalsmith" 9 | ], 10 | "homepage": "https://github.com/metalsmith/excerpts#readme", 11 | "bugs": "https://github.com/metalsmith/excerpts/issues", 12 | "repository": { 13 | "type": "git", 14 | "url": "https://github.com/metalsmith/excerpts.git" 15 | }, 16 | "license": "MIT", 17 | "main": "lib/index.js", 18 | "directories": { 19 | "lib": "lib", 20 | "test": "test" 21 | }, 22 | "files": [ 23 | "lib", 24 | "CHANGELOG.md" 25 | ], 26 | "scripts": { 27 | "changelog": "auto-changelog -u --starting-date 2021-12-01 --commit-limit false --ignore-commit-pattern '^((dev|chore|ci):|Release|skip changelog)'", 28 | "coverage": "nyc report --reporter=text-lcov > ./coverage.info", 29 | "coveralls": "npm run coverage && cat ./coverage.info | coveralls", 30 | "format": "prettier --write \"**/*.{yml,md,js,json}\"", 31 | "lint": "eslint .", 32 | "release": "release-it .", 33 | "test": "nyc mocha" 34 | }, 35 | "dependencies": { 36 | "cheerio": "^1.0.0-rc.10", 37 | "debug": "^4.3.3" 38 | }, 39 | "devDependencies": { 40 | "@metalsmith/markdown": "^1.3.0", 41 | "auto-changelog": "^2.3.0", 42 | "coveralls": "^3.1.1", 43 | "eslint": "^8.4.1", 44 | "eslint-config-prettier": "^8.3.0", 45 | "metalsmith": "^2.3.0", 46 | "mocha": "^7.2.0", 47 | "nyc": "^15.1.0", 48 | "prettier": "^2.5.1", 49 | "release-it": "^14.11.8" 50 | }, 51 | "peerDependencies": { 52 | "metalsmith": "^2.3.0" 53 | }, 54 | "engines": { 55 | "node": ">=8" 56 | }, 57 | "publishConfig": { 58 | "access": "public" 59 | } 60 | } 61 | -------------------------------------------------------------------------------- /test/fixtures/basic/expected/index.md: -------------------------------------------------------------------------------- 1 | excerpt -------------------------------------------------------------------------------- /test/fixtures/basic/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | template: layout 3 | --- 4 | 5 | excerpt 6 | 7 | more content -------------------------------------------------------------------------------- /test/fixtures/first-paragraph-image/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Testing first paragraphs with images 3 | --- 4 | 5 |  6 | 7 |  8 | 9 | This is the excerpt. 10 | -------------------------------------------------------------------------------- /test/fixtures/indented-paragraph/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Testing indented first paragraphs 3 | --- 4 | 5 | This is code. 6 | 7 | This is the excerpt. 8 | 9 | -------------------------------------------------------------------------------- /test/fixtures/no-mutation/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | template: layout 3 | excerpt: beans 4 | --- 5 | 6 | excerpt 7 | 8 | more content 9 | -------------------------------------------------------------------------------- /test/fixtures/not-html/expected/file.yaml: -------------------------------------------------------------------------------- 1 | template: layout 2 | -------------------------------------------------------------------------------- /test/fixtures/not-html/src/file.yaml: -------------------------------------------------------------------------------- 1 | template: layout 2 | -------------------------------------------------------------------------------- /test/fixtures/one-paragraph/expected/index.md: -------------------------------------------------------------------------------- 1 | excerpt -------------------------------------------------------------------------------- /test/fixtures/one-paragraph/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | template: layout 3 | --- 4 | 5 | excerpt 6 | -------------------------------------------------------------------------------- /test/fixtures/reference-links/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Test reference links 3 | --- 4 | 5 | This is [a link][a]. 6 | 7 | [a]: http://example.com 8 | 9 | -------------------------------------------------------------------------------- /test/fixtures/whitespace/expected/index.md: -------------------------------------------------------------------------------- 1 | excerpt -------------------------------------------------------------------------------- /test/fixtures/whitespace/src/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | template: layout 3 | --- 4 | 5 | 6 | 7 | 8 | 9 | excerpt 10 | 11 | more content 12 | -------------------------------------------------------------------------------- /test/index.js: -------------------------------------------------------------------------------- 1 | const assert = require('assert') 2 | const { it } = require('mocha') 3 | const markdown = require('@metalsmith/markdown') 4 | const metalsmith = require('metalsmith') 5 | const excerpt = require('..') 6 | 7 | it('should convert excerpt files', (done) => { 8 | metalsmith('test/fixtures/basic') 9 | .use(markdown()) 10 | .use(excerpt()) 11 | .build((err, files) => { 12 | if (err) { 13 | return err 14 | } 15 | 16 | assert.equal('
excerpt
', files['index.html'].excerpt) 17 | done() 18 | }) 19 | }) 20 | 21 | it('should convert excerpt files that have leading whitespace', (done) => { 22 | metalsmith('test/fixtures/whitespace') 23 | .use(markdown()) 24 | .use(excerpt()) 25 | .build((err, files) => { 26 | if (err) { 27 | return err 28 | } 29 | 30 | assert.equal('excerpt
', files['index.html'].excerpt) 31 | done() 32 | }) 33 | }) 34 | 35 | it('should convert excerpt files that only have one paragraph', (done) => { 36 | metalsmith('test/fixtures/one-paragraph') 37 | .use(markdown()) 38 | .use(excerpt()) 39 | .build((err, files) => { 40 | if (err) { 41 | return err 42 | } 43 | 44 | assert.equal('excerpt
', files['index.html'].excerpt) 45 | done() 46 | }) 47 | }) 48 | 49 | it('should convert excerpt files with reference-style links', (done) => { 50 | metalsmith('test/fixtures/reference-links') 51 | .use(markdown()) 52 | .use(excerpt()) 53 | .build((err, files) => { 54 | if (err) { 55 | return err 56 | } 57 | 58 | assert.equal('This is a link.
', files['index.html'].excerpt) 59 | done() 60 | }) 61 | }) 62 | 63 | it('should skip excerpts with leading whitespace', (done) => { 64 | metalsmith('test/fixtures/indented-paragraph') 65 | .use(markdown()) 66 | .use(excerpt()) 67 | .build((err, files) => { 68 | if (err) { 69 | return err 70 | } 71 | 72 | assert.equal('This is the excerpt.
', files['index.html'].excerpt) 73 | done() 74 | }) 75 | }) 76 | 77 | it('should convert excerpts with multiple formats', (done) => { 78 | metalsmith('test/fixtures/reference-links') 79 | .use(markdown()) 80 | .use(excerpt({ multipleFormats: true })) 81 | .build((err, files) => { 82 | if (err) { 83 | return err 84 | } 85 | 86 | assert.equal('This is a link.
', files['index.html'].excerpt.html) 87 | assert.equal('This is a link.', files['index.html'].excerpt.text) 88 | done() 89 | }) 90 | }) 91 | 92 | it('should skip excerpts with images', (done) => { 93 | metalsmith('test/fixtures/first-paragraph-image') 94 | .use(markdown()) 95 | .use(excerpt()) 96 | .build((err, files) => { 97 | if (err) { 98 | return err 99 | } 100 | 101 | assert.equal('This is the excerpt.
', files['index.html'].excerpt) 102 | done() 103 | }) 104 | }) 105 | 106 | it('should skip excerpts that are not html', (done) => { 107 | metalsmith('test/fixtures/not-html') 108 | .use(excerpt()) 109 | .build((err, files) => { 110 | if (err) { 111 | return err 112 | } 113 | 114 | assert.ok('template: layout', files['file.yaml'].contents.toString().trim()) 115 | done() 116 | }) 117 | }) 118 | 119 | it('should not mutate an existing excerpts', (done) => { 120 | metalsmith('test/fixtures/no-mutation') 121 | .use(markdown()) 122 | .use(excerpt()) 123 | .build((err, files) => { 124 | if (err) { 125 | return err 126 | } 127 | 128 | assert.equal('beans', files['index.html'].excerpt) 129 | done() 130 | }) 131 | }) 132 | --------------------------------------------------------------------------------