Restructure COMET Docs (#3007)

docs/docs/getting-started/creating-a-new-project.md → docs/docs/1-getting-started/1-creating-a-project.md

@@ -1,8 +1,22 @@
 ---
-title: Creating a new project
-sidebar_position: 2
+title: Creating a project
+sidebar_position: 1
 ---
 
+## Requirements
+
+-   [Docker](https://www.docker.com/products/docker-desktop)
+-   [nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
+
+:::tip
+
+use [Deeper Shell Integration](https://github.com/nvm-sh/nvm#deeper-shell-integration) for automatically using nvm where
+applicable
+
+:::
+
+Now, you are ready to create a new Comet DXP project.
+
 ## Setup
 
 To create a new COMET DXP application, execute the following command in your OS command line:

docs/docs/getting-started/how-to-run.md → docs/docs/1-getting-started/2-how-to-run.md

@@ -1,16 +1,16 @@
 ---
 title: How to run
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 A COMET DXP application consists of multiple processes, such as:
 
--   [an API](../overview/packages-tools#apiPackage)
--   [an admin application](../overview/packages-tools#adminPackage)
--   [a frontend site application](../overview/packages-tools#sitePackage)
+-   [an API](packages-tools#apiPackage)
+-   [an admin application](packages-tools#adminPackage)
+-   [a frontend site application](packages-tools#sitePackage)
 -   type generators
 
-We recommend using a process manager to avoid starting all these processes manually. Luckily, the steps in the [installation section](./creating-a-new-project#installation) automatically installed the package: [@vivid-planet/dev-process-manager](https://github.com/vivid-planet/dev-process-manager).
+We recommend using a process manager to avoid starting all these processes manually. Luckily, the steps in the [installation section](creating-a-project#installation) automatically installed the package: [@vivid-planet/dev-process-manager](https://github.com/vivid-planet/dev-process-manager).
 
 Executing the following command starts all processes required to run a COMET DXP application:
 

docs/docs/overview/packages-tools.md → docs/docs/1-getting-started/3-packages-tools.md

@@ -1,6 +1,6 @@
 ---
 title: Packages/Tools
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 ### COMET DXP Package Overview

docs/docs/crud-generator/api-generator.md → docs/docs/1-getting-started/4-crud-generator/1-api-generator.md

@@ -138,8 +138,8 @@ A `status` field lets you filter items by status in the list query.
 
 ### scope
 
-The API generator treats a `scope` as a [COMET content scope](/docs/content-scope/). A `scope` arg is added to the list
-and create operations, ensuring the [scope check](/docs/user-permissions/access-control/#scope-check) can be made.
+The API generator treats a `scope` as a [COMET content scope](/docs/core-concepts/content-scope/). A `scope` arg is added to the list
+and create operations, ensuring the [scope check](/docs/core-concepts/user-permissions/access-control/#scope-check) can be made.
 
 If no `scope` field is present, the scope check is skipped for all operations.
 

docs/docs/crud-generator/index.md → docs/docs/1-getting-started/4-crud-generator/index.md

@@ -1,6 +1,6 @@
 ---
 title: CRUD Generator
-sidebar_position: 15
+sidebar_position: 4
 ---
 
 To accelerate the development of a feature, the CRUD Generator can be used to generate the usual CRUD operations (in GraphQL) for the feature. The CRUD Generator is available for the API and for the Admin. The CRUD Generator can be used in two ways:

docs/docs/getting-started/index.md → docs/docs/1-getting-started/index.md

@@ -1,6 +1,5 @@
 ---
 title: Getting Started
-sidebar_position: 2
 ---
 
 In this section, you will learn everything you need to create, install and run your application.

docs/docs/content-scope/content-website.md → docs/docs/2-core-concepts/1-content-scope/1-content-website.md

@@ -1,6 +1,5 @@
 ---
 title: Content websites
-sidebar_position: 1
 ---
 
 In a content website, the content scope can be used to separate multiple areas of content, such as different websites (domains) or languages. Each area stores its content independently of the others.
@@ -53,4 +52,4 @@ You can then use `useContentScope()` to access the currently selected scope, whi
 
 COMET's user permission feature will automatically validate `scope` arguments of GraphQL operations and check if a user has access to the entity's scope. The column must be named `scope` for this to work.
 
-For nested entities or operations without a `scope` argument please refer to [Evaluate Content Scopes](/docs/content-scope/evaluate-content-scopes) which describes how to decorate the resolvers/controllers properly.
+For nested entities or operations without a `scope` argument please refer to [Evaluate Content Scopes](evaluate-content-scopes) which describes how to decorate the resolvers/controllers properly.

docs/docs/content-scope/data-driven-application.md → docs/docs/2-core-concepts/1-content-scope/2-data-driven-application.md

@@ -1,6 +1,5 @@
 ---
 title: Data-driven applications
-sidebar_position: 2
 ---
 
 You can also use the scope in data-driven applications. However, the usage is quite different compared to content websites:
@@ -44,4 +43,4 @@ const variables = {
 
 ### API: User permissions
 
-In data-driven applications, the scope system is primarily used for controlling permissions. Please refer to [Evaluate Content Scopes](/docs/content-scope/evaluate-content-scopes) which is heavily used in data-driven applications.
+In data-driven applications, the scope system is primarily used for controlling permissions. Please refer to [Evaluate Content Scopes](evaluate-content-scopes) which is heavily used in data-driven applications.

docs/docs/content-scope/evaluate-content-scopes.md → docs/docs/2-core-concepts/1-content-scope/3-evaluate-content-scopes.md

@@ -1,6 +1,5 @@
 ---
 title: Evaluate Content Scopes
-sidebar_position: 3
 ---
 
 To evaluate the scope there a two technically very distinctive ways depending on the type of operation:

docs/docs/content-scope/index.md → docs/docs/2-core-concepts/1-content-scope/index.md

@@ -1,6 +1,6 @@
 ---
 title: Content Scope
-sidebar_position: 6
+sidebar_position: 1
 ---
 
 COMET DXP can be used to create both, content websites and data-driven applications. The usage of the content scope differs considerably between these two use cases.

docs/docs/blocks/your-first-block.mdx → docs/docs/2-core-concepts/2-blocks/1-your-first-block.mdx

@@ -1,6 +1,5 @@
 ---
 title: Your First Block
-sidebar_position: 1
 ---
 
 import CodeBlock from "@theme/CodeBlock";
@@ -128,7 +127,7 @@ The complete code for our Headline API block (including all necessary imports) c
     inputToData,
 } from "@comet/blocks-api";
 import { RichTextBlock } from "@src/common/blocks/rich-text.block";
-import { IsEnum, IsOptional, IsString, ValidateNested } from "class-validator";\n
+import { IsEnum, IsOptional, IsString } from "class-validator";\n
 export enum HeadlineLevel {
     HeaderOne = "header-one",
     HeaderTwo = "header-two",

docs/docs/blocks/block-best-practices.mdx → docs/docs/2-core-concepts/2-blocks/2-block-best-practices.mdx

@@ -1,6 +1,5 @@
 ---
 title: Best practices
-sidebar_position: 2
 ---
 
 This page covers best practices on how to design pleasant-to-use blocks.

docs/docs/blocks/block-naming-strategies.md → docs/docs/2-core-concepts/2-blocks/3-block-naming-strategies.md

@@ -1,6 +1,5 @@
 ---
 title: Block Naming Strategies
-sidebar_position: 2
 ---
 
 API &#8594 Kebab Case<br />

docs/docs/blocks/block-factories.mdx → docs/docs/2-core-concepts/2-blocks/4-factories.mdx

@@ -1,6 +1,5 @@
 ---
 title: Factories
-sidebar_position: 3
 ---
 
 # Block factories

docs/docs/blocks/block-migrations.mdx → docs/docs/2-core-concepts/2-blocks/5-migrations.mdx

@@ -1,6 +1,5 @@
 ---
 title: Migrations
-sidebar_position: 4
 ---
 
 # Block migrations

docs/docs/blocks/composition.mdx → docs/docs/2-core-concepts/2-blocks/6-composition.mdx

@@ -1,6 +1,5 @@
 ---
 title: Composition
-sidebar_position: 5
 ---
 
 # Composing blocks
@@ -102,7 +101,7 @@ This approach is based on the principle of [composition over inheritance](https:
 
 # Why don't create a factory instead?
 
-When considering the example above, the question might arise as to why don't create a [block factory](/docs/blocks/block-factories) instead, where the background option can be optionally activated:
+When considering the example above, the question might arise as to why don't create a [block factory](factories) instead, where the background option can be optionally activated:
 
 ```ts
 const HeadlineBlock = createHeadlineBlock({

docs/docs/blocks/blocks-in-forms.mdx → docs/docs/2-core-concepts/2-blocks/7-blocks-in-forms.mdx

@@ -1,6 +1,5 @@
 ---
 title: Blocks in forms
-sidebar_position: 6
 ---
 
 # Using blocks in forms
@@ -27,7 +26,7 @@ The following steps are necessary to add the `image` field to the form:
 :::info
 
 The block transitions between the various states when being used in a form.
-The states and transitions can be viewed [here](/docs/blocks/lifecycle#the-block-in-the-admin).
+The states and transitions can be viewed [here](/docs/core-concepts/blocks/lifecycle#the-block-in-the-admin).
 
 :::
 

docs/docs/blocks/lifecycle.mdx → docs/docs/2-core-concepts/2-blocks/8-lifecycle.mdx

@@ -1,6 +1,5 @@
 ---
 title: Lifecycle
-sidebar_position: 7
 ---
 
 # Deep dive: A block's lifecycle

docs/docs/blocks/index.md → docs/docs/2-core-concepts/2-blocks/index.md

@@ -1,4 +1,4 @@
 ---
 title: Blocks
-sidebar_position: 4
+sidebar_position: 2
 ---

docs/docs/documents/index.md → docs/docs/2-core-concepts/3-documents/index.md

@@ -1,4 +1,4 @@
 ---
 title: Documents
-sidebar_position: 4
+sidebar_position: 3
 ---

docs/docs/structured-data/index.md → docs/docs/2-core-concepts/4-structured-data/index.md

@@ -1,6 +1,6 @@
 ---
 title: Structured Data
-sidebar_position: 7
+sidebar_position: 4
 ---
 
 Structured data is application-specific data that is managed by the customer. This data is displayed in tables; in order to edit a contribution, a form is used. These tables and forms are created with the help of the [comet-admin](https://github.com/vivid-planet/comet-admin) package.

docs/docs/user-permissions/setup.md → docs/docs/2-core-concepts/5-user-permissions/1-setup.md

@@ -1,6 +1,5 @@
 ---
 title: Setup
-sidebar_position: 1
 ---
 
 ## API

docs/docs/user-permissions/access-control.md → docs/docs/2-core-concepts/5-user-permissions/2-access-control.md

@@ -1,6 +1,5 @@
 ---
 title: Access Control in the API
-sidebar_position: 2
 ---
 
 :::note
@@ -37,7 +36,7 @@ Future version will support a dot-like notation (e.g. `news` will subsume `news.
 
 ## Scope check
 
-The scope check needs to know which scope is used for the current operation. This is described in [Evaluate Content Scopes documentation](/docs/content-scope/evaluate-content-scopes).
+The scope check needs to know which scope is used for the current operation. This is described in [Evaluate Content Scopes documentation](/docs/core-concepts/content-scope/evaluate-content-scopes).
 
 :::caution
 COMET DXP validates the data relevant for the operation, but cannot check if the validated data is finally used. You are responsible for applying the validated data in your operations.

docs/docs/user-permissions/admin.md → docs/docs/2-core-concepts/5-user-permissions/3-admin.md

@@ -1,6 +1,5 @@
 ---
 title: Permissions in Admin
-sidebar_position: 3
 ---
 
 :::caution

docs/docs/user-permissions/index.md → docs/docs/2-core-concepts/5-user-permissions/index.md

@@ -1,6 +1,6 @@
 ---
 title: User Permissions
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 While COMET DXP does not provide authentication, it handles authorization by providing a User Permissions system.
@@ -19,7 +19,7 @@ COMET DXP checks authentication in two dimensions:
 
 **Permissions** are used for access control to specific resolvers or controllers.
 
-**Content Scopes** (also referred to as scopes) are used to control which data is allowed to be handled (see [documentation about content scopes](/docs/content-scope)).
+**Content Scopes** (also referred to as scopes) are used to control which data is allowed to be handled (see [documentation about content scopes](/docs/core-concepts/content-scope)).
 
 Users in COMET DXP possess permissions and scopes. Every operation is assigned to one or more permissions and handles data that is bound to a scope. The system then tries to match if the requested permissions and scopes are covered by the user's permissions and scopes.
 

docs/docs/internationalization/index.mdx → docs/docs/2-core-concepts/6-internationalization/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Internationalization (i18n)
-sidebar_position: 10
+sidebar_position: 6
 ---
 
 The following page describes core translation concepts. We use [FormatJS](https://formatjs.io/) for translations. These design principles were considered:

docs/docs/dependencies/index.md → docs/docs/2-core-concepts/7-dependencies/index.md

@@ -1,6 +1,6 @@
 ---
 title: Block Index / Dependencies
-sidebar_position: 15
+sidebar_position: 7
 ---
 
 # Block Index / Dependencies
@@ -62,7 +62,7 @@ You must recreate the block index views after
 -   executing database migrations
 -   executing the fixtures (because they drop the whole database and recreate it)
 
-You can automate this process by following the steps in the [migration guide](../migration/migration-from-v5-to-v6/#block-index).
+You can automate this process by following the steps in the [migration guide](/docs/migration-guide/migration-from-v5-to-v6/#block-index).
 For new projects, it should already be automated.
 
 ### Displaying dependencies in the admin interface

docs/docs/core-concepts/index.md → docs/docs/2-core-concepts/index.md

@@ -1,6 +1,5 @@
 ---
 title: Core Concepts
-sidebar_position: 3
 ---
 
 On this page, you'll learn the core concepts of COMET DXP. These concepts represent the essential building blocks when developing COMET DXP applications.

docs/docs/page-tree/index.md → docs/docs/3-features-modules/1-page-tree/index.md

@@ -1,6 +1,5 @@
 ---
 title: Page Tree
-sidebar_position: 5
 id: PageTree
 ---
 

docs/docs/preview/index.md → docs/docs/3-features-modules/2-preview/index.md

@@ -1,6 +1,5 @@
 ---
 title: Preview
-sidebar_position: 8
 ---
 
 COMET DXP comes with a built-in preview system. There are two different types of preview: the web preview and the block preview.
@@ -75,9 +74,9 @@ So what are the advantages of the web preview? The web preview is always live, w
 
 But what steps need to be taken to make the block preview work as described?
 
-If you [followed the guide to create your first block](../blocks/your-first-block), it already works!
+If you [followed the guide to create your first block](/docs/core-concepts/blocks/your-first-block), it already works!
 
-In section "[Part three - Adding the block to the site](../blocks/your-first-block#partThree)," the function `withPreview(...)` is wrapped around the block-specific code. So to get the preview working with all its features, simply wrap the `withPreview()` function over each block and give it an expressive label!
+In section "[Part three - Adding the block to the site](/docs/core-concepts/blocks/your-first-block#partThree)," the function `withPreview(...)` is wrapped around the block-specific code. So to get the preview working with all its features, simply wrap the `withPreview()` function over each block and give it an expressive label!
 
 ```tsx title="HeadlineBlock.tsx"
 export const HeadlineBlock = withPreview(
@@ -113,6 +112,6 @@ import { Preview } from "@comet/admin-icons";
 
 :::warning
 
-Additional steps are required to use the preview with [structured data](../structured-data), which will be covered by future versions of the documentation.
+Additional steps are required to use the preview with [structured data](../../core-concepts/structured-data), which will be covered by future versions of the documentation.
 
 :::

docs/docs/asset-management/index.md → docs/docs/3-features-modules/3-asset-management/index.md

@@ -1,6 +1,5 @@
 ---
 title: Asset Management (DAM)
-sidebar_position: 9
 ---
 
 COMET DXP has a built-in digital asset management interface (DAM). The DAM's purpose is the management of all files used on a website. That comprises media files (images, videos, audios), PDFs, zip-Files, and documents.

docs/docs/console-commands/index.md → docs/docs/3-features-modules/5-console-commands/index.md

@@ -1,6 +1,5 @@
 ---
 title: Console Commands
-sidebar_position: 13
 ---
 
 We use [NestJS Console](https://github.com/Pop-Code/nestjs-console) to create console commands. Console commands can be used locally or deployed.

docs/docs/cron-jobs/index.md → docs/docs/3-features-modules/6-cron-jobs/index.md

@@ -1,9 +1,8 @@
 ---
 title: Cron Jobs
-sidebar_position: 14
 ---
 
-Cron Jobs are defined as [console commands](../console-commands/index.md). The preferred way to run them is as a [Kubernetes CronJob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/). Advantages of using Kubernetes Cron Jobs:
+Cron Jobs are defined as [console commands](../console-commands). The preferred way to run them is as a [Kubernetes CronJob](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/). Advantages of using Kubernetes Cron Jobs:
 
 -   You can run multiple instances of the API in parallel without additional configuration for Cron Jobs.
 -   Different resources can be used for Cron Jobs and the API.

docs/docs/logging/access-logging.md → docs/docs/3-features-modules/7-access-logging/index.md

@@ -1,6 +1,5 @@
 ---
 title: Access Logging
-sidebar_position: 2
 ---
 
 There is an option to enable global access logging, where request data is logged in the standard output. The following information is logged:

docs/docs/sentry/index.md → docs/docs/3-features-modules/8-sentry/index.md

@@ -1,6 +1,5 @@
 ---
 title: Sentry Module
-sidebar_position: 16
 ---
 
 SentryModule is a NestJS module that integrates Sentry for error tracking. To use the module, import it into your application's root module and call the `forRootAsync` method. For more detailed configurations and advanced usage please visit [Sentry](https://docs.sentry.io/platforms/javascript/guides/node/configuration/).

docs/docs/3-features-modules/index.md

@@ -0,0 +1,3 @@
+---
+title: Features / Modules
+---