ライブラリと編集方法

このページは、ヘルプサイトの構成、使っているライブラリ、編集方法を簡単にまとめたガイドです。

使用ライブラリ

VitePress

Markdown から静的なヘルプサイトを生成するライブラリです。記事は docs/ 配下の .md ファイルとして管理します。

主な編集対象:

• docs/index.md: ホーム
• docs/samplehelp/: ヘルプ記事
• docs/.vitepress/config.mts: ナビゲーション、サイドメニュー、検索、サイト設定
• docs/.vitepress/theme/style.css: 色、余白、ボタンなどの見た目

Sveltia CMS

ブラウザ上で Markdown 記事を編集するための CMS です。管理画面は /admin/ で開きます。

主な編集対象:

• docs/public/admin/index.html: CMS 本体を読み込む入口
• docs/public/admin/config.yml: GitHub repository、編集できるファイル、入力項目の設定

Phosphor Icons

UI に使うアイコンライブラリです。この VitePress プロジェクトでは Vue 用の @phosphor-icons/vue を使っています。

コンポーネントで使う例:

<script setup lang="ts">
import { PhBookOpenText } from '@phosphor-icons/vue'
</script>

<template>
  <PhBookOpenText :size="20" weight="regular" aria-hidden="true" />
</template>

アイコンだけのボタンに使う場合は、見た目だけで意味が失われないように aria-label や tooltip を付けます。

記事の編集方法

記事を直接編集する場合は docs/samplehelp/ 配下の Markdown を変更します。

docs/samplehelp/index.md
docs/samplehelp/getting-started.md
docs/samplehelp/faq.md
docs/samplehelp/setup/environment.md
docs/samplehelp/setup/first-article.md
docs/samplehelp/operations/editing.md

編集後は次を実行します。

bun run verify

サイドメニューの編集方法

サイドメニューは docs/.vitepress/config.mts の sharedSidebar で一元管理しています。全ページで同じサイドメニューを出すため、ページごとに別々の sidebar は持たせていません。

samplehelp 配下の記事は docs/samplehelp/**/*.md から自動生成します。CMS で記事を追加して GitHub に commit され、Cloudflare Pages が再ビルドされると、サイドメニューにも自動表示されます。

表示順を調整したい場合は、記事の frontmatter に order を追加します。

---
title: 新しい記事
description: 新しい記事の説明
order: 35
---

ディレクトリ名の表示は docs/.vitepress/config.mts の directoryLabels で管理します。

CMS でできることとできないこと

CMS でできること:

• samplehelp ヘルプ（直下） に記事を追加する。
• samplehelp ヘルプ（セットアップ） に記事を追加する。
• samplehelp ヘルプ（運用サンプル） に記事を追加する。
• 既存記事を編集・削除する。
• 固定ページを編集する。

CMS だけでは難しいこと:

• 任意の新しいフォルダーを自由に作って、それを CMS の collection として管理すること。
• VitePress の設定ファイル自体を安全に編集すること。

Sveltia CMS の nested collections は現時点で未実装です。そのため、フォルダーを追加したい場合は、開発者が docs/public/admin/config.yml に collection を追加します。追加されたフォルダー内の記事は、サイドメニュー自動生成の対象になります。

トップページの編集方法

トップページの本文は docs/.vitepress/theme/components/SampleHome.vue にあります。ボタンやカードの見た目は docs/.vitepress/theme/style.css で調整します。

管理画面の編集方法

管理画面で編集できる項目は docs/public/admin/config.yml の collections で決まります。正式運用時は repo: owner/repo を実際の GitHub repository に変更してください。

現在の repository は次の設定です。

backend:
  name: github
  repo: factovo-mt/ft-cms-help
  branch: main

GitHub アカウントでログインしたい場合は、Sveltia CMS Authenticator を Cloudflare Workers に用意し、backend.base_url を追加します。token ログインだけなら、この設定は不要です。

公開前チェック

bun test
bun run docs:build
bun run debug:smoke

まとめて実行する場合:

bun run verify