HTML Include

日本語

Expands includes written as HTML comments to assemble HTML from fragments. Works both as a VS Code extension and from the command line (npx htmlinclude).

Because the directives are HTML comments, the source files remain valid HTML and can be viewed as they are in a browser or preview.

Syntax

include:src inserts the contents of another file at that position. The path is relative to the file containing the directive. Includes inside the inserted file are expanded too.

<!--include:src="parts/header.html"-->

include:output marks the file for output and specifies the output path, relative to destDir. If empty, the path relative to srcDir is used under destDir. Files without include:output (fragments) are not output.

<!--include:output="index.html"-->
<!--include:output=""-->

Whitespace is allowed, as in <!-- include:src = "..." -->.

Example

<!-- src/index.html -->
<!DOCTYPE html>
<html>
<body>
    <!--include:src="parts/header.html"-->
    <p>Body</p>
    <!--include:output="index.html"-->
</body>
</html>

<!-- src/parts/header.html -->
<header><h1>Site name</h1></header>

Output (dist/index.html):

<!-- src/index.html -->
<!DOCTYPE html>
<html>
<body>
    <!-- src/parts/header.html -->
<header><h1>Site name</h1></header>

    <p>Body</p>
    
</body>
</html>

To tidy up the indentation, let prettier format the output with format (see below).

Configuration

Put htmlinclude.json at the root of the project. Paths are relative to htmlinclude.json.

{
  "srcDir": "src",
  "destDir": "dist",
  "format": false
}

Prettier is not bundled. Install it in the target project.

npm install --save-dev prettier

Usage

Command line

npx htmlinclude            # Output using htmlinclude.json in the current directory
npx htmlinclude -c site/htmlinclude.json
npx htmlinclude --watch    # Watch for changes and output again

The exit code is 0 when there are no problems, 1 when there are problems (such as a missing included file), and 2 when it cannot continue (such as a configuration error). Requires Node.js 20 or later. Messages are shown in Japanese when the locale is Japanese (determined by LC_ALL, LC_MESSAGES, LANG, or the OS setting), and in English otherwise.

VS Code

• The command HTML Include: Expand Includes and Output outputs every htmlinclude.json project in the workspace. If there is no htmlinclude.json, it offers to create a template.
• Set htmlinclude.runOnSave to true to output again automatically when a file in a project with htmlinclude.json is saved.
• Problems such as a missing included file or circular includes are shown in the Problems panel. The list of output files is shown in the "HTML Include" output channel.
• Completion and validation are available for htmlinclude.json.

Because it runs prettier from the workspace for formatting, it does not work in Restricted Mode (untrusted workspaces).

Problem handling

The following are reported as problems, and processing of other files continues.

• Missing included file, circular include: The directive is left as is in the output
• Output path is the same as an input file, or overlaps another file's output: That file is not output
• Prettier cannot format (e.g. HTML syntax errors): Output without formatting

Output files whose content has not changed are not written (their modification time stays the same).

日本語

HTML コメントで書いた include を展開して、HTML の断片から HTML を組み立てる。VS Code の拡張としても、コマンドライン（npx htmlinclude）でも使える。

ディレクティブは HTML コメントなので、組み立てる前のファイルも正しい HTML のままで、そのままブラウザやプレビューで見られる。

書き方

include:src は、その位置に別のファイルの内容を取り込む。パスはディレクティブを書いたファイルからの相対パス。取り込んだファイルの中の include も展開する。

<!--include:src="parts/header.html"-->

include:output は、そのファイルを出力することと、出力先を表す。パスは destDir からの相対パス。空にすると、srcDir からの相対パスをそのまま destDir の下に使う。include:output のないファイル（断片）は出力しない。

<!--include:output="index.html"-->
<!--include:output=""-->

<!-- include:src = "..." --> のように、空白を入れてもよい。

例

<!-- src/index.html -->
<!DOCTYPE html>
<html>
<body>
    <!--include:src="parts/header.html"-->
    <p>本文</p>
    <!--include:output="index.html"-->
</body>
</html>

<!-- src/parts/header.html -->
<header><h1>サイト名</h1></header>

出力（dist/index.html）:

<!-- src/index.html -->
<!DOCTYPE html>
<html>
<body>
    <!-- src/parts/header.html -->
<header><h1>サイト名</h1></header>

    <p>本文</p>
    
</body>
</html>

字下げを整えたいときは、後述の format で prettier に整形させる。

設定

プロジェクトの直下に htmlinclude.json を置く。パスは htmlinclude.json からの相対パス。

{
  "srcDir": "src",
  "destDir": "dist",
  "format": false
}

整形に使う prettier はこのツールには含まれていない。対象のプロジェクトにインストールしておく。

npm install --save-dev prettier

使い方

コマンドライン

npx htmlinclude            # カレントディレクトリの htmlinclude.json で出力する
npx htmlinclude -c site/htmlinclude.json
npx htmlinclude --watch    # 変更を監視して出力し直す

終了コードは、問題がなければ 0、問題（取り込むファイルがないなど）があれば 1、設定の誤りなどで続けられなければ 2。Node.js 20 以降で動く。メッセージは、言語の設定（LC_ALL、LC_MESSAGES、LANG、なければ OS の設定）が日本語なら日本語、それ以外は英語で表示する。

VS Code

• コマンド HTML Include: include を展開して出力 で、ワークスペースにあるすべての htmlinclude.json について出力する。htmlinclude.json がなければ、ひな形を作れる。
• 設定 htmlinclude.runOnSave を true にすると、htmlinclude.json のあるプロジェクトの中のファイルを保存したときに、自動で出力し直す。
• 取り込むファイルがない、include が循環しているといった問題は「問題」パネルに表示する。出力したファイルの一覧は出力パネルの「HTML Include」に表示する。
• htmlinclude.json の入力補完と検証ができる。

整形のためにワークスペースの prettier を実行するので、制限モード（信頼されていないワークスペース）では動かない。

問題の扱い

次のものは問題として報告し、ほかのファイルの処理は続ける。

• 取り込むファイルがない、include が循環している: ディレクティブをそのまま出力に残す
• 出力先が入力のファイルと同じ、別のファイルの出力先と重なる: そのファイルを出力しない
• prettier が整形できない（HTML の構文の誤りなど）: 整形せずに出力する

内容が変わらない出力ファイルは書き込まない（更新日時も変わらない）。

開発

npm install
npm test                     # ビルドして node:test のテストを実行する
npm run package              # .vsix を作る
npm run icon                 # images/icon.svg を images/icon.png（256×256）に書き出す（sharp-cli は npx でその都度取得）
npm run publish:marketplace  # VS Code Marketplace に公開する（事前に vsce login ExpressionInc）
npm publish                  # npm に公開する（prepublishOnly でテストを実行する）