Guide

vuepress-plugin-social-share is a VuePress plugin which provides social sharing services.

Install

npm install vuepress-plugin-social-share@next -D
yarn add vuepress-plugin-social-share@next -D
pnpm add vuepress-plugin-social-share@next -D

Usage

See Official Docs about how to use a plugin in VuePress.

import { defineUserConfig } from 'vuepress'
import { socialSharePlugin } from 'vuepress-plugin-social-share'

export default defineUserConfig({
  plugins: [socialSharePlugin()],
})

Options

For advanced usage.

import { defineUserConfig } from 'vuepress'
import { socialSharePlugin } from 'vuepress-plugin-social-share'

export default defineUserConfig({
  plugins: [
    socialSharePlugin({
      networks: [
        // enable build-in networks by default
        'twitter',
        'facebook',
        'email',

        // mark user defined networks as default
        'linkedin',

        // add user defined networks
        {
          name: 'pinterest',
          sharer:
            'https://pinterest.com/pin/create/button/?url=@url&media=@media&description=@title',
          type: 'popup',
          icon: '/pinterest.png',
          /**
           * mark this network as default
           */
          default: true,
        },
        {
          name: 'linkedin',
          sharer:
            'https://www.linkedin.com/shareArticle?mini=true&url=@url&title=@title&summary=@description',
          type: 'popup',
          color: '#1786b1',
          icon: '<svg viewBox="0 0 1024 1024" xmlns="http://www.w3.org/2000/svg"><path d="M910.336 0H113.664A114.005333 114.005333 0 0 0 0 113.664v796.672A114.005333 114.005333 0 0 0 113.664 1024h796.672A114.005333 114.005333 0 0 0 1024 910.336V113.664A114.005333 114.005333 0 0 0 910.336 0zM352.256 796.330667H207.189333V375.466667h145.066667z m-72.021333-477.866667a77.824 77.824 0 0 1-81.237334-74.069333A77.824 77.824 0 0 1 280.234667 170.666667a77.824 77.824 0 0 1 81.237333 73.728 77.824 77.824 0 0 1-81.237333 73.386666z m582.314666 477.866667H716.8v-227.669334c0-46.762667-18.432-93.525333-73.045333-93.525333a84.992 84.992 0 0 0-81.237334 94.549333v226.304h-140.629333V375.466667h141.653333v60.757333a155.989333 155.989333 0 0 1 136.533334-71.338667c60.416 0 163.498667 30.378667 163.498666 194.901334z" /></svg>',
        },
        /**
         * override built-in network
         */
        {
          name: 'twitter',
          color: {
            light: '#1786b1',
            dark: '#ff0',
          },
        },
      ],
      twitterUser: 'ntnyq',
      fallbackImage: '/social-share.png',
      autoQuote: true,
      isPlain: true,
      qrcodeOptions: {
        width: 240,
      },
    }),
  ],
})

networks

  • type: (string | SocialShareNetworkWithName | OverrideSocialShareNetworkWithName)[]
  • default ['twitter', 'facebook', 'reddit']
type ThemeableValue<T = string> = T | { light: T; dark: T }
type OverrideSocialShareNetworkWithName =
  Partial<SocialShareNetworkWithName> & {
    name: BuiltInNetworkNames
  }
type SocialShareNetworkWithName = {
  /**
   * Sharer name
   */
  name: string

  /**
   * Sharer icon
   */
  icon: ThemeableValue<string>

  /**
   * Sharer type
   */
  type: 'direct' | 'popup' | 'qrcode'

  /**
   * Sharer icon color
   */
  color?: ThemeableValue<string>

  /**
   * Sharer URL
   */
  sharer?: string

  /**
   * If component `SocialShare` has no prop `networks`, all `default: true` network will show
   */
  default?: boolean
}

When given type string, the network with this name will be used by default in both global and default SocialShare component if prop networks is not set.

When given type SocialShareNetworkWithName, will override a built-in network with the same name or add a user defined network.

