docs: navigation improvements (#1306)

* docs: update navigation experience

* docs: fix reference intro cards descriptions

apps/docs/api-reference/intro.mdx

@@ -0,0 +1,23 @@
+---
+title: "Introduction"
+sidebarTitle: "Introduction"
+---
+
+Codemod Workflow Engine allows you to manage different migration tasks at various levels.
+
+Below, you can find the different operations supported by the Workflow Engine API:
+
+<CardGroup cols={2}>
+  <Card title="Git Operations" icon="git" href="/api-reference/git">
+    Perform repository operations such as clone, branch, commit, and push
+  </Card>
+  <Card title="File Operations" icon="file" href="/api-reference/file">
+    Perform file and directory operations such as iterating, copying, moving, and removing
+  </Card>
+  <Card title="Code Transformation" icon="scribble" href="/api-reference/transformation">
+    Perform code transformations with engines such as jscodeshift, ts-morph, and ast-grep
+  </Card>
+  <Card title="Command-Line Operations" icon="terminal" href="/api-reference/command">
+    Execute CLI commands over your working directories
+  </Card>
+</CardGroup>

apps/docs/guides/building-codemods/build-package.mdx → apps/docs/building-codemods/build-package.mdx

@@ -7,13 +7,13 @@ You can build a codemod package using three different ways:
 - Build with `codemod learn`
 - Scaffold a codemod package
 
-By building a codemod with Codemod Studio or with `codemod learn`, your codemod package will automatically have the recommended [package structure](/guides/building-codemods/package-requirements).
+By building a codemod with Codemod Studio or with `codemod learn`, your codemod package will automatically have the recommended [package structure](/building-codemods/package-requirements).
 
 If you build a codemod from scratch or a previously built codemod, you will have to scaffold a valid codemod package using Codemod CLI.
 
 ## Building with Codemod Studio
 
-To learn how to build codemods with Codemod Studio, please refer to the [detailed Codemod Studio usage guide](/building-codemods/codemod-studio#building-codemods-with-codemod-studio).
+To learn how to build codemods with Codemod Studio, please refer to the [detailed Codemod Studio usage guide](/codemod-studio#building-codemods-with-codemod-studio).
 
 ## Building with `codemod learn`
 
@@ -30,7 +30,7 @@ You can use `codemod learn` to build a codemod from the latest diff made in your
         Codemod Studio will automatically open, with pre-populated data, and begin building your codemod. Allow Codemod Studio to finish generating your codemod.
     </Step>
     <Step title="Export/publish the generated codemod">
-        After Codemod Studio builds your codemod, you can easily [export and run your codemod](/building-codemods/codemod-studio#running-codemods) over your local project.
+        After Codemod Studio builds your codemod, you can easily [export and run your codemod](/codemod-studio#running-codemods) over your local project.
     </Step>
 </Steps>
 
@@ -44,7 +44,7 @@ To scaffold a new codemod package, you should:
 
 <Steps>
     <Step title="Verify codemod engine compatibility">
-        Verify that the existing codemod is built by one of the [supported codemod engines](/guides/building-codemods/package-requirements#supported-codemod-engines).
+        Verify that the existing codemod is built by one of the [supported codemod engines](/building-codemods/package-requirements#supported-codemod-engines).
     </Step>
     <Step title="Initialize codemod package">
         Initialize a Codemod-compatible package by running:
@@ -61,12 +61,12 @@ To scaffold a new codemod package, you should:
         </Card>
     </Step>
     <Step title="Update package configuration file">
-        Add information about your codemod to the `.codemodrc.json` configuration file. Refer to [`.codemodrc.json` reference here](/guides/building-codemods/package-requirements#codemodrc-json-reference).
+        Add information about your codemod to the `.codemodrc.json` configuration file. Refer to [`.codemodrc.json` reference here](/building-codemods/package-requirements#codemodrc-json-reference).
     </Step>
 </Steps>
 
 ## Next steps
 
-<Card title="Publishing your codemod ->" icon="share-nodes" href="/guides/sharing/publishing-codemods">
+<Card title="Publishing your codemod ->" icon="share-nodes" href="/sharing/publishing-codemods">
 Get started with publishing your codemod to Codemod Registry.
 </Card>

apps/docs/guides/building-codemods/package-requirements.mdx → apps/docs/building-codemods/package-requirements.mdx

@@ -317,6 +317,6 @@ Below, you can find the required codemod package structure for each codemod engi
 
 ## Next steps
 
-<Card title="Building a codemod package ->" icon="wrench" href="/guides/building-codemods/build-package">
+<Card title="Building a codemod package ->" icon="wrench" href="/building-codemods/build-package">
 Get started with building a codemod package.
 </Card>

apps/docs/codemod-registry/introduction.mdx

@@ -18,10 +18,10 @@ icon: 'book-open-cover'
 
 Codemod Registry is the single-stop registry for codemods and code automation recipes that are built on top of tried-and-true engines such as Meta's jscodeshift, ts-morph, and Uber's piranha.
 
-After [publishing codemods](/guides/sharing/publishing-codemods) to the registry, they will automatically integrate into Codemod platform and all developers who have Codemod [CLI](/deploying-codemods/cli) or [IDE extension](/deploying-codemods/vsce) can then discover, share, and run those codemods with a single click. This also eliminates the need for installing additional packages for each framework they want to upgrade.
+After [publishing codemods](/sharing/publishing-codemods) to the registry, they will automatically integrate into Codemod platform and all developers who have Codemod [CLI](/deploying-codemods/cli) or [IDE extension](/deploying-codemods/vsce) can then discover, share, and run those codemods with a single click. This also eliminates the need for installing additional packages for each framework they want to upgrade.
 
 ## Learn more
 
-<Card title="Publishing codemods ->" icon="share-nodes" href="/guides/sharing/publishing-codemods">
+<Card title="Publishing codemods ->" icon="share-nodes" href="/sharing/publishing-codemods">
   Learn how to publish your codemods to Codemod Registry.
 </Card>

apps/docs/deploying-codemods/cli.mdx

@@ -33,7 +33,7 @@ yarn global add codemod
 
 ### `codemod learn`
 
-The `learn` command uses the diff of the latest edited file to automatically build a codemod using [Codemod Studio](/building-codemods/codemod-studio/).
+The `learn` command uses the diff of the latest edited file to automatically build a codemod using [Codemod Studio](/codemod-studio/).
 
 After running this command, if any git diff exists, the Codemod Engine will use the diff as before/after snippets in Codemod Studio.
 
@@ -85,7 +85,7 @@ codemod init
 
 Can be used to publish a codemod to Codemod Registry.
 
-Publishing codemods requires [logging in](#other-commands) to Codemod platform and having a codemod that is [compatible with Codemod Registry](/guides/building-codemods/package-requirements).
+Publishing codemods requires [logging in](#other-commands) to Codemod platform and having a codemod that is [compatible with Codemod Registry](/building-codemods/package-requirements).
 
 To do so, use the `publish` command inside the codemod package directory:
 
@@ -163,9 +163,9 @@ Codemod CLI allows you to run codemods:
     codemod -s [path]
     ```
 
-    If the target source includes a [codemod package](/guides/building-codemods/package-requirements), the codemod will run automatically.
+    If the target source includes a [codemod package](/building-codemods/package-requirements), the codemod will run automatically.
 
-    If the codemod is an <Tooltip tip="E.g. a single transform.js file of a jscodeshift codemod">atomic transform file</Tooltip>, Codemod CLI will ask you to specify a [codemod engine](/guides/building-codemods/package-requirements#supported-codemod-engines) to run the codemod.
+    If the codemod is an <Tooltip tip="E.g. a single transform.js file of a jscodeshift codemod">atomic transform file</Tooltip>, Codemod CLI will ask you to specify a [codemod engine](/building-codemods/package-requirements#supported-codemod-engines) to run the codemod.
   </Tab>
 </Tabs>
 

apps/docs/guides/introduction.mdx

@@ -2,33 +2,6 @@
 title: 'Introduction'
 ---
 
-## Building Codemods
-
-<CardGroup cols={2}>
-
-<Card
-  title="Building a codemod package"
-  href="/guides/building-codemods/package-requirements"
-></Card>
-
-<Card
-  title="Building Codemod2.0"
-  href="/guides/building-codemods/codemod2"
-></Card>
-
-</CardGroup>
-
-## Sharing Codemods
-
-<CardGroup cols={2}>
-
-<Card
-  title="Publishing to Codemod Registry"
-  href="/guides/sharing/publishing-codemods"
-></Card>
-
-</CardGroup>
-
 ## Migrations
 
 <CardGroup cols={2}>

apps/docs/mint.json

@@ -57,6 +57,7 @@
           "group": "Reference",
           "icon": "code",
           "pages": [
+            "api-reference/intro",
             {
               "group": "Git operations",
               "pages": [
@@ -101,7 +102,7 @@
     },
     {
       "group": "Codemod Studio",
-      "pages": ["building-codemods/codemod-studio"]
+      "pages": ["codemod-studio"]
     },
     {
       "group": "Codemod Registry",
@@ -111,6 +112,28 @@
       "group": "VS Code Extension",
       "pages": ["deploying-codemods/vsce"]
     },
+    {
+      "group": "Guides",
+      "pages": [
+        {
+          "group": "Building codemods",
+          "pages": [
+            {
+              "group": "Codemod packages",
+              "pages": [
+                "building-codemods/package-requirements",
+                "building-codemods/build-package"
+              ]
+            },
+            "building-codemods/codemod2"
+          ]
+        },
+        {
+          "group": "Sharing codemods",
+          "pages": ["sharing/publishing-codemods"]
+        }
+      ]
+    },
     {
       "group": "Quick Links",
       "pages": [
@@ -127,23 +150,6 @@
       "group": "Guides & Examples",
       "pages": ["guides/introduction"]
     },
-    {
-      "group": "Building codemods",
-      "pages": [
-        {
-          "group": "Codemod packages",
-          "pages": [
-            "guides/building-codemods/package-requirements",
-            "guides/building-codemods/build-package"
-          ]
-        },
-        "guides/building-codemods/codemod2"
-      ]
-    },
-    {
-      "group": "Sharing codemods",
-      "pages": ["guides/sharing/publishing-codemods"]
-    },
     {
       "group": "Migrations",
       "pages": [

apps/docs/platform/build.mdx

@@ -7,12 +7,12 @@ Codemod platform allows you to build a wide variety of codemods and easily distr
 
 You can build codemods using three different ways:
 
-- [Build with Codemod Studio](/building-codemods/codemod-studio#building-codemods-with-codemod-studio)
-- [Build with codemod learn](/guides/building-codemods/build-package#building-with-codemod-learn)
-- [Scaffold a new codemod package](/guides/building-codemods/build-package#scaffolding-a-codemod-package)
+- [Build with Codemod Studio](/codemod-studio#building-codemods-with-codemod-studio)
+- [Build with codemod learn](/building-codemods/build-package#building-with-codemod-learn)
+- [Scaffold a new codemod package](/building-codemods/build-package#scaffolding-a-codemod-package)
 
 ## Getting started
 
-<Card title="Building codemods ->" icon="screwdriver-wrench" href="/guides/building-codemods/package-requirements">
+<Card title="Building codemods ->" icon="screwdriver-wrench" href="/building-codemods/package-requirements">
   Learn how to build codemod packages.
 </Card>

apps/docs/platform/run.mdx

@@ -6,7 +6,7 @@ sidebarTitle: "Run"
 ## Benefits and features
 
 Running codemods with Codemod platform brings many benefits such as:
-- advanced codemod [configuration](/guides/building-codemods/package-requirements#codemodrc-json-reference) (pre/post-run commands, arguments, formatting, daisy-chaining, multi-threading, dry-running, and more)
+- advanced codemod [configuration](/building-codemods/package-requirements#codemodrc-json-reference) (pre/post-run commands, arguments, formatting, daisy-chaining, multi-threading, dry-running, and more)
 - easily running codemods from different entry points, such as [CLI](/deploying-codemods/cli) and [IDE extension](/deploying-codemods/vsce), based on user preference.
 
 ## Getting started
@@ -21,6 +21,6 @@ Codemod platform allows you to run codemods using different ways:
   Use Codemod VS Code extension to run codemod packages.
   </Card>
 </CardGroup>
-  <Card title="Codemod Studio" icon="square-3" href="/building-codemods/codemod-studio#running-codemods">
+  <Card title="Codemod Studio" icon="square-3" href="/codemod-studio#running-codemods">
   Use Codemod Studio to run your own codemod packages.
   </Card>

apps/docs/guides/sharing/publishing-codemods.mdx → apps/docs/sharing/publishing-codemods.mdx

@@ -18,11 +18,11 @@ Publishing codemods to the registry is especially useful for framework/library b
 
 ### Option 1: Publishing a Codemod-compatible package (recommended)
 
-Creating and publishing a [Codemod-compatible package](/guides/building-codemods/package-requirements) brings an enhanced codemod running experience.
+Creating and publishing a [Codemod-compatible package](/building-codemods/package-requirements) brings an enhanced codemod running experience.
 
 <Steps>
     <Step title="Build a codemod package">
-        To publish a codemod to Codemod Registry, the codemod package needs to be compatible with Codemod platform. To learn how to build Codemod-compatible codemods, please refer to the [building codemods guide](/guides/building-codemods/build-package).
+        To publish a codemod to Codemod Registry, the codemod package needs to be compatible with Codemod platform. To learn how to build Codemod-compatible codemods, please refer to the [building codemods guide](/building-codemods/build-package).
     </Step>
     <Step title="Login to Codemod platform">
         If you are not already logged in, login to Codemod platform using:
@@ -51,7 +51,7 @@ Creating and publishing a [Codemod-compatible package](/guides/building-codemods
         Publish the codemod from source path:
 
         <Note>
-        To generate a [Codemod-compatible package](/guides/building-codemods/package-requirements), Codemod CLI will ask you a few questions about your codemod to generate the [`codemodrc.json` configuration file](/guides/building-codemods/package-requirements#codemodrc-json-reference) automatically for you.
+        To generate a [Codemod-compatible package](/building-codemods/package-requirements), Codemod CLI will ask you a few questions about your codemod to generate the [`codemodrc.json` configuration file](/building-codemods/package-requirements#codemodrc-json-reference) automatically for you.
         </Note>
 
         <Tip>If you want to use ESM-specific features like top-level `await` or `import.meta`, you can rename it to use `.mjs` or `.mts` extension or specify `--esm` flag to treat the source file as ESM package explicitly.</Tip>