feat(frontmatter): configure max length for description (#946)

Emile Bangma

2024-03-04 bcb5b2df09cb8c8fc0736ec476b2486f9b4643be

feat(frontmatter): configure max length for description (#946)

* Sentence length check

* Replace external links with domain name.

* Updated documentation.

* Updated replacement values.

* Updated Regex based on feedback.

* Check description for undefined

* Updated external url transform regex.

* Updated formatting

 docs/plugins/Description.md

@@ -14,6 +14,7 @@
This plugin accepts the following configuration options:

- `descriptionLength`: the maximum length of the generated description. Default is 150 characters. The cut off happens after the first _sentence_ that ends after the given length.
- `replaceExternalLinks`: If `true` (default), replace external links with their domain and path in the description (e.g. `https://domain.tld/some_page/another_page?query=hello&target=world` is replaced with `domain.tld/some_page/another_page`).

## API


 quartz/plugins/transformers/description.ts

@@ -5,12 +5,19 @@

export interface Options {
  descriptionLength: number
  replaceExternalLinks: boolean
}

const defaultOptions: Options = {
  descriptionLength: 150,
  replaceExternalLinks: true,
}

const urlRegex = new RegExp(
  /(https?:\/\/)?(?<domain>([\da-z\.-]+)\.([a-z\.]{2,6})(:\d+)?)(?<path>[\/\w\.-]*)(\?[\/\w\.=&;-]*)?/,
  "g",
)

export const Description: QuartzTransformerPlugin<Partial<Options> | undefined> = (userOpts) => {
  const opts = { ...defaultOptions, ...userOpts }
  return {
@@ -19,20 +26,40 @@
      return [
        () => {
          return async (tree: HTMLRoot, file) => {
            const frontMatterDescription = file.data.frontmatter?.description
            const text = escapeHTML(toString(tree))
            let frontMatterDescription = file.data.frontmatter?.description
            let text = escapeHTML(toString(tree))

            if (opts.replaceExternalLinks) {
              frontMatterDescription = frontMatterDescription?.replace(
                urlRegex,
                "$<domain>" + "$<path>",
              )
              text = text.replace(urlRegex, "$<domain>" + "$<path>")
            }

            const desc = frontMatterDescription ?? text
            const sentences = desc.replace(/\s+/g, " ").split(".")
            const sentences = desc.replace(/\s+/g, " ").split(/\.\s/)
            let finalDesc = ""
            let sentenceIdx = 0
            const len = opts.descriptionLength

            if (sentences[0] !== undefined && sentences[0].length >= len) {
              const firstSentence = sentences[0].split(" ")
              while (finalDesc.length < len) {
                const sentence = firstSentence[sentenceIdx]
                if (!sentence) break
                finalDesc += sentence + " "
                sentenceIdx++
              }
              finalDesc = finalDesc.trimEnd() + "..."
            } else {
            while (finalDesc.length < len) {
              const sentence = sentences[sentenceIdx]
              if (!sentence) break
              finalDesc += sentence + "."
                finalDesc += sentence.endsWith(".") ? sentence : sentence + "."
              sentenceIdx++
            }
            }

            file.data.description = finalDesc
            file.data.text = text