docs: update rule documents (#55)

* docs: update rule documents

* docs: update japanese documents

* docs: fix japanese comment

.vscode/settings.json

@@ -9,5 +9,10 @@
     "source.fixAll.eslint"
   ],
   "typescript.preferences.importModuleSpecifier": "relative",
-  "cSpell.words": ["TSES", "vitepress"]
+  "cSpell.words": ["TSES", "vitepress"],
+  "markdownlint.config": {
+    "MD001": false,
+    "MD025": false,
+    "MD033": false
+  }
 }

docs/getting-started/example.md

@@ -5,9 +5,11 @@ titleTemplate: ":title"
 
 # Example
 
-Below is an example of eslint.config.mjs.
+Below is an example of `eslint.config.mjs`.
 
-Note: We recommend using typescript-eslint together.
+<div style="margin-top:16px; margin-bottom:16px; background-color: #595959; padding: 16px;border-radius: 4px;">
+  💡 We recommend using typescript-eslint together.
+</div>
 
 ```js
 import eslint from "@eslint/js";
@@ -16,10 +18,10 @@ import tsEslint from "typescript-eslint";
 
 export default tsEslint.config(
   eslint.configs.recommended,
-  ...tsEslint.configs.strict,
+  ...tsEslint.configs.recommended, // or ...tsEslint.configs.strict
   ...tsEslint.configs.stylistic,
   {
-    files: ["**/*.ts"],
+    files: ["lib/**/*.ts", "bin/*.ts"],
     languageOptions: {
       ecmaVersion: "latest",
       sourceType: "module",
@@ -37,7 +39,7 @@ export default tsEslint.config(
     },
   },
   {
-    ignores: ["node_modules"],
+    ignores: ["cdk.out", "node_modules"],
   }
 );
 ```

docs/getting-started/index.md

@@ -27,9 +27,15 @@ pnpm install -D eslint-cdk-plugin
 
 ## Setting eslint config
 
-Write eslint.config.mjs as follows:
+Write `eslint.config.mjs` as follows:
 
-Note: This plugin only supports flatConfig
+<div style="margin-top:16px; margin-bottom:16px; background-color: #595959; padding: 16px;border-radius: 4px;">
+  🚨 This plugin only supports FlatConfig.
+  <br />
+  ❓ <a href="https://eslint.org/docs/latest/use/configure/configuration-files#configuration-file-formats">
+    What's FlatConfig?
+  </a>
+</div>
 
 ```js
 // eslint.config.mjs
@@ -48,7 +54,7 @@ export default [
 
 ## Customize rules
 
-If you want to customize the rules, write eslint.config.mjs as follows:
+If you want to customize the rules, write `eslint.config.mjs` as follows:
 
 ```js
 // eslint.config.mjs

docs/ja/getting-started/example.md

@@ -5,9 +5,11 @@ titleTemplate: ":title"
 
 # Example
 
-以下に、eslint.config.mjs の記述例を示します。
+以下に、`eslint.config.mjs` の記述例を示します。
 
-※typescript-eslint と一緒に使用することを推奨します。
+<div style="margin-top:16px; margin-bottom:16px; background-color: #595959; padding: 16px;border-radius: 4px;">
+  💡 typescript-eslint と一緒に使用することを推奨します。
+</div>
 
 ```js
 import eslint from "@eslint/js";
@@ -16,10 +18,10 @@ import tsEslint from "typescript-eslint";
 
 export default tsEslint.config(
   eslint.configs.recommended,
-  ...tsEslint.configs.strict,
+  ...tsEslint.configs.recommended, // or ...tsEslint.configs.strict
   ...tsEslint.configs.stylistic,
   {
-    files: ["**/*.ts"],
+    files: ["lib/**/*.ts", "bin/*.ts"],
     languageOptions: {
       ecmaVersion: "latest",
       sourceType: "module",
@@ -29,15 +31,15 @@ export default tsEslint.config(
       },
     },
     plugins: {
-      cdk: eslintCdkPlugin,
+      cdk: cdkPlugin,
     },
     rules: {
       ...cdkPlugin.configs.recommended.rules,
       "cdk/no-import-private": "error",
     },
   },
   {
-    ignores: ["node_modules"],
+    ignores: ["cdk.out", "node_modules"],
   }
 );
 ```

docs/ja/getting-started/index.md

@@ -27,9 +27,15 @@ pnpm install -D eslint-cdk-plugin
 
 ## eslint の設定
 
-eslint.config.mjs を以下のように記述します。
+`eslint.config.mjs` を以下のように記述します。
 
