メインコンテンツまでスキップ

Dashboards

docStaticは、TinaCMSにダッシュボード機能を追加します。Tinaは、Gitリポジトリ内のファイルシステムをデータベースとして使用してGraphQL APIを生成します。ダッシュボードは、このAPI（ローカルまたはクラウド上）にクエリを実行し、CMS上で直接、実用的なレポートを表示します。ダッシュボード機能は現在、ベータ版と見なされています。 機能自体は十分にテストされていますが、ユーザーインターフェースは暫定的なものであり、改良が必要です。ダッシュボードはページが更新されると自動的に更新されます。ダッシュボードを表示した後、他のユーザーが変更を加えた場合は、**[更新]**をクリックしてダッシュボードを更新できます。

注意

システム内のコンテンツ量によっては、一部のダッシュボードの読み込みに時間がかかる場合があります。こうしたダッシュボードは、通常、ローカルで実行すると更新が若干速くなります。

ダッシュボードの表示​

CMSから、「ダッシュボード」コレクションに移動します。 ページ上部には、GraphQL接続の状態を示すステータスバーがあります。これには、クラウドに接続されているか、ローカルホストに接続されているかが表示されます。ローカルホストが利用可能な場合、常にローカルホストに接続されます。クラウドを使用するには、ローカル開発サーバーが停止していることを確認してください。ステータスバーには環境情報も表示され、すべての設定が有効であるかどうかも確認できます。

ワークフローのステータスの表示​

「コンテンツ概要」ダッシュボードには、/docs パス内のトピックの総数と、各ワークフローステータスにあるトピック数が表示されます：

  • 下書き
  • レビュー中
  • 翻訳中
  • 承認済み
  • 公開済み
  • 非公開

ステータスリンクをクリックすると、そのステータスにあるすべてのトピックが表示されます。

[編集] をクリックすると、トピックを開いて編集できます。

[閉じる] アイコンをクリックすると、トピックの一覧を閉じます。

最近のアクティビティの表示​

[最近のアクティビティ] セクションには、最近変更されたトピックが表示されます。期間（「全期間」、「先週」、「先月」）をフィルタリングしたり、結果の件数を 5 件から 50 件に設定したりできます。

翻訳ステータスの表示​

「翻訳」ダッシュボードには、リストから選択した言語について、各トピックのステータスが表示されます：

  • 最新：翻訳の最終更新日がソースより新しい。
  • 古い：ソースの最終更新日が翻訳より新しい。
  • 欠落：対応する翻訳ファイルがないソースファイルが存在します。

コンテンツの再利用状況の確認​

「コンテンツの再利用」ダッシュボードには、システム内の再利用可能なコンテンツとその使用箇所が表示されます。以下の 4 つのカテゴリについて報告されます：

  • コードスニペット：CodeSnippet コンポーネントによって参照されているコードファイル。
  • 用語集用語：用語集コレクションで定義された用語。
  • スニペット：Snippetコンポーネントによって参照されているMDXコンテンツファイル。
  • 変数セット：VariableSetコンポーネントによって参照されている変数セット。

カテゴリカードをクリックすると、そのカテゴリ内のアイテム一覧と、各アイテムが使用されているトピックが表示されます。

再利用の提案の表示​

「コンテンツ再利用」ダッシュボードの「提案」セクションでは、再利用可能なコンポーネントに変換できるコンテンツを特定します：

  • 候補となるスニペット（コード）：トピック内のインラインコードブロックで、コードスニペットファイルとして抽出できるもの。
  • 候補となる用語：トピック内にプレーンテキストとして表示されている用語集の用語で、代わりにGlossaryTermコンポーネントを使用できるもの。
  • 候補となるスニペット（重複テキスト）：2つ以上のトピックに表示されているテキストブロックで、スニペットファイルとして抽出できるもの。
  • 変数の候補：トピック内にプレーンテキストとして表示されている変数値で、代わりに「VariableSet」コンポーネントを使用できるもの。

提案カードをクリックすると、検出された項目とそれらが表示されているトピックを確認できます。

メディアの再利用状況の確認​

「メディアライブラリ」ダッシュボードでは、/static/img パス内のコンテンツがどこで使用されているかが表示されます。ファイルと画像の総数、ファイルサイズ、画像のパス、および画像サイズが表示されます。

以下の条件でフィルタリングできます：

  • すべてのコンテンツ。
  • 画像のみ。
  • 最近（7日間）。
  • 使用済み。
  • 未使用。

使用済みのコンテンツについては、「n 件のドキュメントで使用」をクリックすると、そのコンテンツが使用されているトピックが表示されます。その後、「編集」をクリックして、それらのトピックを編集できます。

リンクの状態の確認​

このページにある他のダッシュボードとは異なり、「リンクの状態」ダッシュボードは「ダッシュボード」ではなく、URL コレクション内にあります： ここは、<Url> コンポーネントで使用される 一元管理された URL を管理するのと同じ場所であるため、リンクの状態確認とリンク管理が一体となっています。

このダッシュボードは、トピック内のハイパーリンク および 「URL」コレクションに保存されているURLについて、HTTPステータスを含めて報告します。したがって、404や500を返すページは、その出所にかかわらず、リンク切れとして識別されます。 ダッシュボードには、前回のサイトビルド時に組み込まれた、直近の yarn check-links 実行結果が表示されます。実際の HTTP ステータスに基づいてリンクを確認するには、次のコマンドを実行してください：

yarn check-links

これにより、ドキュメント内にハードコードされているものとURLコレクションに保存されているものの両方のすべての外部リンクがリクエストされ、各サーバーからの応答が記録され、レポートが更新されます。最新の結果が必要なときはいつでもこれを実行し、その後サイトを再構築して、ダッシュボードが新しいレポートを反映するようにしてください。ダッシュボードには、前回のチェックの日時が表示されます。

再ビルドせずにダッシュボードを更新するには、ダッシュボード上のRefreshをクリックしてください。これにより、GraphQL経由で現在のドキュメントとURLコレクションが照会されるため、前回のビルド以降に行われた編集が反映されます。これは、yarn check-linksを実行するためのシェルがないTinaCloudで便利です。 また、ブラウザから直接外部リンクを調査することもできますが、ブラウザでは yarn check-links のように他サイトへのリンクの HTTP ステータスを読み取ることができないため、Refresh が自身でチェックした項目は「OK」や「Broken」ではなく「Unverified」として報告されます。 また、まだ存在しているリンクについて、yarn check-linksがすでに記録した実際の判定を上書きすることは決してなく、新しく追加されたものやこれまでチェックされていなかったもののみを補完します。

レポートには以下の項目が含まれます：

  • リンクの総数。
  • OK：サーバーから成功またはリダイレクトステータスが返されました。
  • 破損：サーバーから 404 Not Found や 500 Internal Server Error などのエラーステータスが返されました。これらは修正が必要なリンクです。
  • 未確認：応答が返されなかったため、リンクを判定できませんでした。 原因としては、ドメインの解決に失敗した場合、リクエストがタイムアウトした場合、サイトが403でリクエストを拒否した場合、429によるレート制限などが挙げられます。これらはリンク自体ではなく、チェックを実行しているマシン側の問題である可能性もあるため、ハイパーリンクをクリックして手動で検証してください。
  • 内部：リクエストされていないリンク。これには、内部リンク、アンカー、mailto: および tel: リンク、localhost アドレスが含まれます。
  • スキャンされたファイル。
  • 一元化：チェックされたリンクのうち、ドキュメント内にハードコードされているものではなく、URL コレクションに由来するものの数。
  • 移行候補：ドキュメントにハードコードされており、URLコレクションにはまだ存在せず、一元化する価値のある個別の外部URL。条件については以下を参照してください。

内部リンクは、サイトの構築プロセスにおいて実際のページリストと照合して検証され、破損しているものが報告されるため、ここでは意図的にリクエスト対象から除外されています。 localhostアドレスもスキップされます。これらは、チェックを行っているマシン上でたまたま実行されているものを指すためです。localhost URLをドキュメントに記載しても、報告されることはありません。

ダッシュボードには、問題のあるリンクを含むファイルが一覧表示され、各ファイルにはドキュメント由来かURLコレクション由来かのタグが付与されるため、どのファイルを開くべきかがわかります。 また、移行候補も一覧表示されます。これは、まだ一元化されていないドキュメントで使用されている外部URLであり、複数のドキュメントで重複して使用されているURLは1回だけ表示されるようグループ化されており、一元化ボタンをクリックするとURLコレクションに追加されます。

