teccon forum

Quartzのウェブサイト構築実践

7 min read

Quartz 構成設定 基本

Built-in Features

Backlinks (バックリンク) は、現在のページを参照している他のページへのリンクを表示する機能です。

設定方法:

  1. quartz.config.ts の Plugin.Component セクションで有効化します:
Plugin.Component.Backlinks({
  title: "リンク元のページ",
  showDate: true,
  dateFormat: "YYYY-MM-DD"
})

カスタマイズオプション:

  • title: バックリンクセクションのヘッダータイトル
  • showDate: 日付表示の有無（true/false）
  • dateFormat: 日付フォーマット（moment.js形式）

Tags

タグ機能は、コンテンツの分類と整理に役立ちます。

設定方法:

  1. Markdownファイルのフロントマターにタグを追加します:
---
title: 記事タイトル
tags:
  - タグ1
  - タグ2
---
  1. タグページを有効化します:
Plugin.Component.TagList()

タグ関連の高度な設定:

Plugin.Component.TagList({
  minTagCount: 2,  // 表示する最小タグ数
  maxTagCount: 50, // 表示する最大タグ数
  sortByFrequency: true  // 使用頻度でソート
})

パーマリンクは、コンテンツの永続的なURLを設定する機能です。

設定方法:

  1. フロントマターでカスタムスラッグを指定:
---
title: 記事タイトル
permalink: custom-url-slug
---
  1. quartz.config.ts でパーマリンク形式を設定:
Plugin.Route.ValidPath({
  formatPath: (path) => {
    // カスタム処理
    return path
  }
})

パーマリンク活用例:

  • ブログ記事: /blog/2025/05/article-title
  • ドキュメント: /docs/category/subcategory/topic

User customize

Change Theme

Quartzは複数のテーマを提供しています。テーマを変更するには:

  1. quartz.config.ts の Theme オブジェクトを編集:
export default defineConfig({
  theme: {
    typography: {
      fontFamily: "var(--font-body)",
      dark: "#eeeeee",
      light: "#333333",
    },
    colors: {
      lightMode: {
        light: "#fafafa",
        lightgray: "#e5e5e5",
        gray: "#b8b8b8",
        darkgray: "#4e4e4e",
        dark: "#2b2b2b",
        primary: "#576cbc",
        secondary: "#0f2d6b",
      },
      darkMode: {
        light: "#161618",
        lightgray: "#393639",
        gray: "#646464",
        darkgray: "#d4d4d4",
        dark: "#ebebec",
        primary: "#5b8aff",
        secondary: "#a1c1ff",
      },
    },
  },
})

主なカスタマイズ項目:

  • typography: フォントやテキストカラー
  • colors: 明暗モード別のカラースキーム

Styles

  • Disable selecting

テキスト選択を無効化するカスタムCSSを追加します:

custom.scss:

.no-select {
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
}
 
// 特定のセクションで選択を無効化
.copyright, .sensitive-info {
  @extend .no-select;
}
 
// 画像選択の無効化
img {
  -webkit-user-select: none;
  -moz-user-select: none;
  -ms-user-select: none;
  user-select: none;
  pointer-events: none;
}

このスタイルを適用するには:

  1. styles ディレクトリに custom.scss を作成
  2. コンテンツに対応するクラスを追加

Custom plugin

Quartzでは独自のプラグインを作成して機能拡張できます。

基本的なプラグイン作成ステップ:

  1. quartz/plugins/custom ディレクトリを作成
  2. プラグインファイル（例: myPlugin.ts）を作成:
import { QuartzTransformerPlugin } from "../types"
 
export const MyCustomPlugin: QuartzTransformerPlugin = () => {
  return {
    name: "MyCustomPlugin",
    transform(ctx) {
      // コンテンツを変換するロジック
      return ctx
    },
  }
}
  1. quartz.config.ts にプラグインを登録:
import { MyCustomPlugin } from "./quartz/plugins/custom/myPlugin"
 
export default defineConfig({
  plugins: {
    transformers: [
      // ...他のプラグイン
      MyCustomPlugin(),
    ],
  },
})

人気のカスタムプラグイン例:

  • コードブロック構文ハイライト拡張
  • 数式レンダリング

Folders/Files Order

フォルダやファイルの表示順序をカスタマイズできます。

quartz.config.ts:

Plugin.Explorer({
  sortFn: (a, b) => {
    // フォルダを常にファイルの前に表示
    if (a.file.slug.split("/").length !== b.file.slug.split("/").length) {
      return a.file.slug.split("/").length - b.file.slug.split("/").length
    }
    
    // 数字プレフィックスによる順序付け（例: 01-intro, 02-setup）
    const aMatch = a.file.slug.match(/^(\d+)-/)
    const bMatch = b.file.slug.match(/^(\d+)-/)
    if (aMatch && bMatch) {
      return parseInt(aMatch[1]) - parseInt(bMatch[1])
    }
    
    // デフォルトはアルファベット順
    return a.file.slug.localeCompare(b.file.slug)
  }
})

Advanced Features

Search Functionality

Quartzに検索機能を追加する方法:

  1. quartz.config.ts で検索プラグインを有効化:
Plugin.Search({
  enablePreview: true,
  searchOnlyTitle: false,
  mode: "basic"  // "basic" または "performance"
})
  1. 検索インデックスのカスタマイズ:
Plugin.Search({
  // ...
  extraProperties: ["tags", "description"],
  customSearchFilter: (node) => {
    // 特定の条件に基づくフィルタリング
    return !node.slug.startsWith("private/")
  }
})

Multilingual Support

多言語サイトのセットアップ:

  1. 言語ごとにコンテンツディレクトリを作成:
content/
  en/
    index.md
    about.md
  ja/
    index.md
    about.md
  1. フロントマターに言語を指定:
---
title: ページタイトル
lang: ja
---
  1. 言語切り替えコンポーネントを追加:
// languageSwitcher.tsx
import { QuartzComponentConstructor } from "../types"
 
export const LanguageSwitcher: QuartzComponentConstructor = () => {
  // 実装
}
 
// quartz.config.ts
import { LanguageSwitcher } from "./components/languageSwitcher"
 
export default defineConfig({
  components: {
    beforeBody: [LanguageSwitcher],
  },
})

Graph View

知識グラフビューを使用すると、コンテンツ間の関係を視覚化できます:

  1. グラフビューを有効化:
Plugin.Component.Graph({
  localGraph: {
    enabled: true,
    depth: 2,
  },
  globalGraph: {
    enabled: true,
    scale: 1.0,
  },
})
  1. グラフのカスタマイズオプション:
  • drag: ドラッグ操作の有効化（true/false）
  • zoom: ズーム操作の有効化（true/false）
  • depth: ローカルグラフの深さ
  • repelForce: ノード間の反発力

Callouts

特別な強調ブロック（Callouts）の使用:

Markdownで記述:

> [!NOTE]
> 
> これは注釈です
 
> [!WARNING]
> 
> これは警告です
 
> [!TIP]
> 
> これはヒントです

サポートされているCalloutタイプ:

  • NOTE: 一般的な注釈
  • INFO: 情報
  • WARNING: 警告
  • ERROR: エラー
  • TIP: ヒント
  • EXAMPLE: 例
  • QUESTION: 質問
  • SUMMARY: 要約

カスタムCalloutの追加:

Plugin.Component.Callout({
  customTypes: {
    "CUSTOM": {
      color: "#8855ff",
      icon: "💫"
    }
  }
})

Performance Optimization

Image Optimization

画像の最適化設定:

Plugin.Assets({
  imageOptimization: {
    enabled: true,
    quality: 80,
    formats: ["webp", "avif"]
  }
})

主な設定項目:

  • quality: 圧縮品質（0-100）
  • formats: 変換フォーマット
  • maxWidth: 最大幅（ピクセル）

Code Splitting

大規模サイトのパフォーマンス向上のためのコード分割:

export default defineConfig({
  // ...
  build: {
    bundleConfig: {
      shouldSplitComponents: true,
      splitting: true,
    },
  },
})

Lazy Loading

コンテンツの遅延読み込み設定:

Plugin.Component.Image({
  lazyLoad: true,
  centerImages: true
})

Deployment and Integration

GitHub Actions

Analytics Integration

アナリティクス統合:

Google Analyticsの追加:

Plugin.Analytics({
  provider: "google",
  trackingId: "G-XXXXXXXXXX"
})

Plausible Analyticsの追加:

Plugin.Analytics({
  provider: "plausible",
  host: "plausible.io"
})

Conclusion

Quartzの基本設定から高度なカスタマイズまで幅広くカバーしました。これらの設定を活用することで、強力でパーソナライズされたデジタルガーデンやドキュメントサイトを構築できます。

Quartzが提供する柔軟性と拡張性を最大限に活用し、独自のウェブサイトを作成してください。スタイリング、プラグイン、コンテンツ構造など、あらゆる要素を自由にカスタマイズして、ニーズに合った最適な環境を構築しましょう。

参考リソース:

Graph View