Currently, networks below are built-in supported:

  • bluesky
  • douban
  • email
  • facebook
  • line
  • linkedin
  • pinterest
  • qq
  • qrcode
  • reddit
  • skype
  • telegram
  • threads
  • twitter
  • viber
  • wechat
  • weibo
  • whatsapp
  • x

Note

There is no single, standard way in which browsers/email clients handle mailto links (e.g. subject and body fields may be discarded without a warning). Also there is a risk that popup and ad blockers, anti-virus software etc. may silently block forced opening of mailto links.

Mailto only launches the MUA(Mail User Agent) which is configured as the default in the system-settings.

Reference:

twitterUser

  • type: string
  • default undefined

Your Twitter profile username.

fallbackImage

  • type: string
  • default undefined

A fallback share image if the page has no share image specified.

You can provide a network image url or an absolute path resolve based on .vuepress/public.

import { defineUserConfig } from 'vuepress'
import { socialSharePlugin } from 'vuepress-plugin-social-share'

// Network image
export default defineUserConfig({
  plugins: [
    socialSharePlugin({
      fallbackImage: 'https://vuepress.vuejs.org/hero.png',
    }),
  ],
})
import { defineUserConfig } from 'vuepress'
import { socialSharePlugin } from 'vuepress-plugin-social-share'

// Public image file
export default defineUserConfig({
  plugins: [
    socialSharePlugin({
      fallbackImage: '/hero.png',
    }),
  ],
})

autoQuote

  • type: boolean
  • default true

For Facebook, use the share meta description as the share quote content.

isPlain

  • type: boolean
  • default false

You can set isPlain to true if you don't like that all share icons have different colors.

All share icon colors will be set as the --vp-c-accent (former named --c-brand) by default.

Customize the color by setting --c-social-share-plain.

useCustomStyle

  • type: boolean
  • default false

You can disable the built-in style by setting useCustomStyle to true.

Then you can write styles that suit your theme.

You can take built-in style as a reference.

hideWhenPrint

  • type: boolean
  • default false

Hide all SocialShare (global as well) when print.

qrcodeOptions

  • type: object
  • default: { errorCorrectionLevel: 'H', width: 250, scale: 1, margin: 1.5 }

We use qrcode to generate the qrcode image.

See it's options for more information.

extendsNetworks Deprecated

  • type: object
  • default undefined
  • deprecated: true

With this option, you can add your custom sharer or override the built-in networks config.

i.e:

import { defineUserConfig } from 'vuepress'
import { socialSharePlugin } from 'vuepress-plugin-social-share'
import type { SocialShareNetwork } from 'vuepress-plugin-social-share'

const extendsNetworks: Record<string, SocialShareNetwork> = {
  pinterest: {
    sharer:
      'https://pinterest.com/pin/create/button/?url=@url&media=@media&description=@title',
    type: 'popup',
    icon: '/pinterest.png',
  },
  linkedin: {
    sharer:
      'https://www.linkedin.com/shareArticle?mini=true&url=@url&title=@title&summary=@description',
    type: 'popup',
    color: '#1786b1',
    icon: '<svg viewBox="0 0 1024 1024" xmlns="http://www.w3.org/2000/svg"><path d="M910.336 0H113.664A114.005333 114.005333 0 0 0 0 113.664v796.672A114.005333 114.005333 0 0 0 113.664 1024h796.672A114.005333 114.005333 0 0 0 1024 910.336V113.664A114.005333 114.005333 0 0 0 910.336 0zM352.256 796.330667H207.189333V375.466667h145.066667z m-72.021333-477.866667a77.824 77.824 0 0 1-81.237334-74.069333A77.824 77.824 0 0 1 280.234667 170.666667a77.824 77.824 0 0 1 81.237333 73.728 77.824 77.824 0 0 1-81.237333 73.386666z m582.314666 477.866667H716.8v-227.669334c0-46.762667-18.432-93.525333-73.045333-93.525333a84.992 84.992 0 0 0-81.237334 94.549333v226.304h-140.629333V375.466667h141.653333v60.757333a155.989333 155.989333 0 0 1 136.533334-71.338667c60.416 0 163.498667 30.378667 163.498666 194.901334z" /></svg>',
  },
  twitter: {
    color: {
      light: '#1786b1',
      dark: '#ff0',
    },
  },
}

