@gridsome/vue-remark

Create pages with Vue components in Markdown. Perfect for building Documentation, Design Systems, Portfolios, Blogs, etc.

Install

• npm install @gridsome/vue-remark
• yarn add @gridsome/vue-remark
• pnpm install @gridsome/vue-remark

Usage

1. Add configs to gridsome.config.js.

module.exports = {
  plugins: [
    {
      use: '@gridsome/vue-remark',
      options: {
        typeName: 'Documentation', // Required
        baseDir: './content/docs', // Where .md files are located
        pathPrefix: '/docs', // Add route prefix. Optional
        template: './src/templates/Documentation.vue' // Optional
      }
    }
  ]
}

In this example /content/docs/index.md will be website.com/docs/, and /content/docs/install-guide.md will be website.com/docs/install-guide/.

By default it takes any .md files in baseDir folder and uses them for file-based routing like Pages works. You can override this by using a route config.

2. Setup a template and include the <VueRemarkContent /> component:

<template>
  <Layout>
    <h1>{{ $page.documentation.title }}</h1>
    <p class="intro">{{ $page.documentation.excerpt }}</p>
    <VueRemarkContent />
  </Layout>
</template>

<!-- Front-matter fields can be queried from GraphQL layer -->
<page-query>
query Documentation ($id: ID!) {
  documentation(id: $id) {
    title
    excerpt
  }
}
</page-query>

Example Markdown file

---
title: A cool title
excerpt: Lorem Ipsum is simply dummy text.
---
// Import any Vue Component. Even other .md files!
import YouTube from '~/components/YouTube.vue'
import AboutUs from '~/sections/AboutUs.md'

// Import any JSON if you need data.
import data from '~/data/youtube.json'

// Use front-matter fields anywhere.
# {{ $frontmatter.title }}
> {{ $frontmatter.excerpt }}

// Use your imported Vue Components.
<YouTube :id="data.id" />
<AboutUs />

Options

typeName

• Type: string required

The type name to give the pages in the GraphQL schema.

baseDir

• Type: string required

The path to the directory which contains all the .md files. A relative path will be resolved from the project root directory.

template

• Type: string

Use a template for every page created by this plugin. This option is useful if you for example need to have a shared page-query or want to wrap every page in the same layout component. Insert the <VueRemarkContent> component where you want to show the Markdown content.

module.exports = {
  plugins: [
    {
      use: '@gridsome/vue-remark',
      options: {
        typeName: 'MarkdownPage',
        baseDir: './content',
        template: './src/templates/MarkdownPage.vue'
      }
    }
  ]
}

<template>
  <Layout>
    <h1>{{ $page.vueRemarkPage.title }}</h1>
    <VueRemarkContent />
  </Layout>
</template>

<page-query>
query VueRemarkPage ($id: ID!) {
  vueRemarkPage(id: $id) {
    title
  }
}
</page-query>

It is also possible to use slots inside <VueRemarkContent>.

<VueRemarkContent>
  <template v-slot:tags>
    <ul>
      <li v-for="tag in $page.post.tags" :key="tag.id">
        <g-link to="tag.path">{{ tag.name }}</g-link>
      </li>
    </ul>
  </template>
</VueRemarkContent>

# Post title

<slot name="tags">

route

• Type: string

By default, each markdown file will get a path based on the file location. Use this option to generate paths based on a route pattern instead. Any front matter field is available to use in the path.

module.exports = {
  plugins: [
    {
      use: '@gridsome/vue-remark',
      options: {
        typeName: 'MarkdownPage',
        baseDir: './content',
        route: '/pages/:slug'
      }
    }
  ]
}

ignore

• Type: Array
• Default: []

List of glob patterns that should be ignored when searching for markdown files.

includePaths

• Type: Array
• Default: []

Paths or regex that should be parsed by this plugin. Use this option if you want to import md files as Vue components.

pathPrefix

• Type: string
• Default: '/'

The path for the first level index file in the directory specified by the baseDir option will become /. Use this option to prefix all paths.

index

• Type: Array
• Default: ['index']

Define which files to consider as index files. These files will not have their filename appear in its path and will become the main index.html file of the directory. Make sure there is only one possible index file per directory if multiple index names are defined.

plugins

Add additional Remark plugins. Read more.

refs

• Type: object

Define fields that will have a reference to another node. The referenced typeName is expected to exist. But a content type can also be created automatically if you set create: true. Read more about references.

module.exports = {
  plugins: [
    {
      use: '@gridsome/vue-remark',
      options: {
        typeName: 'Documentation',
        baseDir: './docs',
        refs: {
          // Example 1: Create a Author collection by reference `author` field
          author: 'Author',
          // Example 2: Create a Tag collection by reference `tags` field.
          tags: {
            typeName: 'Tag',
            create: true
          }
        }
      }
    }
  ]
}

remark

Custom Remark options. Read more.

Set layout for specific page in front matter

The generated Vue template has a simple div element as root component. Use a special layout option in front matter to specify a custom element to use as root component.

---
layout: ~/layouts/Default.vue
---

Passing props to the component:

---
layout:
  component: ~/layouts/Default.vue
  props:
    fullWidth: true
---