注意

This article is a tutorial for embedding local font files into your VuePress site. For fonts that are available on the web, you can simply use their CDN links in your stylesheet.

注意

ttf (truetype) files may appear to be broken in some cases (e.g., in Visual Studio Code Simple Browser), while otf (opentype) files work fine. Other types are untested.

It is suggeseted to use otf files for better compatibility.

TL;DR

To embed fonts, you simply put the files under a static directory and reference them in your stylesheets.

The static reference takes effort in configuring an alias for the static directory in your config.ts configuration file.

Step 1: Configure the Static Directory

1. Create a Static Directory

Create a static directory right under your .vuepress directory.

Example

Let's assume the static directory is .vuepress/styles, and the font file you want to embed is named font.otf.

提示

You can refer to the official documentation (from theme Hope) for more information about aliases.

2. Create an Alias

In your config.ts, add an alias for the static directory.

Example

As our static directory is .vuepress/styles, we can consider adding an alias @styles for it.

.vuepress/config.ts

export default defineUserConfig({
  ...
  alias: {
    "@styles": path.resolve(__dirname, "./styles")
  },
  ...
});

3. Create & Reference the Stylesheet

Create a stylesheet file under the static directory and reference it in your client.ts configuration file by importing it.

Example

Let's assume the file name is index.scss.

4. Add the Font File

Copy the font file to somewhere under the static directory.

Example

Let's assume the font file is located at .vuepress/styles/fonts/font.otf.

For better maintainability, you can create a stylesheet to define the font face separately.

Example

Let's assume the font face stylesheet is located at .vuepress/styles/fonts/font.scss.

Review

Current File Structure

.vuepress/
├── styles/
│   ├── index.scss
│   ├── fonts/
│   │   ├── font.scss
│   │   └── font.otf

Step 2: Fill the Stylesheets

1. Define the Font Face

In the font face stylesheet, define the font face using the @font-face rule.

注意

Make sure to use a path in url that is relative to the static directory from the alias instead of the stylesheet's directory in order to load the static asset correctly.

提示

You can refer to the official documentation (from Vite) for more information about how to handle static assets.

警告

Adding a format parameter to the src attribute literally breaks the font embedding for no reason, unless the file format is otf and the parameter is format("opentype").

Example

.vuepress/styles/fonts/font.scss

@font-face {
  font-family: "My Font";
  src: url("@styles/fonts/font.otf");
  font-weight: normal;
  font-style: normal;
}

2. Import into the Stylesheet

In the main stylesheet, import the font face stylesheet and apply the font to the desired elements.

Example

.vuepress/styles/index.scss

@import "./fonts/font.scss";

body {
  font-family: "My Font";
}

Review

Current File Structure

.vuepress/
├── styles/
│   ├── index.scss
│   ├── fonts/
│   │   ├── font.scss
│   │   └── font.otf

index.scss

@import "./fonts/font.scss";

body {
  font-family: "My Font";
}

font.scss

@font-face {
  font-family: "My Font";
  src: url("@styles/fonts/font.otf");
  font-weight: normal;
  font-style: normal;
}

Result

This site embeds SFMono Nerd Font Ligaturized as the default monospace font. You can preview it here:

<!-- @use: @src/snippets/firacode_examples/snippet.ex -->

Related: FiraCode Examples