サイトの雛形を作成する

vss new <DIR> は、設定ファイル、Markdown、テンプレート、CSS を含む最小サイトを生成します。

vss new my-site
cd my-site
vss build
vss serve

build の生成物は dist/ に出力されます。 serve の既定のポートは 8080 です。 ファイルを編集すると自動で再ビルドしますが、ブラウザーのリロードは手動です。

既存のディレクトリに生成する

現在のディレクトリに生成する場合は、. を指定できます。

mkdir my-site
cd my-site
git init
vss new .

.git/ や隠しファイルなど、雛形と無関係な既存ファイルはそのまま保持します。 layouts/ や static/ など、雛形の配置に必要な既存ディレクトリは再利用します。

生成予定のファイルがすでにある場合や、必要なディレクトリの位置に通常ファイルがある場合は、雛形の生成を始める前にエラーにします。 既存ファイルを上書きするオプションはありません。 生成済みサイトでの再実行も衝突としてエラーになり、既存サイトの更新や補修は行いません。

生成先が通常ファイルの場合や、生成先までのパスや雛形の配置に使うパスにシンボリックリンクがある場合も拒否します。 無関係な既存のシンボリックリンクは変更しません。 I/O エラーや検査後の同時変更によって失敗した場合は、作成済みのディレクトリやファイルが残ることがあります。

引数やヘルプは vss new --help で確認できます。 生成するテキストファイルは、OS にかかわらず UTF-8 と LF 改行を使用します。

生成するファイル

my-site/
├── README.md
├── vss.toml
├── index.md
├── layouts/
│   ├── default.html
│   └── tags/
│       └── default.html
└── static/
    └── style.css

index.md を編集し、layouts/ に HTML テンプレート、static/ に画像や CSS を置きます。 README.md は build.ignore_files でビルド対象から除外しています。 サイトルートの .gitignore は生成も変更もしません。

生成物を Git の追跡対象から除外する

vss build と vss serve は、出力ディレクトリの直下に次の内容の .gitignore を生成します。

*

この指定は、.gitignore 自身を含む出力ディレクトリ配下のすべてを Git の追跡対象から除外します。 タグページの出力先がこの .gitignore と重なる設定はエラーになります。 出力先を削除して再生成するたびに、末尾改行付きの同じ内容で作り直します。 vss.toml の dist を変更した場合も、新しい出力先に生成するため、サイトルートの .gitignore を編集する必要はありません。

すでに Git で追跡されている生成物の追跡は解除しません。 追跡を外す場合は、出力先に合わせて次のコマンドを実行してください。

git rm -r --cached -- dist/

公開する

vss.toml の base_url に HTTP(S) の公開先 URL を設定してから、vss build を実行します。 公開するのは dist/ の中身です。 サイト内の Markdown は再帰的に探索されるため、公開したくないファイルをサイトのディレクトリに置かないでください。