管理者は、Markdownドキュメントと画像をまとめた1つのZIPファイルから、製品ドキュメントをナレッジベースにインポートできます。後で同じZIPを再度インポートすると、記事が更新されます。
場所: コンテンツ → ナレッジベース の ドキュメントをインポート ボタン(管理者のみ)。
始める前に
- サーバーのPHPアップロード制限を確認してください。
upload_max_filesizeとpost_max_sizeはZIPファイルより大きくする必要があります。セットアップ → システム → ツール の 概要 パネルで両方の値を確認できます。 - カテゴリーパスを計画します。製品とそのセクションで構成し、たとえば
Ticketix/Getting Started、Ticketix/Features、Ticketix/FAQのようにします。
ZIPに含めるもの
このページの例では、同じ方法でインポートされているこのドキュメントの構成を使用しています。
categories.json
articles/
ticketix-introduction.md
ticketix-install.md
images/
ticketix-ai-connections-screenshot.webp
categories.json(任意)にはカテゴリーを記載します。.mdファイル が記事になります。どのフォルダーに置いてもかまいません。名前が_で始まるファイルとREADME.mdファイルはスキップされます。- 画像 はどのフォルダーに置いてもかまいません。各記事からは、その記事の
.mdファイルからの相対パスで参照します。
フォルダーをZIP圧縮してすべてがその1つのフォルダー内に入った場合、Ticketixはその下のファイルを読み込みます。
categories.json
カテゴリーの一覧です。path は必須で、その他のフィールドは任意です。
[
{"path": "Ticketix", "slug": "ticketix", "description": "Documentation for Ticketix.", "order": 100},
{"path": "Ticketix/Getting Started", "slug": "ticketix-getting-started", "description": "Install and set up Ticketix.", "order": 10}
]
pathは製品とそのセクションを/で区切ったものです。存在しない親カテゴリーは自動で作成されます。slug、description、orderはパスの最後の部分に適用されます。orderの値が小さいものほど先に表示されます。
記事のフロントマター
各 .md ファイルは、2本の --- 行で囲まれたフロントマターで始まり、その後にMarkdown本文が続きます。
---
title: Install Ticketix
slug: ticketix-install
category: Ticketix/Getting Started
order: 30
excerpt: Upload the installation package and run the setup.
tags: install, setup
status: published
visibility: public
---
The body of the article starts here.
| フィールド | 必須 | 意味 |
|---|---|---|
| title | はい | 記事のタイトル |
| category | はい | カテゴリーパス(例:Ticketix/Getting Started)。存在しない場合は作成されます |
| slug | いいえ | 記事のアドレス。空の場合はファイル名から取得されます |
| order | いいえ | カテゴリー内での順序 |
| excerpt | いいえ | プレーンテキストの要約 |
| tags | いいえ | カンマ区切りのタグ |
| status | いいえ | published(デフォルト)または draft |
| visibility | いいえ | public(デフォルト)または internal |
| lang | いいえ | 記事の言語。例:en、tr、de(下記の「翻訳のインポート」を参照) |
使用できるMarkdown
#による見出し。記事タイトルがページ見出しになるため、#と##はどちらもセクション見出しになります。- 段落、
**bold**、*italic*、インラインコード。 - 3つのバッククォートで囲んだコードブロック。
- 1階層の箇条書きリストと番号付きリスト。
|で列を区切った表。- 行頭に
>を付けた注記。 - 水平線。
- リンク。別の記事にリンクするには
kb:とそのスラッグを使います。例:[Write and publish Knowledge Base articles](kb:ticketix-knowledge-base)。 .mdファイルからの相対パスで指定する画像。例:。
画像はPNG、JPEG、GIF、WebPのいずれかで、1枚あたり5 MBまでです。記事に表示されるのはTicketixに保存された画像のみのため、すべての画像をZIPに含めてください。同じ画像は、複数の記事で使われていても1回だけ保存されます。
インポートを実行する
- コンテンツ → ナレッジベース を開き、ドキュメントをインポート をクリックします。
- デフォルト言語 を確認します。これは言語が指定されていないファイルの言語です(別の言語を選ばない限り英語)。ZIP ファイルをウィンドウにドロップするか、選択します。この時点ではまだ何も変更されません。
- Ticketix が ZIP をチェックし、実行内容を表示します。新規、更新、変更なし の記事数、カテゴリー と 画像 の数、言語ごとの同じ件数、作成または更新される 記事、そしてインポートできないファイルとその理由(画像の欠落や
titleの欠落など)が表示されます。 - … 件の変更をインポート をクリックして書き込むか、キャンセル をクリックします。
- 結果を確認します。例:「インポート完了:作成 19、更新 0、変更なし 0、カテゴリー変更 4、新しい画像 20。」
1つのファイルでエラーが発生しても、他のファイルの処理は止まりません。ファイルを修正して、ZIPを再度インポートしてください。チェック後に時間が経ちすぎると、Ticketixからファイルを再度選択するよう求められます。
ドキュメントを更新する
新しいバージョンの ZIP をインポートします。記事はスラッグと言語で照合されます。
- 新しいスラッグの場合は、新しい記事が作成されます。
- 既存のスラッグの場合は、同じ言語の記事が更新されます。以前のテキストはリビジョン履歴に残り、変更メモとして「インポート元」とファイル名が記録されます。
- 内容が変わっていない記事は「変更なし」としてカウントされます。
インポートによって何かが削除されることはありません。記事を削除するには、記事一覧または記事ページでアーカイブしてください。
翻訳のインポート
翻訳は、英語の原文と同じスラッグを持ち、言語だけが異なる記事です。翻訳は英語のドキュメントを取り込んだ後に、専用の ZIP でインポートしてください。例:
de_DE/
categories.json
articles/
ticketix-install.md
images/
ticketix-ai-connections-screenshot.webp
- ファイルの言語は
lang:行で決まります(例:lang: de)。この行がない場合は ZIP の最上位にある言語フォルダー(tr/、tr_TR/、de_DE/はそれぞれtrとdeになります)、それもない場合はインポートの 既定の言語 が使われます。英語、アラビア語、トルコ語、日本語、ドイツ語以外の言語のファイルはエラーになります。 - 翻訳には英語の原文のカテゴリーと並び順が適用され、ファイルの
category行とorder行は使われません。visibility行のない翻訳は、原文がスタッフ限定であればスタッフ限定になります。英語の記事は変更されません。 - 英語の原文がない翻訳は独立した記事としてインポートされ、チェックでは警告として表示されます。
- 言語フォルダー内、またはすべての記事が英語以外の 1 つの言語で書かれた ZIP の最上位にある
categories.jsonは、英語のpathで各カテゴリーを特定し、その言語の名前(title、任意)とdescriptionのみを書き込みます。英語の名前、並び順、親カテゴリーはそのまま維持されます。 - 翻訳記事で使用する画像も含めてください。英語のドキュメントなどですでに保存されている画像は、再度保存されません。
翻訳された categories.json のエントリー例:
[
{"path": "Ticketix/Getting Started", "slug": "ticketix-getting-started", "title": "Erste Schritte", "description": "Ticketix installieren und einrichten."}
]
訪問者に表示される内容については、言語と翻訳コンテンツをご覧ください。
制限
| 制限 | 値 |
|---|---|
| ZIP内のファイル数 | 最大2,000 |
| 展開後の合計サイズ | 最大200 MB |
| 画像サイズ | 1枚あたり最大5 MB |
| 画像形式 | PNG、JPEG、GIF、WebP |
安全のため、Ticketixは絶対パスや .. を含むパスがあるZIPを拒否します。