-※このプラグインは flatConfig のみをサポートしています。
+<div style="margin-top:16px; margin-bottom:16px; background-color: #595959; padding: 16px;border-radius: 4px;">
+  🚨 このプラグインは FlatConfig のみをサポートしています。
+  <br />
+  ❓  <a href="https://eslint.org/docs/latest/use/configure/configuration-files#configuration-file-formats">
+    FlatConfig とは?
+  </a>
+</div>
 
 ```js
 // eslint.config.mjs
@@ -48,7 +54,7 @@ export default [
 
 ## ルールのカスタマイズ
 
-ルールをカスタマイズしたい場合は、eslint.config.mjs を以下のように記述します。
+ルールをカスタマイズしたい場合は、`eslint.config.mjs` を以下のように記述します。
 
 ```js
 // eslint.config.mjs

docs/ja/index.md

@@ -16,17 +16,17 @@ hero:
       link: https://github.com/ren-yamanashi/eslint-cdk-plugin
 features:
   - title: Extensive Rules
-    details: AWS CDK 開発のための広範なルールを提供します。
+    details: AWS CDK 開発のための幅広いESLintルールを提供します。
     link: /ja/rules/
     linkText: ルールを見る
     icon: 📚
   - title: Purpose driven
     details: AWS CDK のベストプラクティスに基づくルールを提供し、可読性・保守性が高く、再利用可能なコードを書く手助けをします。
     icon: 🎯
   - title: Type Safety
-    details: TypeScript の型システムを利用した堅牢なルールを提供し、より安全な CDK コードを書く手助けをします。
+    details: TypeScript の型システムを利用したルールを提供し、より安全な CDK コードを書く手助けをします。
     icon: 💪
   - title: Ease of use
-    details: シンプルなセットアップとインストール、推奨設定ですぐに使用できます。
+    details: インストール後、推奨設定を使用してすぐに使用することができます。
     icon: 🔧
 ---

docs/ja/rules/index.md

@@ -17,7 +17,24 @@ titleTemplate: ":title"
 - [no-mutable-props-interface](/ja/rules/no-mutable-props-interface)
 - [no-import-private](/ja/rules/no-import-private)
 
-## `recommended`のルール内容
+## `recommended` rules
+
+`recommended` を使用すると、簡単に設定をすることができます。
+
+```js
+// eslint.config.mjs
+import eslintCdkPlugin from "eslint-cdk-plugin";
+export default [
+  {
+    plugins: {
+      cdk: eslintCdkPlugin,
+    },
+    rules: {
+      ...eslintCdkPlugin.configs.recommended.rules,
+    },
+  },
+];
+```
 
 `recommended` を使用した場合、実際に設定される内容は以下の通りです。
 
@@ -37,8 +54,6 @@ export default [
       "cdk/pascal-case-construct-id": "error",
       "cdk/no-mutable-public-fields": "warn",
       "cdk/no-mutable-props-interface": "warn",
-      // NOTE: 上記のルールは、以下のように`recommended`を使用した場合と同じ内容です
-      // ...eslintCdkPlugin.configs.recommended.rules,
     },
   },
 ];

docs/ja/rules/no-class-in-interface.md

@@ -5,11 +5,16 @@ titleTemplate: ":title"
 
 # no-class-in-interface
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+
 このルールは、インターフェイスのプロパティにクラスを使用することを禁止します。
 
 インターフェイスのプロパティにクラスを使用すると、インターフェイスとクラス実装の間に密接な結合が作成されます。  
 さらに、クラスは本質的に変更可能であるため、インターフェイスのプロパティ型としてクラスを使用すると予期しない動作が発生する可能性があります。  
-したがって、このようなコードは避けるべきです。
+したがって、このようなコードは推奨されません。
 
 #### ✅ 正しい例
 

docs/ja/rules/no-construct-stack-suffix.md

@@ -5,6 +5,11 @@ titleTemplate: ":title"
 
 # no-construct-stack-suffix
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+
 このルールは、コンストラクト ID およびスタック ID で `Construct` または `Stack` サフィックスの使用を禁止するものです。
 
 コンストラクト ID に `Construct` が含まれていると、CDK の世界で止めるべき問題が CloudFormation テンプレートおよび AWS の世界に漏れてしまうため、好ましくありません。(スタック ID についても同様です)

docs/ja/rules/no-import-private.md

@@ -6,9 +6,14 @@ next: false
 
 # no-import-private
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  ℹ️ このルールは
+  <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  ルールには含まれていません。
+</div>
+
 このルールは、異なる階層レベルの `private` ディレクトリからのモジュールのインポートを禁止します。
 
