Introduction

The plugin registers a set of components which can be used directly in your Markdown files:

• ArtPlayer: Video player powered by ArtPlayer.
• PDFViewer: PDF viewer powered by EmbedPDF.
• VideoPlayer and AudioPlayer: Video and audio player powered by Video.js.
• BiliBiliEmbed, YouTubeEmbed, VimeoEmbed, TwitchEmbed, DailymotionEmbed, TikTokEmbed and SpotifyEmbed: Players provided by the platform itself.
• YouTubePlayer, VimeoPlayer, TwitchPlayer, TikTokPlayer and SpotifyPlayer: Players controlled by the Video.js skin.

Enable Feature

The plugin is disabled by default, you should set plugins.media in theme options to enable it:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : {
      : true,
      : true,
      : true,
      : true,
      : ["bilibili", "youtube"],
    },
  },
});

Then you can use the components in your Markdown files:

<ArtPlayer src="/assets/video.mp4" />

<BiliBiliEmbed bvid="BV1xx411c7mD" />

Link Syntax

Besides the components, the plugin also registers the @[name ...props](link) syntax for every enabled component. The syntax must occupy its own line.

@[youtube title="A video" width="80%"](https://youtu.be/dQw4w9WgXcQ)

@[video autoplay loop](/assets/video.mp4)

The link becomes the source of the component, and the props are passed to it as attributes, so options taking an object or a function are not available.

See the link syntax documentation for the syntax names and details.

Customize Config

vuepress-theme-hope passes plugins.media in theme options as plugin options to @vuepress/plugin-media.

You can check the media plugin documentation for available components, props and plugin options.

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

You can also pass an object to set the default height of code trees.

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : {
      : "400px",
    },
  },
});

Syntax

Wrap several code blocks in a code-tree container, and add a title="filepath" attribute to a code block to declare the file it belongs to.

• Text after the container marker is the title of the code tree.
• height declares the height of the code tree, a bare number is treated as pixels.
• entry declares the file opened by default, and :active on a code block has a higher priority.
• Code blocks without a title attribute are ignored, and files are arranged by their path.
• The first code block is opened by default when neither entry nor :active is declared.

Embedding a directory

Use @[code-tree](dir_path) to render all code files in a directory. A path starting with / is resolved from the source directory, any other path is resolved from the directory of the current page.

Demo

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Syntax

Use a file-tree container with a Markdown unordered list inside to describe the structure. Nested list items create subdirectories, and a trailing / keeps a directory collapsed.

The following notations are also supported:

• **name** highlights the file or directory name.
• name # comment adds a comment to the name.
• ++ name and -- name mark the file or directory as added or removed.
• ... or … adds a placeholder item.

Any text after the container marker becomes the title of the file tree.

Demo

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Syntax

Use a fields container to describe fields. Each line starting with @ followed by an inline code is a field item, and its attributes follow the closing backtick.

::: fields
@`theme` type=`ThemeConfig` required default=`{ base: '/' }`

Theme config.

@`enabled` type=boolean optional default=`true`

Whether it is enabled.

:::

All attributes are allowed and displayed as-is. The common ones are:

• type is displayed as a code block in the field header.
• default is displayed as a labeled code block below the field header.
• required, optional and deprecated are displayed as badges, and a deprecated field name is colored red and struck through.
• Other attributes are displayed as Name: value badges.

Nesting

To describe fields of an object type, nest a field item inside another one by increasing the leading @ by one for each level of nesting.

::: fields
@`options` type=object

Options.

@@`options.name` type=string

Option name.

:::

Demo

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Syntax

Use a plural directive to open a layout, a singular directive for its items, and @end to close it.

• Flexbox: @flexs opens a layout, and @flex adds an item.
• CSS Grid: @grids opens a layout, and @grid adds an item.
• Multi-column: @columns opens a layout, and @column adds an item.

Utilities separated by spaces are supported, such as gap-4, items-center, flex-1 and grid-cols-2, and they are converted to inline styles by default.

You can also use @flexs.nav#top gap-4 to add a class and an id to a layout.

Nesting is supported by closing each layout with @end, and you can use @@, @@@ to state the depth explicitly.

For all supported utilities and options, see @mdit/plugin-layout.

Demo

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Syntax

Wrap an ordered list (or an unordered list) in a steps container. Any Markdown syntax is allowed inside the steps.

Demo

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Usage

You can use a preview container to display a piece of content and it's source code.

If the displayed code differs from the source code of content, you can also use <VPPreview> component with its code and content slots.

Demo

The theme provides the following layouts:

• Layout: Basic layout
• NotFound: 404 page layout
• Slides (Only available when reveal.js is enabled)
• Blog (Only available when blog is enabled)

Customize Layouts with Slots

You can add new layouts or override existing layouts via layouts option in client config file.

The basic layouts can be imported from vuepress-theme-hope/client:

import { Layout, NotFound } from "vuepress-theme-hope/client";

The Blog layout can be imported from vuepress-theme-hope/blog:

import { Blog } from "vuepress-theme-hope/blog";

The Slides layout can be imported from @vuepress/plugin-revealjs/layouts:

import { SlidePage } from "@vuepress/plugin-revealjs/layouts";

Slots of <Layout>

Slots Available in All Type of Pages

• default

  The slot of page content, which is the main slot of the layout.

  Overriding the slot will override the whole page content (only navbar and sidebar are preserved).

  If you have some pages that is wholely built by Vue Components instead of Markdown, you can override this slot to build your own page.

• content

  A slot for page content, this replaces all content generated from Markdown, including contents coming from contentBefore and contentAfter.

• contentBefore

  A slot before content generated from Markdown, and after the page title and toc.

  Note: This slot won't work' when content slot is set.

