extract-topic

Extracts the topic sentence(s) from a given block of text/HTML/Markdown.

Install

npm i extract-topic

Usage

import { extractTopic } from 'extract-topic' // ESM
// const { extractTopic } = require('extract-topic') // CJS
const paragraph = "Desire is irrelevant. There is only doing."

console.log('The topic sentence is: ' + extractTopic(paragraph))
// prints: "The topic sentence is: Desire is irrelevant."

See more examples.

API reference

API generated with dmd-readme-api.

extractTopic(text, [options]) ⇒ string

Extracts the topic (typically the first sentence) from a paragraph. The function is HTML, Markdown, and comment aware and by default will ignore headers and strip formatting.

The algorithm works as follows:

1. Processes any HTML or Markdown style section headers (e.g., '<h1>...</h1>', '### ...', etc.), either removing (default) or converting to a part of the main text body depending on the value of handleHeaders. Whitespace is trimmed, unless keepWhitespace=true orkeepNewlines=true.
2. Removes comment characters (unless keepCommentChars=true) and whitespace is trimmed unless keepWhitespace=true or keepNewlines=true.
3. Strips HTML tags (unless keepTags=true) and Markdown format (unless keepMd=true) and whitespace is trimmed unless keepWhitespace=true or keepNewlines=true.
4. All whitespace is normalized. Unless keepNewlines=true, newlines are removed then, unless keepWhitespace=true tabs and non-breaking spaces are converted to normal spaces, any multiple spaces are reduced to a single space, and space between the last word and end-punctuation is removed.
5. Extracts the first sentenceCount sentences (default 1).
6. If the extracted text doesn't fulfill minChars, extract the next sentence.
7. Trim the output to maxChars, if defined.

Re removing comment signifiers, the function will attempt to remove specified comment signifers from the beginning of each line in the text (including any leading whitespace) beginning with the designated signifier string. '/' is treated as a special multi-line comment signifier. The leading '/' and trailing '/' are removed and any leading '' characters from the body of the comment are removed (Javadoc style).

| Param | Type | Default | Description | | --- | --- | --- | --- | | text | string | | The original block of text to extract the topic from. | | [options] | object | | Extraction options. | | [options.commentSignifiers] | Array.<string> | ['/*', '//'] | An array of comment signifiers to be removed. Pass in an empty array to keep all comment signifiers. See note on removing comment signifiers in function documentation. | | [options.handleHeaders] | boolean | string | false | If false (or null, undefined), then headers are removed from text. If set to a string, then the header text is retained and appended with the value of this option. E.g., handleHeader=': ' applied to '<h1>Overview</h1> Hello!' would yield 'Overview: Hello!' | | [options.keepCommentChars] | boolean | false | If true, then comment signifiers are left in place. | | [options.keepMd] | boolean | false | If true, then Markdown formatting is left in place. | | [options.keepNewlines] | boolean | false | If true, then newlines in the text are preserved. | | [options.keepWhitespace] | boolean | false | If true, then all whitespace in the text is preserved. | | [options.keepTags] | boolean | false | If true, then HTML style tags are left in place. | | [options.maxChars] | number | undefined | | If set, then result will be limited to the indicated number of characters. | | [options.minChars] | number | 0 | If set, then the function will continue to extract sentences until the minChars have been satisfied (regardless of sentenceCount). | | [options.removeBackticks] | boolean | false | If True, then backticks are also removed. | | [options.sentenceCount] | number | 1 | The minimum number of sentences to extract. |

Returns: string - - The extracted topic.

Examples