1. Node.jsを用意
WindowsまたはmacOSにNode.js 22または24とnpmをインストールし、ターミナルを開きます。PowerShellでも同じコマンドを使えます。
node --version
npm --versionドキュメント
CLIで動かし、APIで組み込む。
技術書で読んだ構造を、自分の環境で確かめるための入口です。まずGet StartedでCLIからページを生成し、次にCore・site-generation・HTMLを使う例と、文法・評価の契約へ進んでください。
対応環境: Node.js 22/24。literate APIは実験的なNode.js APIです。
Get Started：npmでページを作る
Windows・macOS向けの実験版です。Node.js 22/24とnpmを使います。
2. CLIを導入
次のコマンドで実験版をversion固定してインストールします。PowerShellのスクリプト実行制限で失敗する場合はnpm.cmdとmatra.cmdを使います。コマンドが見つからない場合はnpmのprefixとPATHを確認してください。
npm install --global @matra/[email protected]
matra --version3. ページを作成
helloは存在しないディレクトリを指定します。dist/index.htmlを開くか、表示されたlocalhostのURLでプレビューします。更新後のブラウザ再読み込みは手動、終了はCtrl+Cです。
matra init hello
cd hello
matra build
matra dev実験版です。buildは文書内のJavaScriptを実行するため、信頼する文書だけを使ってください。OS sandboxや実行時間の保証はありません。キャンペーンの案内・サポート期間は別途お知らせします。
最初の一歩
CLIとCore・HTMLを使う
固定versionで導入し、READMEと公開API契約を参照します。
左は入力Markdown文書の全体です。matra.entryがmain.matraを選び、matra.valuesのJavaScript式をcontentとして渡します。@matra/coreが文書を評価し、@matra/site-generationがページ・共通layout・データからサイトを生成します。CLIは新規プロジェクトの作成とbuild/previewに使います。下のコードは各packageの利用例です。
---
matra:
entry: main.matra
values:
- content.js.part
---
# Compose a page with Matra packages
```main.matra
html(lang="en") {
head {
title { content.pageTitle(content.title) }
}
body {
header {
p { "MATRA / PACKAGE EXAMPLES" }
h1 { content.title }
p { content.description }
}
main {
...for (item in content.packages) {
section(id=item.id) {
h2 { item.name }
p { item.description }
pre { code { item.example } }
}
}
}
footer {
p { "These package workflows are experimental; check each package's release notes." }
}
}
}
```
```content.js.part
({
title: "Compose a page with Matra packages",
description: "Use the CLI to start a project, Core to evaluate Matra documents, and site-generation to build a site.",
pageTitle: title => `${title} | Matra`,
packages: [
{
id: "cli",
name: "@matra/cli",
description: "Create and preview a starter project with the experimental CLI.",
example: "npm install --global @matra/[email protected]\nmatra init hello\ncd hello && matra dev"
},
{
id: "core",
name: "@matra/core",
description: "Build and run a literate Matra document in Node.js.",
example: 'const value = await runLiterate(await buildLiterate(source))'
},
{
id: "site-generation",
name: "@matra/site-generation",
description: "Generate pages from Matra templates, page data, and a shared layout.",
example: 'await generateSite({ root, output: "dist", pages })'
}
]
})
```<html lang="en">
<head>
<title>Compose a page with Matra packages | Matra</title>
</head>
<body>
<header>
<p>MATRA / PACKAGE EXAMPLES</p>
<h1>Compose a page with Matra packages</h1>
<p>Use the CLI to start a project, Core to evaluate Matra documents, and site-generation to build a site.</p>
</header>
<main>
<section id="cli">
<h2>@matra/cli</h2>
<p>Create and preview a starter project with the experimental CLI.</p>
<pre><code>npm install --global @matra/[email protected]
matra init hello
cd hello && matra dev</code></pre>
</section>
<section id="core">
<h2>@matra/core</h2>
<p>Build and run a literate Matra document in Node.js.</p>
<pre><code>const value = await runLiterate(await buildLiterate(source))</code></pre>
</section>
<section id="site-generation">
<h2>@matra/site-generation</h2>
<p>Generate pages from Matra templates, page data, and a shared layout.</p>
<pre><code>await generateSite({ root, output: "dist", pages })</code></pre>
</section>
</main>
<footer>
<p>These package workflows are experimental; check each package's release notes.</p>
</footer>
</body>
</html>読む・試す
目的に合わせて進む。
01
作例
Matra、JavaScript、HTML rendererをつなぐ最小の実行例です。
作例を見る →02
v0.3仕様
文書data model、文法、公開literate APIの一次資料です。
仕様一覧 →03
パッケージ
Core・CLI・HTML・site-generationの役割と、暫定APIを含む利用例を案内します。
package一覧 →注意
安定版と実験版を区別してください。
literate APIの互換性、OS sandbox、timeout保証はありません。公開API契約にある対応範囲を先に確認してください。