---
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 })'
}
]
})
```PACKAGES
公開packageと検証範囲。
このwebsiteのページ本体はMatra templateとpage dataで構成し、@matra/coreで評価、@matra/site-generationで全routeを生成、@matra/htmlでHTML化します。@matra/cliは新規projectの作成・build・previewに使います。下の例は暫定APIを含むため、各packageのversionとrelease記録を確認してください。
Core 0.3.1-site.4 / HTML 0.3.1-site.0 / CLI 0.3.2-alpha.3 / site-generation 0.1.0-site.5。互換性・APIは暫定です。
検証対象
websiteのbuildを再現する依存
各packageの役割と、最小限の利用例を確認できます。
左は入力Markdown文書の全体です。matra.entryがmain.matraを選び、matra.valuesのJavaScript式をcontentとして渡します。@matra/coreが文書を評価し、@matra/site-generationがページ・共通layout・データからサイトを生成します。CLIは新規プロジェクトの作成とbuild/previewに使います。下のコードは各packageの利用例です。
<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/core
文法、評価、文書AST、browser API、experimental/literate APIを提供します。このサイトではliterate APIでMatra文書を評価します。
const value = await runLiterate(await buildLiterate(source))02
@matra/cli
新規projectの作成、build、ローカルpreview向けの実験版CLIです。
npm install --global @matra/[email protected]
matra init hello
cd hello && matra dev03
@matra/site-generation
Matra template・共通layout・page dataからsiteを生成します。このwebsiteの各routeもこのpackageで出力します。APIとversionは暫定です。
await generateSite({ root, output: "dist", pages })04
@matra/html
文書ASTをHTMLへ変換し、文字列・属性のescapeとbase pathに対応します。このwebsiteはsite-generationを通じて利用します。
const html = toHTML(documentAST)05
別domain package
Graphics・Math・Compute Engineは個別の検証対象です。公開状態や完成度を一括して扱いません。
優先度と範囲 →環境
literate APIはNode.js 22/24を対象とします。
同梱compilerにより、利用時のRust・checkout・追加downloadは不要です。APIは実験的で、信頼した入力のみ実行してください。