baker example page template
1.0.0
ベイカー ビルド ツールを使用してページを作成して公開する方法のデモンストレーション。
Los Angeles Times は、latimes.com/projects で公開される静的ページを作成するために Baker を使用しています。 Times システムは、これとよく似たリポジトリのプライベート バージョンに依存しています。この簡略化された例では、ステージング バージョンと本番バージョンを Amazon S3 のパブリック バケットに公開します。
ローカル テスト サーバーのライブ更新
Nunjuck を使用した HTML テンプレート
Sass を使用した拡張 CSS
Rollup および Babel を使用した JavaScript バンドル
quaff を使用したデータのインポート
構造化入力に基づいた動的なページ生成
GitHub Action を介した各pushイベントでの各ブランチのステージング環境への自動デプロイメント
GitHub Action を介したreleaseイベントごとに実稼働環境へのプッシュ ボタン デプロイメント
datadesk/notify-slack-on-build Github Action を介して各デプロイメントのステータスを中継する Slack メッセージ
Node.js バージョン 12、14、または 16。ただし、少なくとも 12.20、14.14、または 16.0。
ノードパッケージマネージャー
git
少し設定するだけで、このテンプレートを使用してページを簡単に公開できます。少しカスタマイズすることで、好みの見た目に変えることができます。このガイドでは基本を紹介します。
新しいページの作成
リポジトリの探索
アセットへのアクセス
データへのアクセス
動的ページ
導入
グローバル変数
ベイカー.config.js
最初のステップは、GitHub の「このテンプレートを使用」ボタンをクリックして、自分用のリポジトリのコピーを作成することです。
プロジェクトのスラッグを提供するように求められます。それが完了すると、新しいリポジトリがhttps://github.com/your-username/your-slugで利用可能になります。
次に、コードを操作するために、コンピュータにクローンを作成する必要があります。
ターミナルを開き、コード フォルダーに移動します。プロジェクトのクローンをフォルダーに作成します。これにより、プロジェクトがコンピュータにコピーされます。
git clone https://github.com/your-username/your-slug
このコマンドが機能しない場合は、コンピューターのセットアップが異なっており、SSH を使用してリポジトリにクローンを作成する必要があることが原因である可能性があります。ターミナルでこれを実行してみてください。
git clone [email protected]:your-username/your-slug.git
リポジトリのダウンロードが完了したら、slug に移動し、Node.js の依存関係をインストールします。
npmインストール
依存関係がインストールされたら、プロジェクトをプレビューする準備が整います。以下を実行してテストサーバーを起動します。
npm 開始
次に、ブラウザでlocalhost:3000に移動します。カスタマイズできる定型ページが表示されるはずです。
別の方法は、ロイターのグラフィック部門が開発したコマンドライン スキャフォールディング ツールである bluprint を使用して新しいページを作成することです。
ブループリント追加 https://github.com/datadesk/baker-example-page-template mkdir 私の新しいページcd 私の新しいページ ブループリント スタート ベイカーの例のページ
ページ テンプレートから新しいプロジェクトを複製するときに見つかる標準のファイルとフォルダーを次に示します。一部のファイルの操作には他のファイルよりも多くの時間を費やすことになりますが、それらがすべて何をするのかの大まかな感覚を理解しておくことは良いことです。
データ フォルダーには、プロジェクトに関連するデータが含まれています。このフォルダーは、プロジェクトが存在する URL など、すべてのプロジェクトに関する必要な情報を保存するために使用します。 .aml 、 .csv 、 .jsonなど、他のさまざまなデータ型をここに保存することもできます。
meta.amlファイルには、見出し、署名欄、スラッグ、発行日、その他のフィールドなど、ページに関する重要な情報が含まれています。これを入力すると、ページが正しく表示され、検索エンジンによってインデックスに登録されるようになります。すべての属性の完全なリストは、参考資料にあります。これを拡張して、必要なだけのオプションを含めることができます。
このフォルダーには、サイトの基本テンプレートと再利用可能なコード スニペットが保存されます。始めたばかりの場合、ここで何も変更することはほとんどありません。より高度な使用例では、複数のページにわたって再利用されるコードを保存できます。
base.htmlBase.html ファイルには、作成するすべてのページにある基本的な HTML がすべて含まれています。ここでの例は、設計上初歩的なものです。実際の実装では、さらに多くの機能を含める必要があるでしょう。
ワークスペースは、Web 上で公開する必要のないプロジェクトに関連するものをすべて配置する場所です。 AI ファイル、コード、文章など。それはあなた次第です。
これは、メディアや、画像、ビデオ、オーディオ、フォントなどのその他の資産を保存するために使用されます。これらは、 staticテンプレート タグを介してページに取り込むことができます。
JavaScript ファイルはこのフォルダーに保存されます。 JavaScript のメイン ファイルはapp.jsと呼ばれ、コードを直接記述することができます。 npm経由でインストールされたパッケージは、他の Node.js スクリプトと同様にインポートして実行できます。このフォルダーに JavaScript コードを記述する他のファイルを作成できますが、ファイルがapp.jsから起動されていることを確認する必要があります。
私たちのスタイルシートは、開発者が CSS をより詳細に制御できる強力なスタイルシート言語である SASS で書かれています。 SASS に慣れていない場合は、スタイルシートにプレーンな CSS を記述することができます。
スタイル フォルダーはスタイルシート ( app.scss ) で構成されており、ここですべてのカスタム スタイルをプロジェクトに追加できます。ただし、追加のスタイルシートを作成してapp.scssにインポートしたい場合もあります。このサンプル プロジェクトには、単純なサイトをシミュレートするために必要な最低限のものだけが含まれています。実際の実装では、さらに多くのことから始めたいと思うでしょう。
baker.config.jsファイルには、Baker がプロジェクトの提供とビルドに使用するオプションを配置します。詳細については、このファイルの他の場所で詳しく説明されています。 domain設定を除き、このファイルを変更する必要があるのは上級ユーザーのみです。
ページのデフォルトのテンプレート。ここでページをレイアウトします。 Nujucks テンプレート システムを使用して HTML を作成します。
これらのファイルは、プロジェクトで使用されるノードの依存関係を追跡します。 npm install実行すると、追加したライブラリがここで自動的に追跡されます。
これは、GitHub がプロジェクトやコードと対話するために使用するファイルを保存するための特別なディレクトリです。 .github/workflowsディレクトリには、開発デプロイメントを処理する GitHub アクションが含まれています。ここでは何も編集する必要はありません。
アセット ディレクトリ内のファイル ストアは、展開プロセスの一部として最適化され、ハッシュ化されます。画像やその他の静的ファイルへの参照を確実にするには、 {% static %}タグを使用する必要があります。これにより、ファイルが公開されるときに大量にキャッシュされ、画像へのリンクがすべての環境で機能することが保証されます。すべての写真とビデオに使用したくなるでしょう。
<図>
<img src="{% static 'assets/images/baker.jpg' %}" alt="Baker ロゴ" width=200>
</図>_dataフォルダーに保存されている構造化データ ファイルには、テンプレートタグまたは JavaScript を介してアクセスできます。このデモには、何が可能かを示すためにexample.jsonというファイルが含まれています。 CSV、YAML、AML などの他のファイル形式もサポートされています。
_dataフォルダー内のファイルは、テンプレート内でその名前によって使用できます。したがって、 _data/example.jsonを使用すると、次のように書くことができます。
{% 例の obj の場合 %}
{{ obj.year }}: {{ obj.wheat }}{% endfor %}Baker でプロジェクトを構築する人にとって共通のニーズは、JavaScript ファイル内の生データにアクセスすることです。多くの場合、このデータは d3 または Svelte を使用して記述されたコードに渡され、ページ上にグラフィックを描画したり HTML テーブルを作成したりします。
アクセスしているデータが、有効なままであると信頼できる URL ですでに利用可能である場合、これは簡単です。しかし、そうではなく、自分で用意したデータだった場合はどうなるでしょうか?
_data フォルダー内のレコードにアクセスすることができます。唯一の注意点は、このファイルを使用可能な状態に変換する作業はユーザーの責任であるということです。これに適したライブラリはd3-fetchです。
Baker が理解できる方法でこのファイルへの URL を構築するには、次の形式を使用します。
import { json } from 'd3-fetch';// 最初のパラメータはファイルへのパスでなければなりません// 2 番目のパラメータは *必ず* “import.meta.url” const url = new URL('../_data /example.json', import.meta.url);// inconst data = await json(url); と呼びます。もう 1 つの方法は、データをscriptタグとしてテンプレートに出力することです。 jsonScriptフィルターは、渡された変数を受け取り、その変数に対してJSON.stringifyを実行し、パラメーターとして渡した ID セットを使用して JSON を<script>タグ内の HTML に出力します。
{{ example|jsonScript('example-data') }}これが完了すると、JavaScript の ID によってページに保存されている JSON を取得できるようになります。
//const dataElement = document.getElementById('example-data') で渡したものと同じ ID を使用して作成された要素 jsonScript を取得します;// その要素の内容を JSON に変換します// 「data」で行う必要があることを行います!const data = JSON.parse(dataElement.textContent); URL 方式が推奨されていますが、余分なネットワーク要求を回避したい場合には、この方式の方が優先される場合もあります。また、 .csvデータを JSON に変換するための特別なライブラリが必要ないという追加の利点もあります。
構造化データ ソースをbaker.config.jsファイルのcreatePagesオプションにフィードすることで、静的ページを無制限に生成できます。たとえば、このスニペットは、 example.jsonファイル内のすべてのレコードのページを生成します。
デフォルトをエクスポート {
// ... 要点を明確にするために、このオプションより上の他のすべてのオプションは除外されています
createPages: createPages(createPage, data) {// _data フォルダーからデータを取得しますconst pageList = data.example;// records をループしますfor (const d of pageList) { // 各オブジェクトに使用される基本テンプレートを設定します。これは _layouts フォルダーにあります。 const template = 'year-detail.html'; // ページの URL を設定します const url = `${d.year}`; // テンプレートのコンテキストに渡される変数を設定します const context = { obj: d }; // 提供された関数を使用してページをレンダリングします createPage(template, url, context);}
},};これを使用すると、単一のテンプレートで/baker-example-page-template/1775/や/baker-example-page-template/1780/]のような URL を作成できます。
このリポジトリによって作成されたページをデプロイする前に、Amazon AWS アカウントを構成し、一連の認証情報を GitHub アカウントに追加する必要があります。
まず、Amazon の S3 ストレージ サービスに 2 つのバケットを作成する必要があります。 1 つはステージング サイト用です。もう 1 つは実稼働サイト用です。この単純な例では、それぞれがパブリック アクセスを許可し、静的 Web サイトを提供するように構成されている必要があります。ロサンゼルス・タイムズで私たちが実行しているような、より洗練された配置では、バケットを登録済みのドメイン名にリンクし、認証スキームによってステージング・サイトを一般公開から保護することができます。
これらのバケットの名前は、サイトをデプロイするアクションからアクセスできる GitHub の「シークレット」として保存する必要があります。アカウントまたは組織の設定パネルにアクセスする必要があります。まずはこれら 2 つのシークレットを追加します。
| 名前 | 価値 |
|---|---|
BAKER_AWS_S3_STAGING_BUCKET | ステージング バケットの名前 |
BAKER_AWS_S3_STAGING_REGION | ステージング バケットが作成された S3 リージョン |
BAKER_AWS_S3_PRODUCTION_BUCKET | 本番バケットの名前 |
BAKER_AWS_S3_PRODUCTION_REGION | 本番バケットが作成された S3 リージョン |
次に、パブリック ファイルを 2 つのバケットにアップロードできるキー ペアを AWS から持っていることを確認する必要があります。値はシークレットにも追加する必要があります。
| 名前 | 価値 |
|---|---|
BAKER_AWS_ACCESS_KEY_ID | AWS アクセスキー |
BAKER_AWS_SECRET_ACCESS_KEY | AWS の秘密キー |
このリポジトリに含まれる GitHub アクションは、ブランチごとにステージング バージョンを自動的に公開します。たとえば、デフォルトのmainブランチにプッシュされたコードはhttps://your-staging-bucket-url/your-repo/main/に表示されます。
bugfixという新しい git ブランチを作成してコードをプッシュすると、すぐにhttps://your-staging-bucket-url/your-repo/bugfix/に新しいステージング バージョンが表示されます。
ページをライブで送信する前に、URL の最終スラッグを決定する必要があります。これにより、ページが公開されるバケット内のサブディレクトリが設定されます。この機能により、The Times は同じバケット内で多数のページを公開し、各ページを異なるリポジトリで管理できるようになります。
ステップ 1 は、URL のスラッグを_data/meta.aml構成ファイルに入力することです。
スラグ: あなたのページのスラグ
ナメクジがまだ取られていないことを確認することは決して悪い考えではありません。これを行うには、 https://your-production-bucket-url/your-slug/にアクセスし、ページが見つからないエラーが返されることを確認します。
バケットのルートでページを公開する場合は、スラッグを null のままにすることができます。
ナメクジ:
次に、変更を構成ファイルにコミットし、それが GitHub のメイン ブランチにプッシュされていることを確認します。
git add _data/meta.aml git commit -m “ページスラッグを設定” git プッシュ オリジン メイン
GitHub 上のリポジトリのページのリリース セクションにアクセスしてください。リポジトリのホームページで見つけることができます。
新しいリリースの下書きを作成します。
そこで新しいタグ番号を作成します。良いアプローチは、セマンティック バージョニング標準に準拠した xxx 形式の番号から始めることです。 1.0.0 は良いスタートです。
最後に、下部にある大きな緑色のボタンを押して、リリースを送信します。
数分待つと、ページがhttps://your-production-bucket-url/your-slug/に表示されます。
ベイカー テスト サーバーは、次のオプションを使用して開始すると、より詳細なログを記録できます。
DEBUG=1 npm 開始
ログをベイカー実行に制限するには:
DEBUG=baker:* npm 開始
ビルドが失敗した場合は、ターミナルを使用してローカルに静的サイトを作成してみてください。ページ構築にエラーがある場合は、端末にエラーが出力されます。
npm ビルドを実行する
Baker には、作成するすべてのページで同じグローバル変数のセットと、作成中の現在のページに基づいて設定されるページ固有の変数の別のセットが付属しています。これらの変数を使用すると、条件付きでコンテンツをページに追加したり、現在のページに基づいて無関係なデータを除外したりできます。
NODE_ENV NODE_ENV変数は、常に 2 つの値developmentまたはproductionのいずれかになります。これは、ページ上で実行されているビルドの種類に対応します。
npm start実行すると、 developmentモードになります。 npm run build実行すると、 productionモードになります。
これは、 developmentモードの場合にのみページに内容を追加する場合に最も役立ちます。
{% if NODE_ENV == '開発' %}<p>これは実際のサイトでは決して見られません!</p>{% endif %}DOMAIN DOMAIN変数は、常にbaker.config.jsで渡されたdomainオプションと同じになります。渡されなかった場合は空の文字列になります。
PATH_PREFIX PATH_PREFIX変数は、常にbaker.config.jsで渡されたpathPrefixオプションと同じになります。渡されなかった場合は単一のスラッシュ ( / ) になります。
page.url現在のページへのプロジェクト相対 URL。 pathPrefix baker.config.jsファイルで提供されている場合、これが含まれます。つまり、これは実行されているプロジェクトのパス設定を考慮し、プロジェクト内の正しいページを指します。
page.absoluteUrl現在のページへの絶対 URL。これにより、 domain 、 pathPrefix 、および現在のパスが完全な URL に結合されます。これは現在、正規 URL とソーシャル<meta>タグのすべての URL を出力するために使用されます。
<link rel="canonical" href="{{ page.absoluteUrl }}">page.inputUrlこれは、現在のプロジェクトのディレクトリを基準とした、このページの作成に使用された元のテンプレートへのパスです。 HTML ファイルがpage-two/index.htmlにある場合、 page.inputUrl page-two/index.htmlになります。
page.outputUrlこれは、このページを作成するために出力された HTML ファイルへの、 _distフォルダーを基準とした相対パスです。 HTML ファイルがpage-two.htmlにある場合、 page.outputUrl page-two/index.htmlになります。
私たちが取り組んでいるすべての Baker プロジェクトには、ルート ディレクトリにbaker.config.jsファイルが含まれています。このファイルは、Baker がプロジェクトを正しくビルドできるように情報を Baker に渡す役割を果たします。
デフォルトをエクスポート {
// アセットが置かれているディレクトリ
資産: '資産',
//createPages
createPages: 未定義、
// データディレクトリ
データ: '_data'、
// パスの構築に使用されるオプションのカスタム ドメイン
ドメイン: 未定義、
// 各 JavaScript エントリポイントのパスまたはパスのグロブ
エントリポイント: 'scripts/app.js',
// 入力ディレクトリ全体、通常は現在のフォルダー
入力: process.cwd()、
// テンプレートのレイアウト、マクロ、インクルードが配置される場所
レイアウト: '_layouts',
// グローバル変数のキーと値を含むオブジェクト
// すべての Nunjucks テンプレートに渡されます
nunjucks変数: 未定義、
// カスタムを追加するためのキー（名前）+値（関数）のオブジェクト
// Nunjuck にフィルターします
nunjucksフィルター: 未定義、
// カスタムを追加するためのキー（名前）+値（関数）のオブジェクト
// Nunjucks へのタグ
nunjucksタグ: 未定義,
// コンパイルしたファイルの出力先
出力: '_dist',
// 解決されたすべてのパスの先頭に追加する接頭辞。その方法
// ナメクジは動作します
パスプレフィックス: '/'、
// すべてのアセットを入れるためのオプションのディレクトリ。めったに使用されません
staticRoot: '',};デフォルト: ”assets”
これにより、Baker にどのフォルダーをアセット ディレクトリとして扱うかを指示します。おそらくこれを変更する必要はありません。
デフォルト: undefined
createPagesは、プロジェクト内のデータとテンプレートを使用してページを動的に作成できるようにするオプションのパラメーターです。
デフォルトをエクスポート {
// …
// createPage - テンプレート、出力名、データ コンテキストを渡します
// data - `_data` フォルダーに準備されたデータ
createPages(createPage, data) {for (const title of data.titles) { createPage('template.html', `${title}.html`, {context: { title }, });}
},};デフォルト: ”_data”
dataオプションは、Baker にどのフォルダーをデータ ソースとして扱うかを指示します。おそらくこれを変更する必要はありません。
デフォルト: undefined
domainオプションは、Baker に絶対 URL を構築するときに何を使用するかを指示します。 bakery-templateこれをhttps://www.latimes.comにプリセットします。
デフォルト: ”scripts/app.js”
entrypointsオプションは、Baker にどの JavaScript ファイルをスクリプト バンドルの開始点として扱うかを指示します。これはファイルまたはファイル グロブへのパスにすることができ、複数のバンドルを同時に作成できるようになります。
デフォルト: process.cwd()
inputオプションは、プロジェクト全体のメイン ディレクトリとしてどのフォルダーを扱うかを Baker に指示します。デフォルトでは、これはbaker.config.jsファイルが存在するフォルダーです。おそらくこれを設定する必要はありません。
デフォルト: ”_layouts”
layoutsオプションは、Baker にテンプレート、インクルード、マクロの場所を伝えます。デフォルトでは、これは_layoutsフォルダーです。おそらくこれを設定する必要はありません。
デフォルト: undefined
nunjucksFilters使用して、独自のカスタム フィルターを渡すことができます。オブジェクト内の各キーはフィルターの名前であり、関数の値はフィルターを使用するときに呼び出される値です。
デフォルトをエクスポート {
// ...
// Nunjucks に追加するフィルターのオブジェクトを渡します
nunjucksFilters: {square(n) { n = +n; n * n を返します;}
},} {{ 値|平方 }}デフォルト: undefined
nunjucksTags使用して、独自のカスタム タグを渡すことができます。これらは、テキストまたは HTML のブロックを簡単に出力できるという点でフィルターとは異なります。
デフォルトをエクスポート {
// ...
// Nunjucks に追加するフィルターのオブジェクトを渡します
nunjucksTags: {doubler(n) { return `<p>${n} を 2 倍にしたものは ${n * 2}</p>`;}
},}; {% ダブラー値 %}デフォルト: ”_dist”
outputオプションは、 npm run buildの実行時にファイルを配置する場所を Baker に指示します。デフォルトでは、これは_distフォルダーです。おそらくこれを設定する必要はありません。
デフォルト： ”/”
pathPrefix構築する URL にどのパス プレフィックスを追加するかを Baker に指示します。 domainも渡される場合、絶対 URL を構築するときにpathPrefixと結合されます。通常、これを手動で設定することはありません。これは、プロジェクト スラグを含む URL を構築するためにデプロイ中に使用されます。
デフォルト： ””
staticRootオプションは、Baker にすべてのアセットを追加のディレクトリに配置するように指示します。これは、ネストせずにすべてのページに一意のスラッグを含める必要があるプロジェクトに役立ち、すべてのページで静的アセットを共有できるようになります。ただし、これは特殊なケースであり、展開用のカスタム設定が必要です。正当な理由なくこれを使用しないでください。
