Gatsby-remark-link-summary NPM

gatsby-remark-link-summary

This plugin scrapes link nodes and replaces the link nodes to summary nodes that you designed using scraped data (e.g. og:title, og:image, og:description).

Example Output

This plugin can convert text links in a markdown file to links with images as follows:

from

[--small-card--](https://www.npmjs.com/package/gatsby-remark-link-summary)
[--large-card--](https://github.com/blyoa/gatsby-remark-link-summary)

card with small image card with large image

Installation

npm install gatsby-remark-link-summary

Usage

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          // put `gatsby-remark-link-summary` before `gatsby-remark-images`
          // if generated nodes by `generator` includes img elements and
          // the image nodes should be processed by `gatsby-remark-images`
          resolve: `gatsby-remark-link-summary`,
          options: {
            cacheRootDirPath: 'path/to/cache',
            destinationSubDirPath: 'path/to/sub/dir',
            sites: [
              {
                pattern: /^https:\/\/github\.com\/.*/,
                generator: async ({ metadata: { url, title, image }, cacheRemoteFile }) => {
                  const deployedPath = await cacheRemoteFile(image, true)
                  return `<a href="${url}"><img src="${deployedPath}"/></a>`
                },
                rules: [
                  require('metascraper-url')(),
                  require('metascraper-image')(),
                ],
                gotOptions: {
                  // e.g.
                  // timeout: ...
                  // retry: ...
                },
                cacheExpirationSecond: 60 * 60 * 24 * 10, // 10 days
              },
              {
                // replace link nodes that have the text "--summary-card--"
                // e.g.
                // [--summary-card--](https://example.com)
                pattern: (node) => {
                  if (node.children.length === 0) return false
                  const [firstChild] = node.children
                  return  (firstChild.type === 'text' && firstChild.value === '--summary-card--')
                  // NOTE: The URL of a link node can be obtained from `node.url`
                },
                generator: async ({ metadata: { url, title, image }, cacheRemoteFile }) => {
                  const deployedPath = await cacheRemoteFile(image, true)
                  return `<a href="${url}"><img src="${deployedPath}"/></a>`
                },
                rules: [
                  require('metascraper-url')(),
                  require('metascraper-image')(),
                ],
              },
            ],
          },
        },
      ],
    },
  },
],

Options

name	type	description
`cacheRootDirPath`	`string \\| undefined`	A directory to place remote files fetched by `cacheRemoteFile` of `HTMLGeneratorParams` and a catalog file about the fetched files and scraped metadata. If this option is `undefined`, the catalog file is not saved.
`destinationSubDirPath`	`string`	A subdirectory of the directory for built artifacts (i.e., the `public` directory) to place remote files fetched in the second argument of `generator`.
`sites`	`SiteOptions[]`	Node generator options for sites.

SiteOptions

name	type	description
`pattern`	`RegExp \\| (node: Link) => boolean`	A target link node to be substituted. `RegExp` specifies URLs of the link node to be substituted, and the function returns whether the link node should be substituted or not. `Link` is the type defined in mdast package.
`generator`	`(params: HTMLGeneratorParams) => string \\| Node \\| Promise<string \\| Node>`	A function to generate the node that substitute a link node.
`rules`	`Rule[]`	Rules for metascraper.
`gotOptions`	`Options[] \\| undefined`	Options for got.
`cacheExpirationSecond`	`number \\| undefined`	The expiration second of scraped metadata and fetched remote files. The metadata and the path to the fetched remote file are reused until this expiration second reaches.If this option is `undefined`, the fetched metadata and the fetched remote files never expire.

HTMLGeneratorParams

name	type	description
`metadata`	`Record<string, string>`	Metadata scraped by metascraper.
`orignalNode`	`Link`	An original link node that `generator` substitutes.
`cacheRemoteFile`	`(fileURL: string, persistent?: boolean) => Promise<string>`	A function to fetch a remote file and returns the path to the fetched file in `destinationSubDirPath`. `fileURL` is the URL of the remote file. When `persistent` is true, the fetched file is also saved in `cachedRootDirPath`.

Example Settings

Card With Small Image

card with small image

gatsby-config.js

const descriptionRule = require("metascraper-description")
const imageRule = require("metascraper-image")
const titleRule = require("metascraper-title")
const urlRule = require("metascraper-url")

