Add Optimized Video to Documentation in VuePress

Banner for a MediaJam post

Teri Eyenike

Video optimization is essential in today’s media, as it helps reduce file sizes and loading times before reaching users’ devices. You don’t want a high bounce rate when users visit your platform if the video size is heavy and takes too much time to load.

VuePress is a static site generator (SSG) powered by the Vue theming system, which is optimized for technical documentation with its project structure centered around markdown.

In this tutorial, you will learn how to add an optimized video to a documentation system in VuePress, with Cloudinary acting as the cloud-based media hosting and transformation service for your media assets.


The completed demo for this project is in a CodeSandbox. Fork it to run the code.


Check out the complete source here.


Completing this project requires the following:

  • Basic understanding of Vue.js.
  • A Cloudinary account. Signup is free!
  • Node>10+ and yarn installed on your local machine.

Getting started with VuePress

To scaffold a VuePress project, run the following command in your terminal:

1yarn create vuepress-site [optionalDirectoryName]

Replace [optionalDirectoryName] with your desired project name.

The above command prompts you with some details to further configure your VuePress site’s metadata, which should look like this when done:

Inside the current directory, navigate to the docs folder that contains the scaffolded documentation site by installing the dependencies and start the local development server with the following command:

1cd docs
3yarn install
5yarn dev

The project will be accessible by default on http://localhost:8080.

Creating documentation in VuePress

Let’s begin by working on the homepage of the documentation site details by changing some of its content.

Copy and paste the following frontmatter block in the docs/src/ file:

1<!-- docs/src/ -->
4home: true
5tagline: Using Cloudinary video player and provide a user with the option to utilize Cloudinary video optimizations
6actionText: View optimized video →
7actionLink: /video/
9footer: Made by teri eyenike with ❤️

The above layout does the following:

  • home: true: represents a front page for visitors to see
  • actionLink: the call-to-action (CTA) button link to the actionText

All other details represent how much or how little you want to present content on your site. You are limited to what appears on the homepage.

Here is what the page should look like:

Next, update the other details on the homepage, such as the logo, navigation links, and the heading title in the docs/src/.vuepress/config.js file:

1// docs/src/.vuepress/config.js
3// import
5module.exports = {
6 title: 'Optimized video',
7 ...,
8 themeConfig: {
9 ...
10 nav: [
11 {
12 text: 'Video',
13 link: '/video/',
14 },
15 ],
16 sidebar: {
17 '/video/': [
18 {
19 title: 'Video',
20 collapsable: false,
21 children: [''],
22 },
23 ],
24 },
25 },
26 ...

The code block above does the following:

  • title: For the navbar and the page title for the site
  • nav: An array of objects that has the key-value pair for the text and link to the individual page on the site
  • sidebar: An array of links essential for navigating the site

Next, update the styles and include the following code in the docs/src/.vuepress/styles/index.styl file:

1// docs/src/.vuepress/styles/index.styl
3.home .hero img
4 max-width 450px !important
7 max-width 100%
8 display block
11.home .footer
12 position absolute
13 bottom 0
14 left 50%
15 width 100%
16 transform translate(-50%, -50%)

Here is the look of the page now:

Setup Cloudinary in VuePress

In this project, we’ll use Cloudinary to store the media assets on the site. So, let’s install the Cloudinary Vue SDK with the following command:

1yarn add cloudinary-vue
  • cloudinary-vue: It allows you to integrate your application with Cloudinary.

Host videos using Cloudinary

Now, head over to Cloudinary and upload a media asset in the form of video, which enables you to have access through its public ID used in the application.

The created video-player folder stores the uploaded videos, and each video has a unique ID called public-id like the one used in our application called gushing-waterfall.

Also, you need to obtain your cloud name from your dashboard.

Creating an optimized video

The documentation site needs an optimized video using the Vue component to present to users of the site.

In the .vuepress folder, create a file, VideoComponent.vue, in the components directory. Copy and paste the following:

1// docs/src/.vuepress/components/VideoComponent.vue
4 <div>
5 <cld-video
6 cloud-name="terieyenike"
7 controls
8 :public-id="publicId"
9 >
10 </cld-video>
11 </div>
15import Cloudinary from "cloudinary-vue";
16import Vue from "vue";
18export default {
19 data() {
20 return {
21 publicId: 'video-player/gushing-waterfall'
22 };
23 },

The code snippet above does the following:

  • Imports the Cloudinary components from the cloudinary-vue library and Vue.
  • In the data object, passes the publicId data set to the uploaded video asset with its public ID.
  • Also included is the rendered Cloudinary video tag with the cloud name, controls for the video, and the bind directive attribute for the public ID.

Next, import the above video component into the file in the video folder. Copy and paste the following:

1<!-- docs/src/video/ -->
3# Cloudinary transformations
5The syntax for transforming and delivering videos is generally similar to that for images, and you can apply the
6majority of available image transformations to video as well. For example, you can resize, crop, rotate, set video
7quality and format or use auto quality and/or auto format, add text or image overlays to your videos, and more.
9There are also a number of special options you can use for transforming and delivering video content. For example, you
10can adjust their size, shape, speed, duration, quality, and appearance. There are also some features that are specific
11to audio.
14<VideoComponent />

Note: In VuePress, every or file contained in each sub-directory will automatically be converted to index.html with its corresponding URL /.

Your page should look like this:

Optimizing video in VuePress

Optimized videos are vital for efficiency and performance.

In the VideoComponent.vue file, include the following transformations to the parent <cld-video> tag.

1// docs/src/.vuepress/components/VideoComponent.vue
4 <div>
5 <cld-video cloud-name="terieyenike" controls public-id="video-player/gushing-waterfall">
6 <cld-transformation width="500" crop="scale" />
7 <cld-transformation fetch-fomat="auto" />
8 </cld-video>
9 </div>
  • The <cld-transformation> allows you to define transformation on the parent component <cld-video> with the video scaled down to a width of 500 pixels.
  • fetch-format set to auto delivers your video asset in the most optimal format to minimize file size for the user browser.

With everything complete, your page should look like this:


This article explained how to produce optimized videos for a documentation site using Cloudinary video transformations. Try these processes and boost the loading time of your website!

Learn More

Teri Eyenike

Software Developer

Teri Eyenike is a software developer interested in making things simple and usable.