export default defineUserConfig({
  plugins: [
    socialSharePlugin({
      networks: ['twitter', 'facebook', 'email', 'pinterest', 'linkedin'],
      extendsNetworks,
    }),
  ],
})

  1. You need to specific the extendsNetworks option with an object which key will be sharer's name and value will be options

  2. Config the plugin's networks option if you want to add custom sharer to GlobalSocialShare

  3. You can override the built-in networks config by given its options a different value

Custom sharer's option:

sharer

  • type: string
  • required true

You can use placeholders below in the sharer, it will be replaced by Share Meta

type

  • type: string

  • default undefined

  • required true

  • popup Open a new browser window for sharing service, mostly you need this

  • direct Open the sharer in current window directly. For mailto:, sms: and other built-in protocol

  • qrcode Open a model to show the qrcode of current page

The plugin does nothing if you haven't config type properly.

color

  • type: string | { dark: string; light: string }
  • default ''

Set the svg element color if you use it as sharer's icon.

icon

  • type: string | { dark: string; light: string }
  • required true

You can set icon with a network image, an image in your public folder with an absolute path or an svg element.

noGlobalSocialShare

  • type: boolean
  • default false

Set it to true if you want to disable the global social share component.

If you only want to disable global social share in some specific page, check Disable social share.

shareIcon

  • type: string | { dark: string; light: string }
  • default undefined

Share icon for GlobalSocialShare component.

shareCloseIcon

  • type: string | { dark: string; light: string }
  • default undefined

Close share icon for GlobalSocialShare component.

Component Props

The props of SocialShare component.

networks

Same as the plugin's option networks, but with a higher priority.

tags

  • type: string[]
  • default []

Share tags for Twitter and Facebook.

isPlain

Same as the plugin's option isPlain, but with a higher priority.

Share meta

Meta data for social share services.

Each meta data are listed following its priority.

url

  • $frontmatter.$shareUrl

  • $frontmatter.shareUrl

  • location.href

title

  • $frontmatter.$shareTitle

  • $frontmatter.shareTitle

  • $frontmatter.title

  • document.title

description

  • $frontmatter.$shareDescription

  • $frontmatter.shareDescription

  • $frontmatter.description

  • <meta name="description" />'s content

  • themeConfig.description

image

  • $frontmatter.$shareImage

  • $frontmatter.shareImage

  • $frontmatter.image

  • plugin option's fallbackImage

quote

hashtags

  • $frontmatter.$shareTags

  • $frontmatter.shareTags

  • $frontmatter.tags

  • $frontmatter.tag

  • Component's prop tags

  • <meta name="keywords" />'s content

Custom style

By default, those variables are set to vuepress-plugin-social-share.

:root {
  // global trigger color
  --c-social-share-trigger: var(--c-text-lightest, #6a8bad);

  // plain mode icon color
  --c-social-share-plain: var(--c-brand, var(--vp-c-accent));

  // global bgColor
  --c-bg-global-social-share: var(--c-bg, var(--vp-c-bg));
}

Override it in your stylesheet if needed.

Disable social share

You can disable vuepress-plugin-social-share in a specific page by setting the markdown frontmatter.

Disable global social share

Set noGlobalSocialShare to true if you want to disable the global social share component.

---
noGlobalSocialShare: true
---

Disable all social share

Set noSocialShare to true if you want to disable all social share component.

---
noSocialShare: true
---

Migration from v1

Edit this page
Last Updated::
Contributors: renovate[bot]