• contentAfter

  A slot after content generated from Markdown, and before page meta and page nav.

  Note: This slot won't work' when content slot is set.

• navScreenTop

  A slot at the top of nav screen.

  The nav screen is the popup screen when you click the top right menu button in mobile view.

• navScreenBottom

  A slot at the bottom of nav screen.

  The nav screen is the popup screen when you click the top right menu button in mobile view.

• sidebarItems

  A slot for sidebar items.

• sidebarTop

  A slot at the top of sidebar.

• sidebarBottom

  A slot at the bottom of sidebar.

Slots Available in Content Page

• pageTop

  A slot at the top of the page content.

• pageBottom

  A slot at the bottom of the page content.

• toc

  A slot for table of contents, receiving a array of headings.

  This will override the default table of contents element. You can use this slot to build your own table of contents.

• tocBefore

  A slot in page toc, before the actual table of contents. Useful for adding sponsor links or ads.

• tocAfter

  A slot in page toc, after the actual table of contents. Useful for adding sponsor links or ads.

Slots Available in Home Page

• heroInfo: A slot for hero info.

• heroLogo: A slot for hero logo.

• heroBg: A slot for hero background.

• heroBefore: A slot before homepage hero.

• heroAfter: A slot after homepage hero.

Slots Available in Portfolio Page

• portfolioInfo: A slot for portfolio info.

• portfolioAvatar: A slot for portfolio avatar.

• portfolioBg: A slot for portfolio background.

Slots of <NotFound>

• default: 404 content slot

• navScreenTop

  A slot at the top of nav screen.

  The nav screen is the popup screen when you click the top right menu button in mobile view.

• navScreenBottom

  A slot at the bottom of nav screen.

  The nav screen is the popup screen when you click the top right menu button in mobile view.

Slots of <Blog>

Slots Available in all Blog Page

• default: Blog content slot

  The slot of page content, which is the main slot of the layout.

  Overriding the slot will override the whole page content (only navbar and sidebar are preserved).

  If you have some pages that is wholely built by Vue Components instead of Markdown, you can override this slot to build your own page.

• navScreenTop

  A slot at the top of nav screen.

  The nav screen is the popup screen when you click the top right menu button in mobile view.

• navScreenBottom

  A slot at the bottom of nav screen.

  The nav screen is the popup screen when you click the top right menu button in mobile view.

• articlesBefore: A slot before articles list.

• articlesAfter: A slot after articles list.

• bloggerInfo: A slot for blogger info.

• infoBefore: A slot before blog info panel.

• infoAfter: A slot after blog info panel.

Slots Available in Home, Category, Tag Page

• articleCover: A slot for article cover.

• articleTitle: A slot for article title.

• articleInfo: A slot for article info.

• articleExcerpt: A slot for article excerpt.

Slots Available in Blog Home Page

• content

  A slot for page content, this replaces all content generated from Markdown, including contents coming from contentBefore and contentAfter.

• contentBefore

  A slot before content generated from Markdown, and after the page title and toc.

  Note: This slot won't work' when content slot is set.

• contentAfter

  A slot after content generated from Markdown, and before page meta and page nav.

  Note: This slot won't work' when content slot is set.

• heroInfo: A slot for hero info.

• heroLogo: A slot for hero logo.

• heroBg: A slot for hero background.

• heroBefore: A slot before homepage hero.

• heroAfter: A slot after homepage hero.

The theme provides blog feature via @vuepress/plugin-icon. For instructions, please see Icon Intro.

This plugin can be disabled by setting plugins.icon to false.

Options

export type BuiltInIcon = "fontawesome-with-brands" | "fontawesome" | "iconify";

export type IconLink =
  `//${string}` | `/${string}` | `http://${string}` | `https://${string}`;

export type IconAsset = (BuiltInIcon | IconLink)[] | BuiltInIcon | IconLink;

export type IconType = "fontawesome" | "iconfont" | "iconify" | "unknown";

Options

type MarkdownHighlighterOptions =
  | ({ type: "prismjs" } & PrismjsPluginOptions)
  | ({ type: "shiki" } & ShikiPluginOptions);

Options

Options

Options

interface MarkdownKatexPluginOptions extends KatexOptions {
  type?: "katex";

  /**
   * Whether to allow inline math with spaces on ends
   *
   * @description NOT recommended to set this to true, because it will likely break the default usage of $
   *
   * @default false
   */
  allowInlineWithSpace?: boolean;

  /**
   * Whether enable copy plugin
   *
   * @default false
   */
  copy?: boolean;

  /**
   * Whether enable mhchem plugin
   *
   * @default false
   */
  mhchem?: boolean;
}

interface MarkdownMathjaxPluginOptions extends Omit<
  MarkdownItMathjaxOptions,
  "transformer"
> {
  type?: "mathjax";

  /**
   * Whether to allow inline math with spaces on ends
   *
   * @description NOT recommended to set this to true, because it will likely break the default usage of $
   *
   * @default false
   */
  allowInlineWithSpace?: boolean;

  /**
   * Output syntax
   *
   * @default 'svg'
   */
  output?: "chtml" | "svg";

  /**
   * Enable A11y
   *
   * @default true
   */
  a11y?: boolean;

  /**
   * TeX input options
   */
  tex?: MathJaxTexInputOptions;

  /**
   * Common HTML output options
   */
  chtml?: MathjaxCommonHTMLOutputOptions;

  /**
   * SVG output options
   */
  svg?: MathjaxSVGOutputOptions;
}

type MarkdownMathPluginOptions =
  MarkdownKatexPluginOptions | MarkdownMathjaxPluginOptions;

Options

