Hugo Preview for VS Code

Hugo Preview is a Hugo-specific preview extension for VS Code, designed for users who create content with Hugo.

It uses your Hugo configuration, theme, and build output as-is, allowing you to preview Markdown files in a way that closely matches the actual site rendering.

Overview

Unlike generic Markdown preview features, this extension is built on the following assumptions:

Hugo configuration files (hugo.toml / config.toml / config.yaml)
The currently selected Hugo theme
Output generated by Hugo itself

For this reason, the extension is only available inside Hugo projects.

Note: In this README, a "Hugo project" refers to the root directory of a site created with hugo new site. Specifically, this is the directory that contains Hugo configuration files and the content/ directory.

Basic Usage

Open a Hugo project in VS Code
Open a Markdown file under the content/ directory
Click the "H" button displayed in the top-right corner of the editor to start the preview

Intended Users

This extension is intended for users who:

Create articles, documentation, or other content using Hugo
Want to edit content while checking the final appearance with their selected theme
Prefer to complete their workflow entirely within VS Code, without switching to a browser

Main Features

Hugo-Specific Preview

This extension provides preview functionality with the selected Hugo theme applied.

Open a Markdown file inside a Hugo project
Click the "H" button shown in the top-right corner of the editor
The preview is rendered on the right side using Hugo

Once the preview is started, the preview panel automatically updates every time the .md file is saved. This allows you to repeat editing and previewing entirely within VS Code, without interacting with a browser.

Preview-Only Style Customization

The preview shown by this extension is the actual site output generated by hugo server, rendered directly inside VS Code.

Because of this, modifying the CSS in your Hugo theme will immediately affect the appearance of the preview.

The preview behaves the same way as a normal Hugo site rendered by hugo server.

Applying styles only during preview

When the preview is rendered, the generated HTML automatically includes the following attribute:

<html hugo-preview="true">

This attribute allows you to define CSS rules that apply only during preview by targeting it in your theme’s stylesheets.

html[hugo-preview="true"] {
  background-color: #1e1e1e;
}

html[hugo-preview="true"] .content {
  max-width: 900px;
}

html[hugo-preview="true"] .l-sidebar {
  display: none;
}

Using this approach, you can adjust the layout and readability of the preview inside VS Code without affecting the production site.

Automatic Hugo Installation and Update Management

The extension automatically manages the Hugo binary internally.

If Hugo is not installed, it will be installed automatically
If a newer version is available, an update dialog is shown
Hugo is updated when the user approves the update

Pinning the Hugo Version

You can fix the Hugo version by enabling the following setting:

{
  "hugoPreview.hugoVersion": "0.152.2"
}

When this setting is enabled, automatic updates are disabled. This is useful when you want to standardize the Hugo version across a team.

Testing with the Hugo Server

If you want to review the entire site, you can start a Hugo server for testing purposes using the following steps:

Click the button in the status bar that displays the current Hugo version
Select one of the following options from the menu:
- Start Hugo server: Start the Hugo server
- Stop Hugo server: Stop the Hugo server
- Open site (http://localhost:1313): Open the site in a browser

Use this feature to perform final checks before release.

Notes

This extension is Hugo-only
It does not work outside of Hugo projects
Hugo is managed internally by the extension
Depending on your Hugo configuration, startup may take some time

License

This extension is licensed under the MIT License.

日本語ドキュメント (Japanese)

Hugo Previewは、Hugoでコンテンツを作成するユーザ向けに設計された、VS Code用のHugo専用プレビュー拡張機能です。

Hugoの設定・テーマ・ビルド結果をそのまま利用し、実際のサイト表示に近い状態でMarkdownをプレビューできます。

概要

一般的なMarkdownプレビューとは異なり、以下を前提として動作します。

Hugoの設定ファイル(hugo.toml / config.toml / config.yaml など)
選択されているテーマ
Hugoによるビルド結果

そのため、Hugoプロジェクト内でのみ利用可能です。

※本READMEにおける「Hugoプロジェクト」とは、 hugo new site で作成されたサイトのルートディレクトリを指します。具体的には、Hugoの設定ファイルやcontent/ディレクトリが配置されている場所です。

基本操作

HugoプロジェクトをVS Codeで開く
Hugoプロジェクトのcontent/配下のMarkdownファイルを開く
エディタ右上に表示される「H」ボタンを押下してプレビューを実施する

想定ユーザ

Hugo を使って記事・ドキュメントなどのコンテンツを作成している
選択しているテーマでの最終的な表示を確認しながら編集したい
ブラウザを開かず、VS Code 上で作業を完結させたい

主な機能

Hugo専用プレビュー

選択しているテーマを適用した状態でプレビュー表示する機能を提供します。

Hugoプロジェクト内でMarkdownファイルを開きます
エディタ右上に"[H]"ボタンが表示されるので、クリックします
Hugoを経由して、右側にプレビュー画面を表示します

プレビュー起動後は、 *.md ファイルを保存するたびにプレビュー画面が自動で更新されます。これにより、ブラウザを操作することなく、VS Code上で編集と確認を繰り返すことができます。

プレビュー専用スタイルのカスタマイズ

本拡張機能のプレビュー画面は、 hugo server によって起動された実際のサイト表示 を、そのまま VS Code上に表示しています。

そのため、Hugoテーマ側のCSSを修正することで、プレビュー画面の表示もそのまま変わります。

プレビュー時のみCSSを切り替えたい場合

プレビュー表示時に生成されるHTMLは、次の属性が自動的に付与されます。

<html hugo-preview="true">

これを利用することで、 プレビュー時のみ適用されるCSS をテーマ側で定義できます。

html[hugo-preview="true"] {
  background-color: #1e1e1e;
}

html[hugo-preview="true"] .content {
  max-width: 900px;
}

html[hugo-preview="true"] .l-sidebar {
  display: none;
}

この方法を使えば、本番サイトのデザインは変更せずに、VS Code上のプレビュー画面だけを見やすく調整するといった使い分けが可能です。

Hugo本体の自動インストール・更新管理

Hugo本体を拡張機能内で自動管理します。

Hugoが未インストールの場合は自動でインストールします
新しいバージョンが存在する場合は、更新ダイアログを表示します
更新を承認することで、Hugoを更新します

Hugoのバージョンを固定にする

以下の設定を有効にすることで、Hugoのバージョンを固定化できます。

{
  "hugoPreview.hugoVersion": "0.152.2"
}

上記を有効にすると、自動更新は行われません。チーム内でバージョンを統一したい場合などにご使用ください。

Hugoサーバのテスト起動

Hugoのコンテンツを、全体通して確認したい場合は、次の手順でテストを実施できます。

ステータスバーに、現在のHugoのバージョンを表記したボタンが配置されるので、そちらをクリックします
上部に以下の選択が出ます
- Start Hugo server: Hugo サーバを起動します
- Stop Hugo server: Hugo サーバを停止します
- Open site (http://localhost:1313): ブラウザでHugoを開きます

リリース前の確認にご利用ください。

注意事項

本拡張機能はHugo専用です
Hugoプロジェクト外では本拡張機能は動作しません
Hugoの設定内容によっては起動に時間がかかる場合がございます

ライセンス

MIT

Hugo Preview

Suguru Ochiai