jigsaw docs template

ジグソー ドキュメント スターター テンプレート

これは、プロジェクト用の美しくカスタマイズ可能なドキュメント サイトを最小限の労力で作成するためのスターター テンプレートです。いくつかの設定を変更するだけで準備は完了です。

ドキュメント テンプレートのプレビューを表示します。

インストール

Jigsaw をインストールした後、プロジェクト ディレクトリから次のコマンドを実行します。

./vendor/bin/jigsaw init docs

このスターター テンプレートには一般的なページ タイプのサンプルが含まれており、以下が事前に構成されています。

• 完全に応答性の高いナビゲーション バー
• サイドバーのナビゲーション メニュー
• Tailwind CSS、CSS の行に触れることなくデザインをカスタマイズできるユーティリティ CSS フレームワーク
• CSS から未使用のセレクターを削除する Purgecss により、CSS ファイルが小さくなります
• ハイライト.jsを使用した構文の強調表示
• sitemap.xmlファイルを自動生成するスクリプト
• Algolia DocSearch を利用した検索バーと、無料のインデックス サービスの開始方法に関する説明
• カスタム 404 ページ

---

---

新しいサイトの構成

すべての Jigsaw サイトと同様に、構成設定はconfig.phpにあります。そのファイル内の変数をプロジェクト固有の設定で更新できます。そこに新しい構成変数を追加して、サイト全体で使用することもできます。詳細については、Jigsaw のドキュメントを参照してください。

 // config.php
return [
    ' baseUrl ' => ' https://my-awesome-jigsaw-site.com/ ' ,
    ' production ' => false ,
    ' siteName ' => ' My Site ' ,
    ' siteDescription ' => ' Give your documentation a boost with Jigsaw. ' ,
    ' docsearchApiKey ' => '' ,
    ' docsearchIndexName ' => '' ,
    ' navigation ' => require_once ( ' navigation.php ' ),
];

ヒント: この構成ファイルは、「コレクション」(サイトへの寄稿者のコレクションやブログ投稿のコレクションなど) を定義する場所でもあります。詳細については、Jigsaw の公式ドキュメントを参照してください。

---

コンテンツの追加

さまざまな種類のファイルを使用してコンテンツを書き込むことができます。デフォルトでは、このスターター テンプレートは、コンテンツがsource/docsフォルダーに配置されることを想定しています。これを変更する場合は、必ずnavigation.php内の URL 参照を更新してください。

各コンテンツ ページの最初のセクションには、レンダリング方法を指定する YAML ヘッダーが含まれています。 title属性は、各ページの HTML titleと OpenGraph タグを動的に生成するために使用されます。 extends属性は、このコンテンツ ファイルがどの親 Blade レイアウトでレンダリングされるかを定義します (例: _layouts.documentation 、 source/_layouts/documentation.blade.phpでレンダリングされます)。また、 section属性は、このコンテンツが配置されることを予期する Blade の「セクション」を定義します。そこに。

---
title : Navigation
description : Building a navigation menu for your site
extends : _layouts.documentation
section : content
---

ジグソー レイアウトについて詳しくは、こちらをご覧ください。

---

アセットの追加

コンパイルが必要なアセット (JavaScript、Less、Sass ファイルなど) は、 source/_assets/ディレクトリに追加でき、 npm run devまたはnpm run prodの実行時に Laravel Mix がそれらを処理します。処理されたアセットは/source/assets/build/に保存されます (この 2 番目のassetsディレクトリにはアンダースコアがないことに注意してください)。

その後、Jigsaw がサイトを構築すると、構築されたファイルを含む/source/assets/ディレクトリ全体 (およびそこに保存することを選択した画像やフォントなどの静的アセットを含むその他のディレクトリ) が宛先のビルド フォルダーにコピーされます。 ( build_local 、ローカルマシン上)。

処理を必要としないファイル (画像やフォントなど) は、 /source/assets/に直接追加できます。

Laravel Mix を使用してジグソーでアセットをコンパイルする方法について詳しく読んでください。

---

サイトの構築

構成変数を編集し、スタイルとコンテンツをカスタマイズする方法を理解したので、サイトを構築しましょう。

 # build static files with Jigsaw
./vendor/bin/jigsaw build

# compile assets with Laravel Mix
# options: dev, prod
npm run dev