ソーシャルカードプラグインを導入する (#1117)

* Azure AD B2C サンプルのReadMeの誤字修正とcspellの除外設定追加 (#1051) * cspellの除外設定を追加。 * 誤字修正。 --------- Co-authored-by: Fumika Koyama <[email protected]> * アプリケーションアーキテクチャ概要編からコンソールアプリの要件別サンプルにリンクを張る (#1057) * リンクを追加 * 冗長な記載を修正 * documentsのreadmeを最新化する (#1062) * フォルダー構造を修正。 * 「テスト方針」と「画像ファイル」のフォルダー構成を修正。 --------- Co-authored-by: Fumika Koyama <[email protected]> * mkdocs.ymlとドキュメントリリース用のYAMLに設定を追加。 * pngquantをsudoでインストールするよう修正。 * enabledの設定を削除。 * プラグインの記載位置を変更。 * lintエラーに対応。 * BUILD_DOCUMENTS=trueの時にソーシャルカードを生成するよう修正。 * 不要な設定を削除。 * タイトルとロゴのみのソーシャルカードを生成。 * インデントを修正。 * 不要なスペースを削除。 * タイトルのみを表示する。 * アイコンの設定を修正。 * アイコンの設定を削除。 * デフォルトのソーシャルカードのdescriptionを非表示にする。 * 不要なファイルを削除。 * ソーシャルカード内にtitleとdescriptionが入るきるよう修正。 * titleが付いていないページにtitle追加。 * descriptionの文字数を調整。 * descriptionのスペースを調整。 * 「.NET Fw」の表記を修正。 * READMEにソーシャルカードについての説明を追加。 * descriptionが抜けている部分に追記。 * titleとdescriptionを設定するようmarkdownlintのルールを追加。 * 商標ページのdescriptionを修正。 Co-authored-by: tsuna-can-se <[email protected]> * ソーシャルカードの確認方法を修正。 --------- Co-authored-by: Fumika Koyama <[email protected]> Co-authored-by: kentah <[email protected]> Co-authored-by: tsuna-can-se <[email protected]>
AlesInfiny · Apr 26, 2024 · 391639d · 391639d
1 parent 60d2fc8
commit 391639d
Show file tree

Hide file tree

Showing 68 changed files with 174 additions and 63 deletions.
diff --git a/.github/workflows/build-and-release-documents.yml b/.github/workflows/build-and-release-documents.yml
@@ -5,14 +5,14 @@ name: ドキュメントのビルドとリリース
 
 on:
   push:
-    branches: [main]
     tags:
       - 'v[0-9]+.[0-9]+.[0-9]+'
       - 'v[0-9]+.[0-9]+.[0-9]+-Beta[0-9]+'
   workflow_dispatch:
 
 permissions:
   id-token: write
+  contents: write
 
 env:
   APP_ALESINFINY_MARIS_WEBAPP_NAME: app-alesinfiny-maris-docs-prod
@@ -52,6 +52,7 @@ jobs:
         uses: ./.github/workflows/compress-sample-source
         with:
           compressed-source-path: ${{ env.DOCUMENT_BASE_PATH }}/${{ env.COMPRESSED_SOURCE_PATH }}
+
       - name: ドキュメントのビルド
         uses: ./.github/workflows/build-documents
         with:

diff --git a/.github/workflows/build-documents/action.yml b/.github/workflows/build-documents/action.yml
@@ -2,10 +2,10 @@ name: "ドキュメントのビルド"
 description: "ドキュメントをビルドします。"
 inputs:
   document-base-path:
-    desctiption: "ドキュメントのベースフォルダパス"
+    description: "ドキュメントのベースフォルダパス"
     required: true
   output-folder-name:
-    desctiption: "ビルドしたドキュメントの出力先フォルダ名"
+    description: "ビルドしたドキュメントの出力先フォルダ名"
     required: true
 runs:
   using: "composite"
@@ -21,6 +21,12 @@ runs:
         python -m pip install --upgrade pip
         python -m pip install -r requirements.txt
 
+    - name: ソーシャルカードプラグイン用のパッケージインストール
+      shell: bash
+      run: |
+        python -m pip install "mkdocs-material[imaging]"
+        sudo apt-get install pngquant
+
     - id: setup-version
       name: ドキュメントのバージョン設定
       shell: bash
@@ -37,6 +43,7 @@ runs:
       continue-on-error: true
       shell: bash
       run: |
+        export BUILD_DOCUMENTS=true
         cd "${{ inputs.document-base-path }}"
         echo '# Mkdocs Build Result :factory:' >> $GITHUB_STEP_SUMMARY
         mkdocs build --verbose --clean --strict --site-dir "${{ inputs.output-folder-name }}" > mkdocs_build_log.txt

diff --git a/.github/workflows/compress-sample-source/action.yml b/.github/workflows/compress-sample-source/action.yml
@@ -2,7 +2,7 @@ name: "サンプルアプリケーションのソースコード圧縮"
 description: "サンプルアプリケーションのソースコードを圧縮します。"
 inputs:
   compressed-source-path:
-    desctiption: "圧縮したソースコードを配置するフォルダのGITHUB_WORKSPACEからの相対パス"
+    description: "圧縮したソースコードを配置するフォルダのGITHUB_WORKSPACEからの相対パス"
     required: true
 
 runs:

diff --git a/.github/workflows/lint-documents/action.yml b/.github/workflows/lint-documents/action.yml
@@ -34,7 +34,7 @@ runs:
       shell: bash
       run: |
         echo '## Markdownlint Result' >> $GITHUB_STEP_SUMMARY
-        npx markdownlint --config .markdownlint.yaml --ignore **/node_modules/** --output markdownlint-result.txt .
+        npx markdownlint --config .markdownlint.yaml --rules custom-lint-rules --ignore **/node_modules/** --output markdownlint-result.txt .
         echo ':heavy_check_mark: Markdownlint に成功しました。' >> $GITHUB_STEP_SUMMARY
 
     - name: Markdownlint 失敗時の結果表示

diff --git a/.github/workflows/pack-and-upload/action.yml b/.github/workflows/pack-and-upload/action.yml
@@ -2,7 +2,7 @@ name: "ビルドアーティファクトのパッケージングとアップロ
 description: "ドキュメントをzip化してアップロードします。"
 inputs:
   packaging-folder-path:
-    desctiption: "パッケージングする対象のGITHUB_WORKSPACEからの相対パス"
+    description: "パッケージングする対象のGITHUB_WORKSPACEからの相対パス"
     required: true
   document-artifact-path:
     description: "zipファイルのGITHUB_WORKSPACEからの相対パス"

diff --git a/custom-lint-rules/requires-title-and-description.js b/custom-lint-rules/requires-title-and-description.js
@@ -0,0 +1,37 @@
+
+const hasTitleAndDescription = (params, onError) => {
+    const title_line = params.frontMatterLines.filter((line) =>
+      line.startsWith("title: ")
+    );
+    const description_line = params.frontMatterLines.filter((line) =>
+        line.startsWith("description: ")
+      );
+    if (title_line.length < 1) {
+      onError({
+        lineNumber: 1,
+        detail: "Title is not specified",
+      });
+    } else if (title_line.length > 1) {
+        onError({
+          lineNumber: 1,
+          detail: "Document files are not allowed to specify multiple lists of title",
+        });
+    } else if (description_line.length < 1) {
+      onError({
+        lineNumber: 1,
+        detail: "Description is not specified",
+      });
+    } else if (description_line.length > 1) {
+        onError({
+          lineNumber: 1,
+          detail: "Document files are not allowed to specify multiple lists of description",
+        });
+      }
+  };
+
+module.exports = {
+    names: ["CMD001", "requires-title-and-description"],
+    description: "All documents should specify title and description",
+    tags: ["custom"],
+    function: hasTitleAndDescription,
+  };
diff --git a/documents/README.md b/documents/README.md
@@ -1,4 +1,6 @@
 <!-- textlint-disable @textlint-rule/require-header-id -->
+<!-- markdownlint-disable-file CMD001 -->
+
 # AlesInfiny Maris OSS Edition ドキュメントについて
 
 <!-- cSpell:ignore hoge hogehoge dotnetfw pymdown -->
@@ -218,6 +220,43 @@ cSpell の拡張機能をインストールしていると、 [問題] ウィン
 
     <https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell#ignore>
 
+### 各ページの title/description の設定
+
+以下のように、各 markdown ファイルの上部に `title` と `description` を設定しています。
+
+``` text
+---
+title: CSR 編
+description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
+---
+```
+
+ここで設定した `title` と `description` を元にソーシャルカードが生成されるため、以下の文字数を守って設定します。
+( `description` を省略すると、 mkdocs.yml の `site_description` の値が設定されます。)
+
+- カード上に表示できる文字数
+    - `title`：全角 9 文字×3 行まで
+    - `description`: 半角 59 文字(全角だと 30 文字目が半分途切れる)× 2 行まで
+
+※スペースを空けないと 1 単語とみなされ、同じ行に詰め込もうとして文章が途切れるので適宜スペースで区切ってください。
+
+- 例：
+
+    - `title: .NETアプリケーションの処理方式` の場合
+    ![ソーシャルカード失敗例](readme-images/social-card-example-error.png)
+    - `title: .NET アプリケーションの 処理方式` の場合
+    ![ソーシャルカード](readme-images/social-card-example.png)
+
+文字が途切れていないか等を適宜確認してください。
+ソーシャルカードはローカルでは生成せず、 CI 上でのドキュメントビルド時に生成されるよう設定しています。
+生成されたソーシャルカードは以下の手順で確認してください。
+
+1. GitHub Actions の「ドキュメントのビルド(CI 用)」を開き、対象のブランチを選択してワークフローを実行します。
+
+1. 実行したワークフローの Summary の Artifacts から　documents をダウンロードします。
+
+1. ダウンロードした documents.zip 内の docs.zip を解凍し、`assets/images/social` に生成されたソーシャルカードを確認します。
+
 ### 修正内容のコミット
 
 記事の作成と体裁の修正が完了したら、 Feature ブランチにコミットします。

diff --git a/documents/contents/about-maris/credits.md b/documents/contents/about-maris/credits.md
@@ -1,5 +1,6 @@
 ---
 title: クレジット表記
+description: AlesInfiny Maris OSS Edition ポータルサイトのクレジット表記です。
 ---
 
 <!-- textlint-disable @textlint-rule/require-header-id -->

diff --git a/documents/contents/about-maris/terms.md b/documents/contents/about-maris/terms.md
@@ -1,5 +1,6 @@
 ---
 title: 利用規約
+description: AlesInfiny Maris OSS Edition ポータルサイトの利用規約です。
 ---
 
 # 利用規約 {#top}

diff --git a/documents/contents/about-maris/trademarks.md b/documents/contents/about-maris/trademarks.md
@@ -1,5 +1,6 @@
 ---
 title: 商標
+description: AlesInfiny Maris OSS Edition の商標について説明します。
 ---
 
 # 商標 {#top}

diff --git a/...ts/contents/app-architecture/client-side-rendering/csr-architecture-overview.md b/...ts/contents/app-architecture/client-side-rendering/csr-architecture-overview.md
@@ -1,6 +1,6 @@
 ---
 title: CSR 編
-description: クライアントサイドレンダリングを行う Web アプリケーションのアーキテクチャについて解説します。
+description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
 ---
 
 # CSR アーキテクチャ概要 {#top}

diff --git a/documents/contents/app-architecture/client-side-rendering/frontend-architecture.md b/documents/contents/app-architecture/client-side-rendering/frontend-architecture.md
@@ -1,6 +1,6 @@
 ---
 title: CSR 編
-description: クライアントサイドレンダリングを行う Web アプリケーションのアーキテクチャについて解説します。
+description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
 ---
 
 # フロントエンドアーキテクチャ {#top}

diff --git a/documents/contents/app-architecture/client-side-rendering/global-function.md b/documents/contents/app-architecture/client-side-rendering/global-function.md
@@ -1,6 +1,6 @@
 ---
 title: CSR 編
-description: クライアントサイドレンダリングを行う Web アプリケーションのアーキテクチャについて解説します。
+description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
 ---
 
 # 全体処理方式 {#top}

diff --git a/documents/contents/app-architecture/client-side-rendering/index.md b/documents/contents/app-architecture/client-side-rendering/index.md
@@ -1,6 +1,6 @@
 ---
 title: CSR 編
-description: クライアントサイドレンダリングを行う Web アプリケーションのアーキテクチャについて解説します。
+description: クライアントサイドレンダリングを行う Web アプリケーションの アーキテクチャについて解説します。
 ---
 
 # クライアントサイドレンダリング編 {#top}

diff --git a/...ts/app-architecture/client-side-rendering/test/backend-application/unit-test.md b/...ts/app-architecture/client-side-rendering/test/backend-application/unit-test.md
@@ -1 +1,6 @@
+---
+title: CSR 編 - テスト
+description: バックエンドアプリケーションのテスト方針について解説します。
+---
+
 # 単体テスト ( UT0 ) {#top}
diff --git a/documents/contents/app-architecture/console-app/index.md b/documents/contents/app-architecture/console-app/index.md
@@ -1 +1,6 @@
+---
+title: コンソール アプリケーション編
+description: コンソールアプリケーションの アーキテクチャについて解説します。
+---
+
 # コンソールアプリケーション編 {#top}
diff --git a/documents/contents/app-architecture/index.md b/documents/contents/app-architecture/index.md
@@ -1,3 +1,8 @@
+---
+title: アプリケーション アーキテクチャ
+description: AlesInfiny Maris OSS Edition を利用することで構築できる アプリケーションについて説明します。
+---
+
 # アプリケーションアーキテクチャ {#top}
 
 - [概要編](./overview/index.md)

diff --git a/documents/contents/app-architecture/overview/application-kind.md b/documents/contents/app-architecture/overview/application-kind.md
@@ -1,6 +1,6 @@
 ---
 title: 概要編
-description: AlesInfiny Maris OSS Edition を利用することで構築できるアプリケーションの概要を、アプリケーション形態ごとに説明します。
+description: AlesInfiny Maris OSS Edition を利用することで構築できる アプリケーションの概要を説明します。
 ---
 
 # 構築できるアプリケーション形態 {#top}

diff --git a/documents/contents/app-architecture/overview/application-structure.md b/documents/contents/app-architecture/overview/application-structure.md
@@ -1,6 +1,6 @@
 ---
 title: 概要編
-description: AlesInfiny Maris OSS Edition を利用することで構築できるアプリケーションの概要を、アプリケーション形態ごとに説明します。
+description: AlesInfiny Maris OSS Edition を利用することで構築できる アプリケーションの概要を説明します。
 ---
 
 # アプリケーション構成 {#top}

diff --git a/documents/contents/app-architecture/overview/configuration-management.md b/documents/contents/app-architecture/overview/configuration-management.md
@@ -1,6 +1,6 @@
 ---
 title: 概要編
-description: AlesInfiny Maris OSS Edition のアプリケーションアーキテクチャ概要を解説します。
+description: AlesInfiny Maris OSS Edition を利用することで構築できる アプリケーションの概要を説明します。
 ---
 
 # 構成管理 {#top}

diff --git a/...ure/overview/dotnet-application-processing-system/event-id-management-policy.md b/...ure/overview/dotnet-application-processing-system/event-id-management-policy.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/...ture/overview/dotnet-application-processing-system/exception-handling-policy.md b/...ture/overview/dotnet-application-processing-system/exception-handling-policy.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/...tecture/overview/dotnet-application-processing-system/health-check-necessity.md b/...tecture/overview/dotnet-application-processing-system/health-check-necessity.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/...ontents/app-architecture/overview/dotnet-application-processing-system/index.md b/...ontents/app-architecture/overview/dotnet-application-processing-system/index.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/...ecture/overview/dotnet-application-processing-system/input-validation-policy.md b/...ecture/overview/dotnet-application-processing-system/input-validation-policy.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/...pp-architecture/overview/dotnet-application-processing-system/logging-policy.md b/...pp-architecture/overview/dotnet-application-processing-system/logging-policy.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/...ture/overview/dotnet-application-processing-system/message-management-policy.md b/...ture/overview/dotnet-application-processing-system/message-management-policy.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/.../overview/dotnet-application-processing-system/transaction-management-policy.md b/.../overview/dotnet-application-processing-system/transaction-management-policy.md
@@ -1,5 +1,5 @@
 ---
-title: .NETアプリケーションの処理方式
+title: .NET アプリケーションの 処理方式
 description: AlesInfiny Maris OSS Edition で構築する .NET アプリケーションの共通的な処理方式を解説します。
 ---
 

diff --git a/documents/contents/app-architecture/overview/index.md b/documents/contents/app-architecture/overview/index.md
@@ -1,6 +1,6 @@
 ---
 title: 概要編
-description: AlesInfiny Maris OSS Edition を利用することで構築できるアプリケーションの概要を、アプリケーション形態ごとに説明します。
+description: AlesInfiny Maris OSS Edition を利用することで構築できる アプリケーションの概要を説明します。
 ---
 
 # 概要編 {#top}

diff --git a/...ents/guidebooks/how-to-develop/dotnet/configure-asp-net-core-web-api-project.md b/...ents/guidebooks/how-to-develop/dotnet/configure-asp-net-core-web-api-project.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # ASP.NET Core Web API プロジェクトの構成 {#top}

diff --git a/...ts/guidebooks/how-to-develop/dotnet/configure-asp-net-core-with-vite-project.md b/...ts/guidebooks/how-to-develop/dotnet/configure-asp-net-core-with-vite-project.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # ASP.NET Core with Vite プロジェクトの構成 {#top}

diff --git a/...contents/guidebooks/how-to-develop/dotnet/configure-integration-test-project.md b/...contents/guidebooks/how-to-develop/dotnet/configure-integration-test-project.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # 結合テストプロジェクトの構成 {#top}

diff --git a/documents/contents/guidebooks/how-to-develop/dotnet/create-project-structure.md b/documents/contents/guidebooks/how-to-develop/dotnet/create-project-structure.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # プロジェクト構造の作成 {#top}

diff --git a/documents/contents/guidebooks/how-to-develop/dotnet/create-project.md b/documents/contents/guidebooks/how-to-develop/dotnet/create-project.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # プロジェクトの作成 {#top}

diff --git a/documents/contents/guidebooks/how-to-develop/dotnet/create-solution-structure.md b/documents/contents/guidebooks/how-to-develop/dotnet/create-solution-structure.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # ソリューション構造の作成 {#top}

diff --git a/documents/contents/guidebooks/how-to-develop/dotnet/health-check-api.md b/documents/contents/guidebooks/how-to-develop/dotnet/health-check-api.md
@@ -1,6 +1,6 @@
 ---
 title: .NET 編
-description: バックエンドで動作する .NET アプリケーションの開発手順を解説します。
+description: バックエンドで動作する .NET アプリケーションの 開発手順を解説します。
 ---
 
 # ヘルスチェック API の実装 {#top}