Merge pull request #226 from Peefy/add-doc-cards-for-overview-documents

feat: add doc cards for overview documents in user guides
kcl-lang · Nov 28, 2023 · 0d7d752 · 0d7d752
2 parents 4b6b12e + e242d82
commit 0d7d752
Show file tree

Hide file tree

Showing 8 changed files with 136 additions and 0 deletions.
diff --git a/docs/user_docs/guides/working-with-k8s/0-overview.md b/docs/user_docs/guides/working-with-k8s/0-overview.md
@@ -3,6 +3,9 @@ title: "Overview"
 sidebar_position: 0
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 ## Kubernetes
 
 [Kubernetes](https://kubernetes.io/) is an open source project for running and managing containerized applications on a cluster of machines.
@@ -14,3 +17,17 @@ sidebar_position: 0
 - **Dynamic configuration policy management**: **Create**, **orchestrate**, **mutate** or **validate** Kubernetes API resources for application workloads using the modern language including the use of **functions**, **schemas**, **conditionals** and **rich IDE features** (auto-completion, type & error checking, linting, refactoring, etc.) instead of YAML, JSON, scripts and templates.
 - **Import from existing Kubernetes ecosystem**: Convert **Kubernetes manifests** and **custom resource types** to KCL.
 - **Kubernetes package management**: **Install** or **publish** KCL modules from the [registry](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1) for application workload, container and service modules.
+
+## Docs
+
+<DocsCards>
+  <DocsCard header="Adopt from Kubernetes" href="adopt-from-kubernetes">
+    <p>Provides the guide to import Kubernetes manifests and CRDs to KCL.</p>
+  </DocsCard>
+  <DocsCard header="Generate Kubernetes" href="generate-k8s-manifests">
+    <p>Provides the guide to generate Kubernetes manifests using KCL.</p>
+  </DocsCard>
+  <DocsCard header="Kubernetes Tool Integrations" href="mutate-manifests/kubectl-kcl-plugin">
+    <p>Provides some Kubernetes tool integrations to mutate or validate Kubernetes manifests using KCL modules.</p>
+  </DocsCard>
+</DocsCards>
diff --git a/docs/user_docs/guides/working-with-konfig/1-overview.md b/docs/user_docs/guides/working-with-konfig/1-overview.md
@@ -3,6 +3,9 @@ id: overview
 sidebar_label: Overview
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 # Konfig Overview
 
 In KCL, it is recommended to uniformly manage all configurations and model libraries in the way of **configuration library**, that is, to store not only KCL definitions of the abstract model itself, but also various types of configurations, such as application operation and maintenance configuration, policy, etc. The configuration is recommended to be hosted in various VCS systems to facilitate configuration rollback and drift check. The best practice code of the configuration repository is Konfig, and the repository is hosted in [Github](https://github.com/kcl-lang/konfig)。
@@ -28,3 +31,17 @@ Konfig provides users with an out-of-the-box and highly abstract configuration i
 - **Domain model**: It is a model that does not contain any implementation logic and abstraction. It is often generated by tool transformation and does not need to be modified. It corresponds to the real effective YAML attribute one by one. The domain model needs to be further abstracted and is generally not directly used by users. For example, `kusion_kubernetes` is the domain model library of Kubernetes scenarios.
 
 In addition, the core model simplifies the configuration code of front-end users through two layers of abstraction: the front-end model and the back-end model. The domain model is automatically generated through the [KCL OpenAPI tool](/docs/tools/cli/openapi/quick-start).
+
+## Docs
+
+<DocsCards>
+  <DocsCard header="Structure" href="structure">
+    <p>Provides the explanation of the Konfig directory and code structure.</p>
+  </DocsCard>
+  <DocsCard header="Quick Start" href="guide">
+    <p>Provides the quick guide to use Konfig.</p>
+  </DocsCard>
+  <DocsCard header="Best Practice" href="practice">
+    <p>Provides the guide of the best practices for integrating new models into the Konfig library and designing, building and writing KCL codes.</p>
+  </DocsCard>
+</DocsCards>
diff --git a/...rus-plugin-content-docs/current/user_docs/guides/working-with-k8s/0-overview.md b/...rus-plugin-content-docs/current/user_docs/guides/working-with-k8s/0-overview.md
@@ -3,6 +3,9 @@ title: "概述"
 sidebar_position: 0
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 ## Kubernetes
 
 [Kubernetes](https://kubernetes.io/) 是一个开源项目，用于在一组机器集群上运行和管理容器化应用程序。
@@ -14,3 +17,17 @@ sidebar_position: 0
 - **动态配置策略管理**：使用现代语言（包括函数、类型、条件语句和丰富的 IDE 集成开发环境功能）来创建、编排、更改或验证应用负载的 Kubernetes API 资源，而不是使用 YAML、JSON、脚本和模板等方式。
 - **接入 Kubernetes 已有生态**：将 Kubernetes 配置清单和自定义资源类型转换为 KCL 配置和 Schema 并使用。
 - **Kubernetes 包管理**：使用 KCL 包管理工具从 Registry 下载安装和发布应用负载、容器和服务等模型。
+
+## 文档
+
+<DocsCards>
+  <DocsCard header="Adopt from Kubernetes" href="adopt-from-kubernetes">
+    <p>将 Kubernetes 清单和 CRD 转换为 KCL 代码的指南。</p>
+  </DocsCard>
+  <DocsCard header="Generate Kubernetes" href="generate-k8s-manifests">
+    <p>使用 KCL 生成 Kubernetes 清单的指南。</p>
+  </DocsCard>
+  <DocsCard header="Kubernetes Tool Integrations" href="mutate-manifests/kubectl-kcl-plugin">
+    <p>提供一些 Kubernetes 工具集成，以及使用 KCL 模块对 Kubernetes 清单进行变异或验证的指南。</p>
+  </DocsCard>
+</DocsCards>
diff --git a/...-plugin-content-docs/current/user_docs/guides/working-with-konfig/1-overview.md b/...-plugin-content-docs/current/user_docs/guides/working-with-konfig/1-overview.md
@@ -3,6 +3,9 @@ id: overview
 sidebar_label: 概述
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 # Konfig 概述
 
 在 KCL 中推荐通过**配置库**的方式统一管理所有的配置清单和模型库，即不仅存放抽象模型本身的 KCL 定义，还存放各种类型的配置清单，比如应用的运维配置、策略配置等。配置大库推荐托管在各类 VCS 系统中，以方便做配置的回滚和漂移检查。配置大库的最佳实践代号为 Konfig，仓库托管在 [Github](https://github.com/kcl-lang/konfig)。
@@ -28,3 +31,17 @@ Konfig 提供给用户开箱即用、高度抽象的配置界面，模型库最
 - **领域模型**：是不包含任何实现逻辑和抽象的模型，往往由工具转换生成，无需修改，和真正生效的 YAML 属性一一对应，底层模型需要经过进一步抽象，一般不直接被用户使用。比如，kusion_kubernetes 是 Kubernetes 场景的底层模型库。
 
 此外，核心模型内部通过前端模型和后端模型两层抽象简化前端用户的配置代码，底层模型则是通过 [KCL OpenAPI 工具](/docs/tools/cli/openapi/quick-start) 自动生成。
+
+## 文档
+
+<DocsCards>
+  <DocsCard header="Structure" href="structure">
+    <p>Konfig 仓库目录和代码结构的说明。</p>
+  </DocsCard>
+  <DocsCard header="Quick Start" href="guide">
+    <p>使用 Konfig 的快速指南。</p>
+  </DocsCard>
+  <DocsCard header="Best Practice" href="practice">
+    <p>将新模型集成到 Konfig 以及 KCL 代码编写的最佳实践指南。</p>
+  </DocsCard>
+</DocsCards>
diff --git a/...ugin-content-docs/version-0.7.0/user_docs/guides/working-with-k8s/0-overview.md b/...ugin-content-docs/version-0.7.0/user_docs/guides/working-with-k8s/0-overview.md
@@ -3,6 +3,9 @@ title: "概述"
 sidebar_position: 0
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 ## Kubernetes
 
 [Kubernetes](https://kubernetes.io/) 是一个开源项目，用于在一组机器集群上运行和管理容器化应用程序。
@@ -14,3 +17,17 @@ sidebar_position: 0
 - **动态配置策略管理**：使用现代语言（包括函数、类型、条件语句和丰富的 IDE 集成开发环境功能）来创建、编排、更改或验证应用负载的 Kubernetes API 资源，而不是使用 YAML、JSON、脚本和模板等方式。
 - **接入 Kubernetes 已有生态**：将 Kubernetes 配置清单和自定义资源类型转换为 KCL 配置和 Schema 并使用。
 - **Kubernetes 包管理**：使用 KCL 包管理工具从 Registry 下载安装和发布应用负载、容器和服务等模型。
+
+## 文档
+
+<DocsCards>
+  <DocsCard header="Adopt from Kubernetes" href="adopt-from-kubernetes">
+    <p>将 Kubernetes 清单和 CRD 转换为 KCL 代码的指南。</p>
+  </DocsCard>
+  <DocsCard header="Generate Kubernetes" href="generate-k8s-manifests">
+    <p>使用 KCL 生成 Kubernetes 清单的指南。</p>
+  </DocsCard>
+  <DocsCard header="Kubernetes Tool Integrations" href="mutate-manifests/kubectl-kcl-plugin">
+    <p>提供一些 Kubernetes 工具集成，以及使用 KCL 模块对 Kubernetes 清单进行变异或验证的指南。</p>
+  </DocsCard>
+</DocsCards>
diff --git a/...n-content-docs/version-0.7.0/user_docs/guides/working-with-konfig/1-overview.md b/...n-content-docs/version-0.7.0/user_docs/guides/working-with-konfig/1-overview.md
@@ -3,6 +3,9 @@ id: overview
 sidebar_label: 概述
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 # Konfig 概述
 
 在 KCL 中推荐通过**配置库**的方式统一管理所有的配置清单和模型库，即不仅存放抽象模型本身的 KCL 定义，还存放各种类型的配置清单，比如应用的运维配置、策略配置等。配置大库推荐托管在各类 VCS 系统中，以方便做配置的回滚和漂移检查。配置大库的最佳实践代号为 Konfig，仓库托管在 [Github](https://github.com/kcl-lang/konfig)。
@@ -28,3 +31,17 @@ Konfig 提供给用户开箱即用、高度抽象的配置界面，模型库最
 - **领域模型**：是不包含任何实现逻辑和抽象的模型，往往由工具转换生成，无需修改，和真正生效的 YAML 属性一一对应，底层模型需要经过进一步抽象，一般不直接被用户使用。比如，kusion_kubernetes 是 Kubernetes 场景的底层模型库。
 
 此外，核心模型内部通过前端模型和后端模型两层抽象简化前端用户的配置代码，底层模型则是通过 [KCL OpenAPI 工具](/docs/tools/cli/openapi/quick-start) 自动生成。
+
+## 文档
+
+<DocsCards>
+  <DocsCard header="Structure" href="structure">
+    <p>Konfig 仓库目录和代码结构的说明。</p>
+  </DocsCard>
+  <DocsCard header="Quick Start" href="guide">
+    <p>使用 Konfig 的快速指南。</p>
+  </DocsCard>
+  <DocsCard header="Best Practice" href="practice">
+    <p>将新模型集成到 Konfig 以及 KCL 代码编写的最佳实践指南。</p>
+  </DocsCard>
+</DocsCards>
diff --git a/versioned_docs/version-0.7.0/user_docs/guides/working-with-k8s/0-overview.md b/versioned_docs/version-0.7.0/user_docs/guides/working-with-k8s/0-overview.md
@@ -3,6 +3,9 @@ title: "Overview"
 sidebar_position: 0
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 ## Kubernetes
 
 [Kubernetes](https://kubernetes.io/) is an open source project for running and managing containerized applications on a cluster of machines.
@@ -14,3 +17,17 @@ sidebar_position: 0
 - **Dynamic configuration policy management**: **Create**, **orchestrate**, **mutate** or **validate** Kubernetes API resources for application workloads using the modern language including the use of **functions**, **schemas**, **conditionals** and **rich IDE features** (auto-completion, type & error checking, linting, refactoring, etc.) instead of YAML, JSON, scripts and templates.
 - **Import from existing Kubernetes ecosystem**: Convert **Kubernetes manifests** and **custom resource types** to KCL.
 - **Kubernetes package management**: **Install** or **publish** KCL modules from the [registry](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1) for application workload, container and service modules.
+
+## Docs
+
+<DocsCards>
+  <DocsCard header="Adopt from Kubernetes" href="adopt-from-kubernetes">
+    <p>Provides the guide to import Kubernetes manifests and CRDs to KCL.</p>
+  </DocsCard>
+  <DocsCard header="Generate Kubernetes" href="generate-k8s-manifests">
+    <p>Provides the guide to generate Kubernetes manifests using KCL.</p>
+  </DocsCard>
+  <DocsCard header="Kubernetes Tool Integrations" href="mutate-manifests/kubectl-kcl-plugin">
+    <p>Provides some Kubernetes tool integrations to mutate or validate Kubernetes manifests using KCL modules.</p>
+  </DocsCard>
+</DocsCards>
diff --git a/versioned_docs/version-0.7.0/user_docs/guides/working-with-konfig/1-overview.md b/versioned_docs/version-0.7.0/user_docs/guides/working-with-konfig/1-overview.md
@@ -3,6 +3,9 @@ id: overview
 sidebar_label: Overview
 ---
 
+import DocsCard from '@site/src/components/global/DocsCard';
+import DocsCards from '@site/src/components/global/DocsCards';
+
 # Konfig Overview
 
 In KCL, it is recommended to uniformly manage all configurations and model libraries in the way of **configuration library**, that is, to store not only KCL definitions of the abstract model itself, but also various types of configurations, such as application operation and maintenance configuration, policy, etc. The configuration is recommended to be hosted in various VCS systems to facilitate configuration rollback and drift check. The best practice code of the configuration repository is Konfig, and the repository is hosted in [Github](https://github.com/kcl-lang/konfig)。
@@ -28,3 +31,17 @@ Konfig provides users with an out-of-the-box and highly abstract configuration i
 - **Domain model**: It is a model that does not contain any implementation logic and abstraction. It is often generated by tool transformation and does not need to be modified. It corresponds to the real effective YAML attribute one by one. The domain model needs to be further abstracted and is generally not directly used by users. For example, `kusion_kubernetes` is the domain model library of Kubernetes scenarios.
 
 In addition, the core model simplifies the configuration code of front-end users through two layers of abstraction: the front-end model and the back-end model. The domain model is automatically generated through the [KCL OpenAPI tool](/docs/tools/cli/openapi/quick-start).
+
+## Docs
+
+<DocsCards>
+  <DocsCard header="Structure" href="structure">
+    <p>Provides the explanation of the Konfig directory and code structure.</p>
+  </DocsCard>
+  <DocsCard header="Quick Start" href="guide">
+    <p>Provides the quick guide to use Konfig.</p>
+  </DocsCard>
+  <DocsCard header="Best Practice" href="practice">
+    <p>Provides the guide of the best practices for integrating new models into the Konfig library and designing, building and writing KCL codes.</p>
+  </DocsCard>
+</DocsCards>