module.exports = {
  // snip...
  plugins: [
    // snip...
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-link-summary`,
            options: {
              cacheRootDirPath: "cache/link-summary",
              destinationSubDirPath: "link-summary",
              sites: [
                {
                  pattern: /^https:\/\/www\.npmjs\.com\/.*/,
                  generator: async ({
                    metadata: { image, url, title, description },
                    cacheRemoteFile,
                  }) => {
                    const filePath = await cacheRemoteFile(image, true)
                    return `
                      <div class="summary-card">
                        <a href="${url}">
                          <img
                            class="summary-card__image"
                            src="${filePath}"
                          />
                          <div class="summary-card__description">
                            <div class="summary-card__description__title"
                              >${title}</div
                            >
                            <div class="summary-card__description__summary"
                              >${description}</div
                            >
                            <div class="summary-card__description__url"
                              >${url}</div
                            >
                          </div>
                        </a>
                      </div>
                    `
                  },
                  rules: [
                    urlRule(),
                    titleRule(),
                    imageRule(),
                    descriptionRule(),
                  ],
                },
              ],
            },
          },
          // snip...
        ],
      },
    },
    // snip...
  ],
}

your-style-file.css

/* import css, e.g. from gatsby-browser.js */
.summary-card {
  line-height: 1.5;
}

.summary-card a {
  color: inherit;
  text-decoration: none;
  display: flex;
  flex-direction: row-reverse;
  align-items: center;
  border: 1px solid #e5e5e5;
  border-radius: 3px;
}

.summary-card__image {
  width: 14rem;
  height: 10rem;
  object-fit: cover;
  border-inline-start: 1px solid #e5e5e5;
}

.summary-card__description {
  display: flex;
  flex-direction: column;
  flex: 1;
  padding: 0 1.2rem;
  overflow: hidden;
}

.summary-card__description__title {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
  font-weight: 700;
  max-height: calc(2rem * 1.5);
  overflow: hidden;
}

.summary-card__description__summary {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
  margin-block-start: 0.4rem;
  font-size: 0.8rem;
  max-height: calc(1.6rem * 1.5);
  overflow: hidden;
  color: #a3a3a3;
}

.summary-card__description__url {
  margin-block-start: 0.6rem;
  font-size: 0.8rem;
  overflow: hidden;
  text-overflow: ellipsis;
  color: #a3a3a3;
}

Card With Large Image

card with large image

gatsby-config.js

const descriptionRule = require("metascraper-description")
const imageRule = require("metascraper-image")
const titleRule = require("metascraper-title")
const urlRule = require("metascraper-url")

module.exports = {
  // snip...
  plugins: [
    // snip...
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-link-summary`,
            options: {
              cacheRootDirPath: "cache/link-summary",
              destinationSubDirPath: "link-summary",
              sites: [
                {
                  pattern: /^https:\/\/github\.com\/.*/,
                  generator: async ({
                    metadata: { image, url, title, description },
                    cacheRemoteFile,
                  }) => {
                    const filePath = await cacheRemoteFile(image, true)
                    return `
                      <div class="large-image-summary-card">
                        <a href="${url}">
                          <img
                            class="large-image-summary-card__image"
                            src="${filePath}"
                          />
                          <div class="large-image-summary-card__description">
                            <div class="large-image-summary-card__description__title"
                              >${title}</div
                            >
                            <div class="large-image-summary-card__description__summary"
                              >${description}</div
                            >
                            <div class="large-image-summary-card__description__url"
                              >${url}</div
                            >
                          </div>
                        </a>
                      </div>
                    `
                  },
                  rules: [
                    urlRule(),
                    titleRule(),
                    imageRule(),
                    descriptionRule(),
                  ],
                },
              ],
            },
          },
          // snip...
        ],
      },
    },
    // snip...
  ],
}

/* import css, e.g. from gatsby-browser.js */
.large-image-summary-card {
  line-height: 1.5;
}

.large-image-summary-card a {
  display: flex;
  color: inherit;
  text-decoration: none;
  flex-direction: column;
  border: 1px solid #e5e5e5;
  border-radius: 3px;
}

.large-image-summary-card__image {
  width: 100%;
  object-fit: cover;
  border-block-end: 1px solid #e5e5e5;
}

.large-image-summary-card__description {
  display: flex;
  flex: 1;
  flex-direction: column;
  padding: 1.2rem;
}

.large-image-summary-card__description__title {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
  font-weight: 700;
  max-height: calc(2rem * 1.5);
  overflow: hidden;
}

.large-image-summary-card__description__summary {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 2;
  margin-top: 0.2rem;
  font-size: 0.8rem;
  max-height: calc(1.6rem * 1.5);
  overflow: hidden;
  color: #a3a3a3;
}

.large-image-summary-card__description__url {
  margin-top: 0.4rem;
  font-size: 0.8rem;
  color: #a3a3a3;
  overflow: hidden;
  text-overflow: ellipsis;
}

gatsby gatsby-plugin open graph protocol remark twitter card

@types/error-cause @types/es-aggregate-error @types/mdast error-cause es-aggregate-error eslint-plugin-n file-type got metascraper valid-url

@everything-registry/sub-chunk-1723 @zalastax/nolb-gatsby-r

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago