maqz README

使い方

導入

必要なソフトウェアをインストールし、GitHubからクローンして環境を整えます。

1. 必要なソフトウェアのインストール

以下のソフトウェアは必須です。

node.js
Git

また、エディターも必要です。エディターにはVisual Studio Codeを推奨します。

環境によって追加のライブラリも必要です。

Mac OS

Command Line Tools
libjpeg, libpng

brew install libjpeg libpng

Ubuntu

libjpeg, libpng

apt-get install -y libjpeg libpng

2. yarnとgitで導入

新しいフォルダーを作成し、以下の操作をしてください。

git init
git remote add upstream https://github.com/tamaina/tamaina.github.io.git
git fetch upstream
git checkout src
npx yarn install
git worktree add docs master; git worktree add pages pages

2. ビルド

普通のビルド

npx gulp

一般的なビルドです。

ページのみビルド

npx gulp pages

ページのみを変更した場合はnpx gulp pagesをします。distの一掃やスタイルやスクリプトの生成・更新をしないので、速くビルドできます。

ローカルで確認

ローカルサーバーを立てて内容を事前に確認できます。.config/debug-override.ymlで設定できます。

npx gulp local-server を実行し、緑色で表示されたlocalhostを含むアドレスにアクセスします。

公開する

GitHub Pagesを使って自分のサイトとして公開してみましょう。

GitHubでリポジトリを作成します。
.config/default.ymlを編集し、自分のサイトの設定に合わせます。
package.jsonも編集します。
git remote add origin (git url).git
独自ドメインにする場合、theme/staticにCNAMEという名前のファイル（拡張子なし）を作成し、中身は自分が公開したいドメインを書きます（例: maqz.example.com）
ビルド npx gulp
.\pushAll.bat "コミットコメント"（コミットコメントにはわかりやすいものに）
実際にアクセスして確認してみましょう。

画像の登録（圧縮）

maqzでは、画像は原則縮小・圧縮することになっています。

filesフォルダー以下に置いたファイルには圧縮がかかります。
theme/static/に置いたファイルは圧縮されません。

設定は./config/images.ymlで行います。

画像を追加

gulp image -i

ラスター画像（png, jpegなどのビットマップ画像）は以下のようになります（設定で変更可）。

/files/images/imports/yyyy/mm/{name}.{ext} - 横幅が1200px以下で同系式（圧縮はする）
/files/images/imports/yyyy/mm/{name}.webp - 横幅が1200px以下でwebp
/files/images/imports/yyyy/mm/{name}.720.{ext} - 横幅が720px以下で同系式（圧縮はする）
/files/images/imports/yyyy/mm/{name}.720.webp - 横幅が720pxのwebp
/files/images/imports/yyyy/mm/{name}.360.{ext} - 横幅が360px以下で同系式（圧縮はする）
/files/images/imports/yyyy/mm/{name}.360.webp - 横幅が360pxのwebp

SVGも圧縮しますが、png化などは行いません。

すべての画像を再圧縮

gulp image-prebuildFiles

files以下の画像をすべて圧縮しなおします。圧縮の設定

ページを編集する

ページを編集するには、pagesフォルダー以下にmarkdown(.md)、pug(.pug)、html(.html)を配置します。通常はこのディレクトリ構造のままファイルが公開されることでしょう。

ファイルの先頭の---で囲んだ範囲をFrontMatterといい、Yaml形式でページに関する設定を行えます。
たとえば、titleはページのタイトル、descriptionはページの短い説明、themeは使用するテンプレート（後述）を指定します。

pugファイルであれば、自身のFrontMatterはpage.attributesから参照できます。

テーマを編集する

themeフォルダーにテーマがあり、編集できます。

HTML(pug)

templatesフォルダーにはテンプレートを配置します。
この中にあるどのファイル名のpugを利用するかをFrontMatterのthemeで決定できます。
指定しなければ、または存在しなければdefault.pugで処理を行います。
ampはamp_を付加したものを利用します。
ページをhtml化したものはmainHtmlとして格納されています。

includes/_mixins.pug, includes/_script.pugはページのpugをHTMLにするときに先頭に付加されます。

.configフォルダー内の設定はsiteにまとめて格納されています。

また、scripts/builder/registerer/base.jsを編集することでデータを簡単に追加できます。

スタイル (styl, sass)

sass形式で書かれています。main.jsを読みます。

JavaScript

サイトに挿入するJavaScriptです。main.sassを読みます。ampはamp_mainを読みます。

サイトを公開する

.config/default.ymlを公開条件に合わせて編集する
ビルドする
docsフォルダーもしくはdocsブランチを公開する

Note

worktreeの追加

- （既存の{basebranch}ブランチを親として利用）git checkout -b {basebranch}; git checkout {basebranch}
- （親をもたない新規ブランチを作る）念のため新たな作業フォルダーにcloneしてgit checkout --orphan {branch}→すべてのフォルダーを消去→git push origin {branch}
git checkout master
git worktree add {path} {branch}
cd {path}
不要なファイルを消去
git push --set-upstream origin {branch}（set-upstreamを指定してあると、git pull/pushなどで明示的にリモートを指定する必要がなくなる）

worktreeについて他のコマンドを調べるにはgit worktree -hでヘルプを表示

ライセンス

CC0