-注: このルールは `recommended` ルールには含まれていません。  
 設定する場合は、次のように記述する必要があります。
 
 ```js

docs/ja/rules/no-mutable-props-interface.md

@@ -5,7 +5,20 @@ titleTemplate: ":title"
 
 # no-mutable-props-interface
 
-このルールは、コンストラクトまたはスタックの、`Props`(インターフェース)のパブリック変数を変更可能にすることを禁止します。
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+    ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  🔧 このルールによってエラーになるコードは
+  <a href="https://eslint.org/docs/latest/use/command-line-interface#--fix">
+    ESLint の --fix コマンド
+  </a>
+  で自動修正できます。
+</div>
+
+このルールは、コンストラクトまたはスタックの、`Props`(インターフェース)のパブリック変数を変更可能にすることを禁止します。  
+(`readonly`でない Props 変数の定義を禁止します)
 
 Props で変更可能なパブリック変数を指定すると、意図しない副作用を引き起こす可能性があるため推奨されません。
 

docs/ja/rules/no-mutable-public-fields.md

@@ -5,9 +5,22 @@ titleTemplate: ":title"
 
 # no-mutable-public-fields
 
-このルールは、クラスのパブリック変数を変更可能にすることを禁止するものです。
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+    ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  🔧 このルールによってエラーになるコードは
+  <a href="https://eslint.org/docs/latest/use/command-line-interface#--fix">
+    ESLint の --fix コマンド
+  </a>
+  で自動修正できます。
+</div>
 
-パブリック変数が変更可能である場合、意図しない副作用が発生する可能性があるため、好ましくありません。
+このルールは、クラスのパブリック変数を変更可能にすることを禁止するものです。  
+(`readonly`でないパブリック変数の定義を禁止します)
+
+パブリック変数が変更可能である場合、意図しない副作用が発生する可能性があるため、推奨されません。
 
 #### ✅ 正しい例
 

docs/ja/rules/no-parent-name-construct-id-match.md

@@ -5,9 +5,14 @@ titleTemplate: ":title"
 
 # no-parent-name-construct-id-match
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+    ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+
 このルールでは、親クラス名をコンストラクト ID として使用することを禁止します。
 
-コンストラクト ID に親クラス名と一致する文字列を指定すると、CloudFormation リソースの階層が不明瞭になるため、これは避けるべきです。
+コンストラクト ID に親クラス名と一致する文字列を指定すると、CloudFormation リソースの階層が不明瞭になるため、推奨されません。
 
 #### ✅ 正しい例
 

docs/ja/rules/no-public-class-fields.md

@@ -5,9 +5,14 @@ titleTemplate: ":title"
 
 # no-public-class-fields
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+
 このルールは、クラスの`public`変数にクラスを使用することを禁止します。
 
-`public`変数でクラス型を使用すると、密結合が作成され、可変状態が公開されるため、好ましくありません。
+`public`変数でクラス型を使用すると、密結合が作成され、可変状態が公開されるため、推奨されません。
 
 #### ✅ 正しい例
 

docs/ja/rules/pascal-case-construct-id.md

@@ -5,6 +5,18 @@ titleTemplate: ":title"
 
 # pascal-case-construct-id
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+    ✅ <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  を使用した場合、このルールが有効になります。
+</div>
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  🔧 このルールによってエラーになるコードは
+  <a href="https://eslint.org/docs/latest/use/command-line-interface#--fix">
+    ESLint の --fix コマンド
+  </a>
+  で自動修正できます。
+</div>
+
 このルールは、コンストラクト ID に PascalCase を強制します。
 
 #### ✅ 正しい例

docs/rules/index.md

@@ -19,6 +19,23 @@ You can check the details of the rules on each page.
 
 ## `recommended` rules
 
+Using `recommended` makes it easy to set up.
+
+```js
+// eslint.config.mjs
+import eslintCdkPlugin from "eslint-cdk-plugin";
+export default [
+  {
+    plugins: {
+      cdk: eslintCdkPlugin,
+    },
+    rules: {
+      ...eslintCdkPlugin.configs.recommended.rules,
+    },
+  },
+];
+```
+
 When using `recommended`, the actual content set is as follows.
 
 ```js
@@ -37,8 +54,6 @@ export default [
       "cdk/pascal-case-construct-id": "error",
       "cdk/no-mutable-public-fields": "warn",
       "cdk/no-mutable-props-interface": "warn",
-      // NOTE: The above rules are the same as when using `recommended`
-      // ...eslintCdkPlugin.configs.recommended.rules,
     },
   },
 ];

docs/rules/no-class-in-interface.md

@@ -5,6 +5,12 @@ titleTemplate: ":title"
 
 # no-class-in-interface
 
+<div style="margin-top: 16px; background-color: #595959; padding: 16px; border-radius: 4px;">
+  ✅ Using
+  <a href="https://eslint-cdk-plugin.dev/rules/#recommended-rules">recommended</a>
+  in an ESLint configuration enables this rule.
+</div>
+
 This rule disallows using class types in interface properties.
 
 When class types are used in interface properties, it creates tight coupling between the interface and the class implementation.