You can use markdown.highlighter to choose the highlighter you want to use, shiki for shiki, prismjs for prism.js. You can also set markdown.highlighter to an object to pass options to the highlighter, while specifying the type of highlighter with the type field:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    // keyword "shiki" / "prismjs"
    // or an object format with type field
    : {
      : "shiki", // or "prismjs"

      // shiki or prism options
      // ...
    },
  },
});

The shiki plugin is built-in, so you don't need to install it. If you want to use prismjs, you need to install the plugin first:

Shiki

With @vuepress/plugin-shiki, you can use shiki to highlight your code blocks.

We support all options in @vuepress/plugin-shiki.

Prism.js

With @vuepress/plugin-prismjs, you can use prism.js to highlight your code blocks.

We support all options in @vuepress/plugin-prismjs.

Highlighter Features

The following features are both supported in shiki and prism.js, and is customizable via highlighter options.

Line Numbers

You can add :line-numbers / :no-line-numbers mark in your fenced code blocks to override the value set in config, and customize the beginning number by adding = after :line-numbers. For example, :line-numbers=2 means the line numbers in code blocks will start from 2.

Input:

```ts:line-numbers
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts :no-line-numbers
// line-numbers is disabled
const line2 = "This is line 2";
const line3 = "This is line 3";
```

```ts :line-numbers=2
// line-numbers is enabled and start from 2
const line3 = "This is line 3";
const line4 = "This is line 4";
```

Output:

// line-numbers is enabled
const line2 = "This is line 2";
const line3 = "This is line 3";

// line-numbers is disabled
const line2 = "This is line 2";
const line3 = "This is line 3";

// line-numbers is enabled and start from 2
const line3 = "This is line 3";
const line4 = "This is line 4";

Highlight Lines

You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks:

• Line ranges: {5-8}
• Multiple single lines: {4,7,9}
• Combined: {4,7-13,16,23-27,40}

Input:

```ts {1,7-9}
import { defaultTheme } from "@vuepress/theme-default";
import { defineUserConfig } from "vuepress";

export default defineUserConfig({
  title: "Hello, VuePress",

  theme: defaultTheme({
    logo: "https://vuepress.vuejs.org/images/hero.png",
  }),
});
```

Output:

import { defaultTheme } from "@vuepress/theme-default";
import { defineUserConfig } from "vuepress";

export default defineUserConfig({
  title: "Hello, VuePress",

  theme: defaultTheme({
    logo: "https://vuepress.vuejs.org/images/hero.png",
  }),
});

Line Collapsing

Disabled by default, can be enabled via collapsedLines in highlighter options.

You can add the :collapsed-lines / :no-collapsed-lines marker to the code block to override global settings. You can also add = after :collapsed-lines to customize the starting line number being collapsed, for example, :collapsed-lines=12 means collapsing the code block starting from line 12.

Input:

Collapse lines starting from 15:

```css :collapsed-lines=15
html {
  margin: 0;
  background: black;
  height: 100%;
}
/* ... more code */
```

Disabled collapsed lines:

```css :no-collapsed-lines
html {
  margin: 0;
  background: black;
  height: 100%;
}
/* ... more code */
```

Output:

Collapse lines starting from 15:

html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}

.blowup {
  display: block;
  position: absolute;
  object-fit: contain;
  object-position: center;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 2000;
}

.darken {
  opacity: 0.4;
}

Disabled collapsed lines:

html {
  margin: 0;
  background: black;
  height: 100%;
}

body {
  margin: 0;
  width: 100%;
  height: inherit;
}

/* the three main rows going down the page */

body > div {
  height: 25%;
}

.thumb {
  float: left;
  width: 25%;
  height: 100%;
  object-fit: cover;
}

.main {
  display: none;
}

.blowup {
  display: block;
  position: absolute;
  object-fit: contain;
  object-position: center;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  z-index: 2000;
}

.darken {
  opacity: 0.4;
}

Code Block Title

Add title="Title" after the code block ``` to set the title.

Input:

```ts title="foo/baz.js"
console.log("hello");
```

Output:

console.log("hello");

Notation Diff

Enabled by notationDiff: true in highlighter options.

Input:

```ts
console.log("hewwo"); // [!code --]
console.log("hello"); // [!code ++]
console.log("goodbye");
```

Output:

console.log("hewwo"); 
console.log("hello"); 
console.log("goodbye");

Notation Focus

Enabled by notationFocus: true in highlighter options.

Input:

```ts
console.log("Not focused");
console.log("Focused"); // [!code focus]
console.log("Not focused");
```

Output:

console.log("Not focused");
console.log("Focused"); 
console.log("Not focused");

Notation Highlight

Enabled by notationHighlight: true in highlighter options.

Input:

```ts
console.log("Not highlighted");
console.log("Highlighted"); // [!code highlight]
console.log("Not highlighted");
```

Output:

console.log("Not highlighted");
console.log("Highlighted"); 
console.log("Not highlighted");

Notation Error Level

Enabled by notationErrorLevel: true in highlighter options.

Input:

```ts
console.log("No errors or warnings");
console.warn("Warning"); // [!code warning]
console.error("Error"); // [!code error]
```

Output:

console.log("No errors or warnings");
console.warn("Warning"); 
console.error("Error"); 

Notation Word Highlight

Enabled by notationWordHighlight: true in highlighter options.

Input:

```ts
// [!code word:Hello]
const message = "Hello World";
console.log(message); // prints Hello World
```

Output:

// [!code word:Hello]
const message = "Hello World";
console.log(message); // prints Hello World

You can highlight words based on the meta string provided on the code snippet

Input:

```js /Hello/
const msg = "Hello World";
console.log(msg);
console.log(msg); // prints Hello World
```

Output:

const msg = "Hello World";
console.log(msg);
console.log(msg); // prints Hello World

Whitespace

Control rendering of whitespace characters (Space and Tab) in code blocks via whitespace option in highlighter options.

• true: enable render whitespace, same of all
• false: disable render whitespace
• 'all': render all whitespace
• 'boundary': render leading and trailing whitespace of the line
• 'trailing': render trailing whitespace of the line

You can add :whitespace / :no-whitespace mark in your fenced code blocks to override the value set in config, and customize the render type by adding = after :whitespace. For example :whitespace=boundary will render leading and trailing whitespace of the line.

Input:

```md :whitespace
<!-- render all whitespace -->