一元化をクリックすると、そのエントリがURLコレクションのフォームに追加されますが、ダッシュボード上の表示には反映されません。 エントリを保存し（必要な他の言語のURLを追加して）、**Refreshをクリックすると、エントリは「一元化済み、ドキュメントでは未更新」ステータスに移行し、Replace**ボタンが表示されます。 このギャップは意図的なものであり、回避すべき問題ではありません。「置換」ボタンは、エントリにハードコードされたリンクを置換するためのデータが実際に揃うまでは表示されるべきではありません。また、エントリに必要な言語バリエーションの入力は自動化できません。サイトによってその扱いが一貫しておらず、パスプレフィックスやドメインが異なり、 言語ごとのURLが全く存在しないサイトなど——これらを人が手作業で調べて入力する以外に方法はありません。

URLを一元化しても、そのURLをハードコードしたままのドキュメントには影響しません。これは別のステップとなります。urls.jsonへのエントリ追加と、すべてのドキュメント内の参照をそれに置き換えることは、異なる編集作業だからです。 ダッシュボードでは、これらを**「一元化済み、ドキュメント未更新」の項目で個別に追跡しており、「置換」**ボタンをクリックするだけで、そのURLがハードコードされている箇所をすべて、出現するドキュメントの数に関係なく、一挙に<Url>参照に置き換えることができます。 各出現箇所は独自のリンクテキストを保持します。つまり、2つの異なるドキュメントで異なる文言でリンクされているURLの場合、互いに上書きし合うのではなく、それぞれに異なる上書きが適用されます—ただし、その文言がすでにその言語のキーのデフォルトテキストと一致している場合は例外です。その場合、「置換」機能は上書きを適用せず、キーそのものが同じ役割を果たします。これにより、将来変更が必要になる可能性のあるすべてのドキュメントに同じ文字列を重複して書き込む必要がなくなります。

また、「Replace」は、各ドキュメントのすべての翻訳を英語のソースとは独立してチェックし、同じリンクがまだハードコードされている翻訳があれば、ソースの表現ではなく、その翻訳独自の表現を使用して更新します。 ローカライズされた <Url> は、すべての言語で実際に使用されて初めてその価値が発揮されるため、翻訳をハードコードしたままにしておくと、そもそもリンクを一元化する意味が失われてしまいます。存在しない翻訳、あるいはたまたまこの特定のリンクをハードコードしていない翻訳については、変更されません。

ハードコードされた外部URLのすべてが移行の対象となるわけではありません。URLを一元化しても、それが繰り返し使用されているか、言語バリエーションを含んでいる場合にのみ効果が発揮されるため、以下のいずれかの条件を満たすURLのみがここに表示されます：

  • 2つ以上のドキュメントでハードコードされている。
  • リンク先が言語バリエーションを持つ場合：ページ自体が <link rel="alternate" hreflang> で言語バリエーションを宣言しているか、またはウィキペディアの記事である場合（これは既知の例外です。ウィキペディアには言語バリエーションがありますが、それらに対する hreflang タグは公開されていません）。

言語バリエーションが検出されないページへの単発リンクは、単なるハードコードされたリンクのままとなります。それ単体では urls.json にエントリを追加する価値はありません。言語バリエーションのみを条件として該当する候補には 言語バリエーションあり とラベル付けされ、重複カウントのルールがスキップされたように見えないようにしています。

hreflangを検出するには、対象ページのHTMLを取得する必要がありますが、これを確実に実行できるのはyarn check-linksのみです。これはNodeから実行されるため、ブラウザのクロスオリジン制限の影響を受けません。 Refreshをクリックすると、ブラウザからも同様の処理が試みられます。これは、寛容なCORSヘッダーを送信するサイトでは機能しますが、そうではないサイトも数多く存在します。サイトが読み取りをブロックした場合、Refreshではバリエーションが存在するかどうかを判断する手段がなく、yarn check-linksが実行されるまでその候補は除外されたままになります。 ウィキペディアの例外は、リクエストではなくホスト名によって判断されるため、どちらの場合にも適用されます。

例えば継続的インテグレーション（CI）ジョブなどで、リンク切れが見つかった場合にビルドを失敗させたい場合は、yarn check-links --strict を実行してください。これにより、リンク切れの場合のみエラーで終了し、未検証のリンクでは終了しないため、一時的なネットワークの問題によってビルドが失敗することはありません。