@gridsome/vue-remark
v0.2.6
Published
Use Vue Components in Markdown
Downloads
995
Maintainers
Readme
@gridsome/vue-remark
Create pages with Vue components in Markdown. Perfect for building Documentation, Design Systems, Portfolios, Blogs, etc.
Install
yarn add @gridsome/vue-remark
npm 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
---