A text  
with trailing spaces

    indented text
```

```md :whitespace=boundary
<!-- render leading and trailing whitespace of the line -->

A text  
with trailing spaces

    indented text
```

```md :whitespace=trailing
<!-- render trailing whitespace of the line -->

A text  
with trailing spaces

    indented text
```

```md :no-whitespace
<!-- disable render whitespace -->

A text  
with trailing spaces

    indented text
```

Output:

<!-- render all whitespace -->

A text  
with trailing spaces

    indented text

<!-- render leading and trailing whitespace of the line -->

A text  
with trailing spaces

    indented text

<!-- render trailing whitespace of the line -->

A text  
with trailing spaces

    indented text

<!-- disable render whitespace -->

A text  
with trailing spaces

    indented text

Copy Button

The theme uses @vuepress/plugin-copy-code to add copy buttons on all fenced code blocks.

By default, the copy button is only displayed on desktop mode. Set plugins.copyCode.showInMobile to true in theme options to display this button on mobile devices.

A success hint will be displayed once user press the copy button, and its default duration is 2000 ms, you can customize it with plugins.copyCode.duration in theme options, and you can disable the hint by setting duration to 0.

To use this layout, you should set home: true and portfolio: true in the page front matter.

Personal Information

The name is default to author option in theme options, while you can set name in frontmatter to customize it. The welcome message can also be customized through welcome option in frontmatter.

To describe yourself, set titles in frontmatter with titles that fits you. You are also expected to set a image of yours with avatar (and avatarDark for dark mode if needed). You can also set bgImage (and bgImageDark for dark mode if needed) to customize background image. Advanced style adjusting can be done with avatarStyle and bgImageStyle option.

You can set social medias using medias in frontmatter with name icon and url for each media. When blog feature is enabled, media links set in blog.medias are displayed by default.

By default, we will apply special styles to contents in portfolio page, you may set content: doc in frontmatter to revert to original style, or set content: none to hide Markdown contents.

Introduction

You can set multiple notices for different paths in the site with plugins.notice.

Each notice options needs to contain a path or match option, which is used to match the path. The path option is a string, which matches all paths starting with this, and the match option is a regexp to test the page route path against.

A notice configuration item includes:

• title: Notice title, support both text and HTMLString

• content: Notice content, support both text and HTMLString

• actions: Notice actions

  Should be an array of objects containing:

  • text: action text

  • link: action link (optional).

    Pathname will be treated as internal route link and handled by router, and full URL will be treated as external link and being opened in new window.

  • type: "default" or "primary" (optional)

    Default value is "default".

Here is an example:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : [
      {
        : "/",
        : "Notice Title",
        : "Notice Content",
        : [
          {
            : "Primary Action",
            : "https://theme-hope.vuejs.press/",
            : "primary",
          },
          { : "Default Action" },
        ],
      },
      {
        : "/zh/",
        : "Notice Title",
        : "Notice Content",
        : [
          {
            : "Primary Action",
            : "https://theme-hope.vuejs.press/",
            : "primary",
          },
          { : "Default Action" },
        ],
      },
    ],
  },
});

Also, we provide some advanced option for you to control notice display.

Introduction

To use it, install @vuepress/plugin-watermark

You can customize the watermark behavior with plugins.watermark in theme options, or with watermark in page frontmatter.

The simplest way is to set it to true to get a site name watermark:

• Enable globally:

  .vuepress/theme.ts

  import {  } from "vuepress-theme-hope";
  
  export default ({
    : {
      : true,
    },
  });

• Enable in a specific page:

  example.md

• Chart.js: A lightweight, easy-to-use, highly customizable chart library.

  Chart.js is lighter comparing to ECharts.

• ECharts: A powerful, interactive charting and visualization library for browser.

  ECharts is more powerful comparing to Chart.js.

• Flowchart: A simple markdown extension to generate flowcharts and sequence diagrams.

  Lightweight, only focusing on flowcharts.

• Markmap: Create mindmap with markdown

  The runtime is very heavy, not recommended.

• Mermaid: Generation of diagram and flowchart from text in a similar manner as markdown.

  Powerful collection of common charts.

• Plantuml: UML diagram driven by Java.

  No runtime.

Demo

Chart.js

• View Detail

ECharts

• View Detail

Flowchart

• View Detail

Markmap

Settings

Install markmap-lib, markmap-toolbar and markmap-view in your project:

Then enabling via:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Syntax

```markmap
<!-- contents here -->
```

Configuring through frontmatter syntax is supported.

Demo

Settings

You can enable this feature via:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Syntax

You can insert the same content that plantuml supports, for example:

@startuml
content
@enduml

Demo

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Usage

This is the same as tabs feature, but it's special built for code blocks.

Only the first code fence after @tab marker is rendered inside code tabs, other Markdown content will be ignored.

Demo

• Image: Covert to figure, switched with color scheme and setting size
• Tasklist
• TeX: Support KaTeX and Mathjax

Demo

Image Enhancement

Support setting title, color scheme and size

• View Detail

Math

• View Detail

Task List

• Plan A
• Plan B

View Detail

• Hint Container: Stylized hint
• Align: Customize content alignment
• Attrs: Adding attrs to Markdown contents
• Layout: Flexbox, grid and multi-column layouts
• Mark: Highlight contents
• Superscript and Subscript
• Spoiler: Hide spoiler content
• Steps: Show content as progressive steps
• Stylize: Customizable token stylizer

Demo

Hint Container

• View Detail

Align

• View Detail

Attrs

A word having id.

• View Detail

Layout

• View Detail

Mark

You can mark important words.

• View Detail

Spoiler

VuePress Theme Hope is powerful.

• View Detail

Steps

• View Detail

Stylize

Donate Mr.Hope a cup of coffee.

• View Detail

Superscript and Subscript

19^th H₂O

• View Detail

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Demo

Settings

Hint box is enabled by default, and we allow you to disable it:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    // disable hint box
    : false,
  },
});

Demo

Settings

Install sandpack-vue3 in your project:

Then enabling via:

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,
  },
});

Usage

To use sandpack playground, you should use a container named sandpack#template.

In it, you can use 3 directives:

• @file FullPathFile then a code block to add files, you can also set the file options, for example: @file FullPathFile [active readOnly hidden]
• @options then a javascript block to customize "options"
• @setup then a javascript block to customize "customSetup"

You can see the below demos to see more details.

You can import and call defineSandpackConfig in client config file to customize sandpack-vue3:

import { defineSandpackConfig } from "vuepress-plugin-md-enhance/client";

defineSandpackConfig({
  // sandpack config here
});

Demo

You can use extendsMarkdown hook in config file to add Markdown extensions:

import { defineUserConfig } from "vuepress";

export default defineUserConfig({
  // site config
  // ...

  extendsMarkdown: (md) => {
    md.use(yourMdItPlugin, options);
  },
});

Foldable Sidebar / TOC on Mobile / Left Sidebar on PC

To better adapt to different sizes of devices, the theme uses responsive layout to adjust the layout according to the screen width.

Since the layout is pre-rendered, all sizes of screens share the same DOM structure. To correctly render FCP and for better performance, different size layouts are almost entirely rendered by CSS rather than controlling by scripts. We implement several sets of CSS to display different layouts with same DOM structure. This means that you cannot customize these layouts or adjust their order.

The only thing you can configure is the CSS breakpoint. The default breakpoints are as follows:

The theme adds built-in support for the following 5 plugins:

• @vuepress/plugin-docsearch
• @vuepress/plugin-meilisearch
• @vuepress/plugin-slimsearch
• @vuepress/plugin-orama
• @vuepress/plugin-search

plugins.docsearch

Options which will be passed to @vuepress/plugin-docsearch. For details, see DocSearch plugin documentation.

plugins.meilisearch

Options which will be passed to @vuepress/plugin-meilisearch. For details, see MeiliSearch plugin documentation.

plugins.slimsearch

You can set it to true to enable it directly, or an object to configure will be passed to @vuepress/plugin-slimsearch.

For details, see SlimSearch plugin documentation.

plugins.orama

You can set it to true to enable it directly, or an object to configure will be passed to @vuepress/plugin-orama.

For details, see Orama plugin documentation.

plugins.search

You can set it to true to enable it directly, or an object to configure will be passed to @vuepress/plugin-search.

For details, see search plugin documentation.

Register Components Globally

You can register components globally, so that you can use theme directly in Markdown files and Layouts.

Register via @vuepress/plugin-register-components

You can automatically register components via the @vuepress/plugin-register-components plugin.

For details about how to use the plugin, see Official Documentation.

Register via Client Config File

You can create .vuepress/client.js or .vuepress/client.ts and register components manually.

import { defineClientConfig } from "vuepress/client";
import MyComponent from "./MyComponent.vue";

export default defineClientConfig({
  enhance: ({ app, router, siteData }) => {
    app.component("MyComponent", MyComponent);
  },
});

Usage

Global component can be directly used in any component, layouts or pages.

Assume that you have registered MyComponent globally, then you can use it like:

• Markdown:

  example.md

  <MyComponent />

• Component:

  .vuepress/components/Example.vue

  <template>
    <p>Example Component</p>
    <MyComponent />
  </template>

• Layout:

  .vuepress/layouts/Custom.vue

  <template>
    <p>Example Layout</p>
    <MyComponent />
  </template>

Markdown to Vue SFC

Every Markdown file is first compiled to HTML and then converted to a Vue Single File Component (SFC). In other words, you can write Markdown files like Vue SFC.

• <script> and <style> tags are directly treated as tags in Vue SFC. In other words, they are promoted from the <template> tag to the top level of the SFC.
• All content other than <script> and <style> tags will be compiled to HTML and then treated as <template> tags in Vue SFC.

The converted Vue SFC will be cached in the .vuepress/.temp/pages directory, and will be rendered by the internal <Content /> component.

Using Vue syntax in Markdown

You can use Vue syntax directly in Markdown, for details see VuePress → Markdown.

Importing files

• You can use @source alias to reference the source directory of the current project

  Markdown file

  <MyComponent />
  
  <script setup>
  import MyComponent from "@source/example/MyComponent.vue";
  </script>

• You can also use alias option:

• Code Tabs: Add tabs to your code block.
• Code Demo: Display and run code snippets in browser.
• File Tree: Display a directory structure.
• Code Tree: Display the code blocks of several files together with a file tree.
• Playground: Embed external playground site.
• Kotlin Playground: Reactive kotlin playground.
• Vue Playground: Reactive vue playground.

Demo

Code Tabs

• View Detail

Code Demo

• View Detail

Playground

• View Detail

Kotlin Playground

• View Detail

Vue Playground

• View Detail

Sandpack

• View Detail

File Tree

• View Detail

Code Tree

• View Detail

Example

import { defineClientConfig } from "vuepress/client";
import { onMounted } from "vue";
import ExampleGlobalComponent from "./components/ExampleGlobalComponent.vue";
import ExampleRootComponent from "./components/ExampleRootComponent.vue";
import { setupExampleCompositionAPI } from "./composables/exampleCompositionAPI";
import ExampleLayout from "./layouts/ExampleLayout.vue";

export default defineClientConfig({
  // Client enhancements
  enhance: ({ app, router }) => {
    // register global component
    app.component("ExampleGlobalComponent", ExampleGlobalComponent);

    // register router guard
    router.beforeEach((to) => {
      console.log("before navigation");
    });

    router.afterEach((to) => {
      console.log("after navigation");
    });
  },

  // global registration
  setup() {
    // Register the global Composition API
    setupExampleCompositionAPI();

    // access DOM in client
    onMounted(() => {
      // use DOM API after mounted
      document.querySelector("#app");
    });
  },

  // adding or overriding layouts
  layouts: {
    ExampleLayout,
  },

  // global component
  rootComponents: [
    "ExampleRootComponent",
    //...
  ],
});

Clear Effects

By default, the theme will:

• Use color list to decorate categories and tags
• Add animation when switching pages and elements
• Add ease-in animations to homepage elements, and add hovering effects to features.
• Use a more fancy code copy button
• Use fancy tooltips.
• Added fade-in when switching between day mode and night mode

If you need to remove these fancy styles, please set pure: true in the theme options to enable pure mode.

Meanwhile, you can control the duration of the animation by controlling $color-transition and transform-transition in the palette file:

$color-transition: 0s;
$transform-transition: 0s;

Global

If you need to add global CSS and JS, please set head option in VuePress config file.

import {  } from "vuepress";

export default ({
  //...

  : [
    //...

    // import an external script
    ["script", { : "YOUR_SCRIPT_LINK" }],
    // add a script
    [
      "script",
      {},
      `\
        // your script here
      `,
    ],
    // add an external CSS
    ["link", { : "stylesheet", : "YOUR_STYLE_LINK" }],
    // add a style
    // We don't recommend this, you should prefer to use .vuepress/style/index.scss
    [
      "style",
      {},
      `\
        /* your style here */
      `,
    ],
  ],

  //...
});

Per Page

If you need to add page-level CSS and JS, please set head option in frontmatter.

With Theme Options

The theme provides many layout-related options for you to customize the layout of the theme. For details about these options, see Theme Configuration → Layout.

Responsive BreakPoints

The theme will automatically apply responsive layouts under different screen widths. If you need to modify these breakpoints, you can modify them in style config file.

// Modify the breakpoint of the desktop layout
$pc = 1280px;

For details about breakpoint variables $pc, $laptop, $pad, $tablet, $mobile, see Theme Configuration → Styles.

Layout Size

The theme provides common size variables in the style palette file, and you can modify these variables in the palette file to achieve the purpose of modifying the layout size.

// Modify the height of the navigation bar
$navbar-height = 80px;

Introduction of layout variables can be found at Theme Configuration → Style.

Via Style File

The style file is .vuepress/styles/index.scss in the project directory, where you can put your own styles.

• If you are not satisfied with the style of the theme, you can adjust the style of the theme components through the style file.

  Note

  In order to override the original style, you need to use the same or higher priority selector or use !important directly.

• If you want to remove some features, you can hide related dom elements by display: none in the style file.

Via Adding / Overriding Layouts

You can add new layouts or override existing layouts via layouts option in client config file.

See Customize Layouts with Slots for how to add or override layouts.

Via Overriding Components

See Replace theme components.

Introduction

This feature is enabled by default. If there is no README.md in the folder, the theme will automatically generate a directory page for it. To disable, set plugins.catalog to false.

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : false,
  },
});

You can control catalog behavior via plugins.catalog in the theme options, for example:

• Exclude some folders from catalog generation via plugins.catalog.exclude
• Control frontmatter generation through plugins.catalog.frontmatter.

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : {
      : () => {
        if (.("/zh/")) return { : "目录" };

        return { : "Catalog" };
      },
      : ["/api/", "/zh/api/"],
    },
  },
});

For detailed configuration, see Catalog plugin docs.

Catalog Component

You can use the <Catalog> component directly in Markdown to display the catalog.

Component related

Bing Wallpapers

Replace the background of your blog's homepage with daily Bing wallpaper.

Usage:

Override heroBg slot of <Blog> with the component from "vuepress-theme-hope/presets/BingHeroBackground.js".

<script setup lang="ts">
import { Blog } from "vuepress-theme-hope/blog";
import BingHeroBackground from "vuepress-theme-hope/presets/BingHeroBackground.js";
</script>

<template>
  <Blog>
    <template #heroBg>
      <BingHeroBackground />
    </template>
  </Blog>
</template>

import { defineClientConfig } from "vuepress/client";
import Blog from "./layouts/Blog.vue";

export default defineClientConfig({
  //...

  layouts: {
    // ...
    Blog,
  },
});

Hitokoto Description

Replace the description of the blog's home page with a random Hitokoto sentence (Chinese only).

Usage:

Override heroInfo slot of <Blog> with the component from "vuepress-theme-hope/presets/HitokotoBlogHero.js".

<script setup lang="ts">
import { Blog } from "vuepress-theme-hope/blog";
import HitokotoBlogHero from "vuepress-theme-hope/presets/HitokotoBlogHero.js";
</script>

<template>
  <Blog>
    <template #heroInfo="data">
      <HitokotoBlogHero v-bind="data" />
    </template>
  </Blog>
</template>

import { defineClientConfig } from "vuepress/client";
import Blog from "./layouts/Blog.vue";

export default defineClientConfig({
  //...

  layouts: {
    // ...
    Blog,
  },
});

Composable Related

Transparent Navbar

Make navbar transparent in certain pages while at page top.

export declare const setupTransparentNavbar: (options?: {
  /**
   * @default 'blog-homepage'
   */
  type?: "homepage" | "blog-homepage" | "all";

  /**
   * Transparent threshold
   *
   * @default 50
   */
  threshold?: number;

  /**
   * Text color in light mode
   */
  light?: string;

  /**
   * Text color in dark mode
   */
  dark?: string;
}) => void;

import {  } from "vuepress/client";
import {  } from "vuepress-theme-hope/presets/transparentNavbar.js";

export default ({
  : () => {
    ({ : "homepage" });
  },
});

Running time

Display running time of the site in footer.

export declare const setupRunningTimeFooter: (
  /**
   * The date to calculate the running time
   */
  date: string | Date,
  /**
   * The locales of running time
   *
   * @description :day, :hour, :minute, :second will be replaced by the corresponding value
   *
   * @default { "/": "Running time: :day days :hour hours :minute minutes :second seconds" }
   */
  locales?: Record<string, string>,
  /**
   * Whether to preserve the original content of the footer
   *
   * @default false
   */
  preserveContent?: boolean,
) => void;

import {  } from "vuepress/client";
import {  } from "vuepress-theme-hope/presets/footerRunningTime.js";

export default ({
  () {
    (
      new ("2022-01-01"),
      {
        "/": "Running time: :day days :hour hours :minute minutes :second seconds",
        "/zh/": "已运行 :day 天 :hour 小时 :minute 分钟 :second 秒",
      },
      true,
    );
  },
});

Snowfall

Add snowfall effect to the site.

export declare const setupSnowFall: (options: {
  /**
   * Image of snowflake
   */
  image?: string;

  /**
   * Count of snowflakes
   *
   * @default 25
   */
  count?: number;

  /**
   * Min size of snowflake in pixels
   *
   * @default 5
   */
  minSize?: number;

  /**
   * Max size of snowflake in pixels
   *
   * @default 10
   */
  maxSize?: number;

  /**
   * Speed of snowflake
   *
   * @default 1
   */
  speed?: number;
}) => void;

import {  } from "vuepress/client";
import {  } from "vuepress-theme-hope/presets/snowFall.js";

export default ({
  () {
    ();
  },
});

Config Related

Custom Blog Types

• Recent Updated:

  // vuepress-theme-hope/presets/getRecentUpdatedArticles.js
  export interface RecentUpdateArticlesOptions {
    /**
     * Path of this blog type
     *
     * @default "/recent-updated/"
     */
    path?: string;
  
    /**
     * Locale text for the blog type
     *
     * @example {
     *  '/': 'Recent Updated',
     *  '/zh/': '最近更新',
     * }
     */
    locales?: Record<string, string>;
  }
  
  export declare const getRecentUpdatedArticles: (
    options: RecentUpdateArticlesOptions,
  ) => BlogTypeOptions;
  Code Example

  .vuepress/theme.ts

  import {  } from "vuepress-theme-hope";
  import {  } from "vuepress-theme-hope/presets/getRecentUpdatedArticles.js";
  
  export default ({
    : {
      : {
        : [
          ({
            : {
              "/": "Recent Updated",
              "/zh/": "最近更新",
            },
          }),
        ],
      },
    },
  });

• Slides:

  // vuepress-theme-hope/presets/getSlides.js
  export interface SlidesOptions {
    /**
     * Path of this blog type
     *
     * @default "/slides/"
     */
    path?: string;
  
    /**
     * Locales for the blog type
     *
     * @example {
     *  '/': 'Slides',
     *  '/zh/': '幻灯片',
     * }
     */
    locales?: Record<string, string>;
  }
  
  export declare const getSlides = (options: SlidesOptions) => BlogTypeOptions;
  Code Example

  .vuepress/theme.ts

  import {  } from "vuepress-theme-hope";
  import {  } from "vuepress-theme-hope/presets/getSlides.js";
  
  export default ({
    : {
      : {
        : [
          ({
            : {
              "/": "Slides",
              "/zh/": "幻灯片",
            },
          }),
        ],
      },
    },
  });

Style Related

You can create a client config file and import the following files through the import statement.

Docs

• "vuepress-theme-hope/presets/shinning-feature-panel.scss": Add shinning effect to the features of the project home page.

Blog

• "vuepress-theme-hope/presets/left-blog-info.scss": Move the blogger information to the left of the article list.
• "vuepress-theme-hope/presets/round-blogger-avatar.scss": Clip blogger avatar to round shape
• "vuepress-theme-hope/presets/squircle-blogger-avatar.scss": Clip blogger avatar to a squircle

Others

• "vuepress-theme-hope/presets/bounce-icon.scss": Add a mouseover bounce effect to the page icon.
• "vuepress-theme-hope/presets/hide-navbar-icon.scss": Hide navbar icon.
• "vuepress-theme-hope/presets/hide-sidebar-icon.scss": Hide sidebar icon.
• "vuepress-theme-hope/presets/hr-driving-car.scss": Add a driving car to all hr elements

More

If you have great customizations based on VuePress Theme Hope, you can pull them out into presets and send us a PR.

You can customize the theme layout through these slots, and what you can do depends entirely on your imagination, such as:

• Add a banner ad to your document or blog via the contentBefore slot
• Add a donate button to your docs or blog via contentAfter slot
• Add a list of sponsors to your docs or blogs via the tocBefore slot
• Add a QR code to your docs or blog via the tocAfter slot

Settings

import {  } from "vuepress-theme-hope";

export default ({
  : {
    : true,

    // other options...
  },
});

Usage

You can use component fence block to add a component into your markdown content. Both YAML and JSON format props data are supported:

• YAML :

  ```component ComponentName
  # component data here
  ```

• JSON:

  ```component ComponentName
  {
    // component data here
  }
  ```

Demo

<VPCard> here is a global component.

The above code blocks are equivalent to:

<VPCard
  title="Mr.Hope"
  desc="Where there is light, there is hope"
  logo="https://mister-hope.com/logo.svg"
  link="https://mister-hope.com"
  background="rgba(253, 230, 138, 0.15)"
/>

The behavior option can also accept a boolean value:

• false: options set tofalse with false value
• true: { check: true, compact: true, custom: false, debug: false }

import {  } from "vuepress";
import {  } from "vuepress-theme-hope";

export default ({
  // siteConfig here
  // ...

  : (
    {
      // themeConfig here
      // ...
    },
    {
      // theme behavior options here (optional)
    },
  ),
});

Options

Introduction to Responsive Layout

On mobile devices:

• In navbar, site name will be hidden, and elements such as navbar links, theme switch, and full-screen button will be collapsed into additional pop-up window, and toggled through the button on the right side of navbar;
• The sidebar will be displayed in the form of a side menu and hidden by default, and the sidebar toggle button is displayed on the left side of navbar to control the pop-up and retraction of the sidebar;
• Path navigation, body text, back to top button text has smaller font size
• The title of the current page is collapsed into the sidebar

On tablet/laptop devices:

• Navbar links will appear in the navbar
• The sidebar will be displayed as a collapsible menu
• The title of the current page is collapsed into the sidebar

On pc device:

• Navbar links will appear in the navbar
• The sidebar will stick to the left side of the content on the page
• The title of the current page will be displayed on the right side of the page

Responsive configuration

Themes provide breakpoint variables for controlling responsive layout behavior. You can modify them in .vuepress/styles/config.scss:

• $pc: PC responsive layout breakpoint, default is 1440px
• $laptop: notebook responsive layout breakpoint, default is 1280px
• $pad: Large pad responsive layout breakpoint, defaults to 959px
• $tablet: Tablet responsive layout breakpoint, default is 768px
• $mobile: Mobile responsive layout breakpoint, default is 480px

Modify the built-in color

The theme controls the color through config file and palette file. These files are .vuepress/styles/{config|palette}.scss files under the VuePress project folder.

You may need to set colors under two situations:

1. This color remains the same in day mode and night mode, e.g.: theme color.
2. This color is different in light mode and dark mode, such as background color, font color, border color, etc.

For the former, you need to write variable values directly, e.g.:

$theme-color: #3eaf7c;

For the latter, you need to set a color map with light and dark keys and color values, e.g.:

$vp-c-bg: (
  light: #fff,
  dark: #000,
);

See Theme Configuration → Color Settings for all available color variables.

Modify other colors

Sometimes, you may want to modify some colors that are not in palette.scss, such as the background color of the code block. At this time, you can check whether the corresponding color attribute value is a CSS variable through the devTools.

If so, you can go to index.scss to manually override this variable value:

// override code block background color
#app {
  --code-c-bg: #fff;

  [data-theme="dark"] & {
    --code-c-bg: #000;
  }
}

If not, write your own selectors to override them:

// override code block background color
pre[class*="language-"] {
  background-color: #fff !important;

  [data-theme="dark"] & {
    background-color: #222 !important;
  }
}

Font Family

For common font families, they can generally be divided into serif^[1] and sans-serif^[2].

Modifying Fonts

The theme provides $vp-font, $vp-font-heading and $vp-font-mono three variables to control the font in .vuepress/styles/palette.scss.

• $vp-font: the font used on normal text
• $vp-font-heading: font for heading elements
• $vp-font-mono: the font used in code block and inline codes

By default, the theme uses sans serif with normal text.

$vp-font: 'Georgia, -apple-system, "Nimbus Roman No9 L", sans-serif';

Fallback Font

Because different platforms, different operating systems, and different installation methods (slim/full) will cause huge differences in the number and types of fonts in the font library, you should set as many fonts as possible, and ensure that the fallback fonts ^[3] exists.

Font Library

You can find more fonts in Google Fonts, and you can preview and download them online.

Please search and select the font and weight you want in the webpage, then click the Select button on the right to add it to your selection list, then click the button in the upper right corner to view your favorite fonts and get the link Imported in the configuration file of VuePress.

We assume that you have selected the 400 and 700 italic fonts of Lora font. After clicking the button in the upper right corner, Google will give the following code in the sidebar:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,400;1,700&display=swap"
  rel="stylesheet"
/>

font-family: "Lora", serif;

Then all you need to do is import and use them by adding the following code in the VuePress configuration file:

import {  } from "vuepress";

export default ({
  //...

  : [
    //...

    // Import the corresponding link
    ["link", { : "preconnect", : "https://fonts.googleapis.com" }],
    [
      "link",
      { : "preconnect", : "https://fonts.gstatic.com", : "" },
    ],
    [
      "link",
      {
        : "https://fonts.googleapis.com/css2?family=Noto+Serif+SC:wght@400;500;700&display=swap",
        : "stylesheet",
      },
    ],
  ],

  //...
});

Also modify the $vp-font variable in the palette file:

// apply font
$vp-font: "Lora, serif";

In this way, you can use lora font in your website.