Update Terraform reference category page locations (#48148)

Backports #47955

As with #47797, Docusaurus expects category index pages to be
within--and named after--their parent directories. (Docusaurus also
accepts the names `README` and `index` for category pages, but we are
not using this convention.) This change applies this standard to our
Terraform provider reference docs.

- Update paths in the generator configuration. Assume that each category
  index page is in the same subdirectory as its contents.
- Update paths in the `lint.yaml` workflow.
- Fix internal links.

.github/workflows/lint.yaml

@@ -63,7 +63,6 @@ jobs:
               - 'docs/pages/admin-guides/**'
               - 'docs/pages/enroll-resources/**'
               - 'docs/pages/reference/operator-resources/**'
-              - 'docs/pages/reference/terraform-provider.mdx'
               - 'docs/pages/reference/terraform-provider/**'
               - 'examples/chart/teleport-cluster/charts/teleport-operator/operator-crds'
 

docs/pages/admin-guides/infrastructure-as-code/managing-resources/import-existing-resources.mdx

@@ -83,5 +83,6 @@ cluster configuration matches your expectations.
 - Follow [the user and role IaC guide](user-and-role.mdx) to use the Terraform
   Provider to create Teleport users and grant them roles.
 - Explore the full list of supported [Terraform provider
-  resources](../../../reference/terraform-provider.mdx).
-- See [the list of supported Teleport Terraform setups](../terraform-provider/terraform-provider.mdx):
+  resources](../../../reference/terraform-provider/terraform-provider.mdx).
+- See [the list of supported Teleport Terraform
+  setups](../terraform-provider/terraform-provider.mdx):

docs/pages/admin-guides/infrastructure-as-code/terraform-provider/dedicated-server.mdx

@@ -159,7 +159,7 @@ $ tctl get role/terraform-test
 ## Next steps
 
 - Explore the
-  [Terraform provider resource reference](../../../reference/terraform-provider.mdx)
+  [Terraform provider resource reference](../../../reference/terraform-provider/terraform-provider.mdx)
   to discover what can be configured with the Teleport Terraform provider.
 - Read the [tbot configuration reference](../../../reference/machine-id/configuration.mdx) to explore
   all the available `tbot` configuration options.

docs/pages/admin-guides/infrastructure-as-code/terraform-provider/local.mdx

@@ -159,8 +159,10 @@ Do not forget to obtain new temporary credentials every hour by re-running `eval
 - Follow [the user and role IaC guide](../managing-resources/user-and-role.mdx) to use the Terraform
   Provider to create Teleport users and grant them roles.
 - Consult the list of Terraform-supported
-  resources [in the Terraform reference](../../../reference/terraform-provider.mdx).
-- Once you have working Terraform code that configures your Teleport cluster, you might want to run it in the CI or
-  from a bastion instead of running it locally. To do this, please follow the dedicated guides:
+  resources [in the Terraform
+  reference](../../../reference/terraform-provider/terraform-provider.mdx).
+- Once you have working Terraform code that configures your Teleport cluster,
+  you might want to run it in the CI or from a bastion instead of running it
+  locally. To do this, please follow the dedicated guides:
   - [Run the Terraform Provider in CI or cloud VMs](./ci-or-cloud.mdx)
   - [Run the Terraform Provider on a dedicated server](./dedicated-server.mdx)

docs/pages/admin-guides/infrastructure-as-code/terraform-provider/long-lived-credentials.mdx

@@ -199,6 +199,9 @@ To apply the configuration:
 
 ## Next steps
 
-- Explore the full list of supported [Terraform provider resources](../../../reference/terraform-provider.mdx).
-- Learn [how to manage users and roles with IaC](../managing-resources/user-and-role.mdx)
-- Read more about [impersonation](../../access-controls/guides/impersonation.mdx).
+- Explore the full list of supported [Terraform provider
+  resources](../../../reference/terraform-provider/terraform-provider.mdx).
+- Learn [how to manage users and roles with
+  IaC](../managing-resources/user-and-role.mdx)
+- Read more about
+  [impersonation](../../access-controls/guides/impersonation.mdx).

docs/pages/admin-guides/infrastructure-as-code/terraform-provider/spacelift.mdx

@@ -260,8 +260,8 @@ $ tctl get users/terraform-test
 
 - Now that you know how to manage Teleport configuration resources with
   Terraform and Spacelift, read the [Terraform resource
-  reference](../../../reference/terraform-provider.mdx) so you can flesh out your
-  configuration.
+  reference](../../../reference/terraform-provider/terraform-provider.mdx) so
+  you can flesh out your configuration.
 - To find out more about Spacelift's OIDC implementation, which Machine ID uses
   to authenticate to your Teleport cluster, read [the Spacelift
   documentation](https://docs.spacelift.io/integrations/cloud-providers/oidc/).

docs/pages/admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx

@@ -28,8 +28,8 @@ is executed. You must pick the correct guide for your setup:
 
 Once you have a functional Teleport Terraform provider, you will want to configure your resources with it.
 
-You can find the list of supported resources and their fields is
-available [in the Terraform reference](../../../reference/terraform-provider.mdx).
+The list of supported resources and their fields is available [in the Terraform
+reference](../../../reference/terraform-provider/terraform-provider.mdx).
 
 Some resources have their dedicated Infrastructure-as-Code (IaC) step-by step guides such as:
 - [Managing Users And Roles With IaC](../managing-resources/user-and-role.mdx)

docs/pages/admin-guides/infrastructure-as-code/terraform-starter/enroll-resources.mdx

@@ -623,7 +623,7 @@ edit your Terraform module to:
 1. **Change the userdata script** to enable additional Agent services additional
    infrastructure resources for your Agents to proxy.
 1. **Deploy dynamic resources:** Consult the [Terraform provider
-   reference](../../../reference/terraform-provider.mdx) for Terraform resources
-   that you can apply in order to enroll dynamic resources in your
-   infrastructure.
+   reference](../../../reference/terraform-provider/terraform-provider.mdx) for
+   Terraform resources that you can apply in order to enroll dynamic resources
+   in your infrastructure.
 

docs/pages/admin-guides/infrastructure-as-code/terraform-starter/rbac.mdx

@@ -563,4 +563,4 @@ troubleshoot the single sign-on provider.
 
 Now that you have configured RBAC in your Terraform demo cluster, fine-tune your
 setup by reading the comprehensive [Terraform provider
-reference](../../../reference/terraform-provider.mdx).
+reference](../../../reference/terraform-provider/terraform-provider.mdx).

docs/pages/reference/terraform-provider/data-sources/data-sources.mdx

@@ -0,0 +1,35 @@
+---
+title: "Terraform data-sources index"
+description: "Index of all the data-sources supported by the Teleport Terraform Provider"
+---
+
+{/*Auto-generated file. Do not edit.*/}
+{/*To regenerate, navigate to integrations/terraform and run `make docs`.*/}
+
+{/*
+    This file will be renamed data-sources.mdx during build time.
+    The template name is reserved by tfplugindocs so we suffix with -index.
+*/}
+
+The Teleport Terraform provider supports the following data-sources:
+
+  - [`teleport_access_list`](./access_list.mdx)
+  - [`teleport_access_monitoring_rule`](./access_monitoring_rule.mdx)
+  - [`teleport_app`](./app.mdx)
+  - [`teleport_auth_preference`](./auth_preference.mdx)
+  - [`teleport_cluster_maintenance_config`](./cluster_maintenance_config.mdx)
+  - [`teleport_cluster_networking_config`](./cluster_networking_config.mdx)
+  - [`teleport_database`](./database.mdx)
+  - [`teleport_github_connector`](./github_connector.mdx)
+  - [`teleport_installer`](./installer.mdx)
+  - [`teleport_login_rule`](./login_rule.mdx)
+  - [`teleport_oidc_connector`](./oidc_connector.mdx)
+  - [`teleport_okta_import_rule`](./okta_import_rule.mdx)
+  - [`teleport_provision_token`](./provision_token.mdx)
+  - [`teleport_role`](./role.mdx)
+  - [`teleport_saml_connector`](./saml_connector.mdx)
+  - [`teleport_session_recording_config`](./session_recording_config.mdx)
+  - [`teleport_static_host_user`](./static_host_user.mdx)
+  - [`teleport_trusted_cluster`](./trusted_cluster.mdx)
+  - [`teleport_trusted_device`](./trusted_device.mdx)
+  - [`teleport_user`](./user.mdx)

docs/pages/reference/terraform-provider/resources/resources.mdx

@@ -0,0 +1,37 @@
+---
+title: "Terraform resources index"
+description: "Index of all the datasources supported by the Teleport Terraform Provider"
+---
+
+{/*Auto-generated file. Do not edit.*/}
+{/*To regenerate, navigate to integrations/terraform and run `make docs`.*/}
+
+{/*
+    This file will be renamed data-sources.mdx during build time.
+    The template name is reserved by tfplugindocs so we suffix with -index.
+*/}
+
+The Teleport Terraform provider supports the following resources:
+
+  - [`teleport_access_list`](./access_list.mdx)
+  - [`teleport_access_monitoring_rule`](./access_monitoring_rule.mdx)
+  - [`teleport_app`](./app.mdx)
+  - [`teleport_auth_preference`](./auth_preference.mdx)
+  - [`teleport_bot`](./bot.mdx)
+  - [`teleport_cluster_maintenance_config`](./cluster_maintenance_config.mdx)
+  - [`teleport_cluster_networking_config`](./cluster_networking_config.mdx)
+  - [`teleport_database`](./database.mdx)
+  - [`teleport_github_connector`](./github_connector.mdx)
+  - [`teleport_installer`](./installer.mdx)
+  - [`teleport_login_rule`](./login_rule.mdx)
+  - [`teleport_oidc_connector`](./oidc_connector.mdx)
+  - [`teleport_okta_import_rule`](./okta_import_rule.mdx)
+  - [`teleport_provision_token`](./provision_token.mdx)
+  - [`teleport_role`](./role.mdx)
+  - [`teleport_saml_connector`](./saml_connector.mdx)
+  - [`teleport_server`](./server.mdx)
+  - [`teleport_session_recording_config`](./session_recording_config.mdx)
+  - [`teleport_static_host_user`](./static_host_user.mdx)
+  - [`teleport_trusted_cluster`](./trusted_cluster.mdx)
+  - [`teleport_trusted_device`](./trusted_device.mdx)
+  - [`teleport_user`](./user.mdx)

docs/pages/reference/terraform-provider.mdx → docs/pages/reference/terraform-provider/terraform-provider.mdx

@@ -14,10 +14,10 @@ It lists all the supported resources and their fields.
 
 <Admonition type="tip">
 To get started with the Terraform provider, you must start with [the installation
-guide](../admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx).
+guide](../../admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx).
 Once you got a working provider, we recommend you to follow the
 ["Managing users and roles with IaC"](
-../admin-guides/infrastructure-as-code/managing-resources/user-and-role.mdx) guide.
+../../admin-guides/infrastructure-as-code/managing-resources/user-and-role.mdx) guide.
 </Admonition>
 
 The provider exposes Teleport resources both as Terraform data-sources and Terraform resources.
@@ -27,8 +27,8 @@ to create resources in Teleport.
 {/* Note: the awkward `resource-index` file names are here because `data-sources`
 is reserved by the generator for the catch-all resource template */}
 
-- [list of supported resources](./terraform-provider/resources.mdx)
-- [list of supported data-sources](./terraform-provider/data-sources.mdx)
+- [list of supported resources](./resources/resources.mdx)
+- [list of supported data-sources](./data-sources/data-sources.mdx)
 
 ## Example Usage
 
@@ -81,7 +81,7 @@ provider "teleport" {
 This section lists the different ways of passing credentials to the Terraform provider.
 You can find which method fits your use case in
 the [Teleport Terraform provider setup
-page](../admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx)
+page](../../admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx)
 
 ### With an identity file
 
@@ -108,16 +108,16 @@ Detected security key tap
 ```
 
 You can find more information in
-the ["Run the Terraform provider locally" guide](../admin-guides/infrastructure-as-code/terraform-provider/local.mdx)
+the ["Run the Terraform provider locally" guide](../../admin-guides/infrastructure-as-code/terraform-provider/local.mdx)
 
 #### Obtaining an identity file via `tbot`
 
-`tbot` relies on [MachineID](../enroll-resources/machine-id/introduction.mdx) to obtain and automatically renew
+`tbot` relies on [MachineID](../../enroll-resources/machine-id/introduction.mdx) to obtain and automatically renew
 short-lived credentials. Such credentials are harder to exfiltrate, and you can control more precisely who has access to
 which roles (e.g. you can allow only GitHub Actions pipelines targeting the `prod` environment to get certificates).
 
 You can follow [the Terraform Provider
-guide](../admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx) to setup `tbot`
+guide](../../admin-guides/infrastructure-as-code/terraform-provider/terraform-provider.mdx) to setup `tbot`
 and have Terraform use its identity.
 
 #### Obtaining an identity file via `tctl auth sign`
@@ -132,19 +132,19 @@ This auth method has the following limitations:
 - Such credentials are high-privileged and long-lived. They must be protected and rotated.
 - This auth method does not work against Teleport clusters with MFA set to `webauthn`.
   On such clusters, Teleport will reject any long-lived certificate and require
-  [an additional MFA challenge for administrative actions](../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx).
+  [an additional MFA challenge for administrative actions](../../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx).
 
 ### With a token (native MachineID)
 
 Starting with 16.2, the Teleport Terraform provider can natively use MachineID (without `tbot`) to join a Teleport
 cluster. The Terraform Provider will rely on its runtime (AWS, GCP, Kubernetes, CI/CD system) to prove its identity to
 Teleport.
 
-You can use any [delegated join method](./join-methods.mdx#delegated-join-methods) by setting
+You can use any [delegated join method](../join-methods.mdx#delegated-join-methods) by setting
 both `join_method` and `join_token` in the provider configuration.
 
 This setup is described in more details in
-the ["Run the Teleport Terraform provider in CI or Cloud" guide](../admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx).
+the ["Run the Teleport Terraform provider in CI or Cloud" guide](../../admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx).
 
 ### With key, certificate, and CA certificate
 
@@ -160,7 +160,7 @@ This auth method has the following limitations:
 - Such credentials are high-privileged and long-lived. They must be protected and rotated.
 - This auth method does not work against Teleport clusters with MFA set to `webauthn`.
   On such clusters, Teleport will reject any long-lived certificate and require
-  [an additional MFA challenge for administrative actions](../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx).
+  [an additional MFA challenge for administrative actions](../../admin-guides/access-controls/guides/mfa-for-admin-actions.mdx).
 
 {/*  schema generated by tfplugindocs */}
 ## Schema
@@ -175,8 +175,8 @@ This auth method has the following limitations:
 - `identity_file` (String, Sensitive) Teleport identity file content. This can also be set with the environment variable `TF_TELEPORT_IDENTITY_FILE`.
 - `identity_file_base64` (String, Sensitive) Teleport identity file content base64 encoded. This can also be set with the environment variable `TF_TELEPORT_IDENTITY_FILE_BASE64`.
 - `identity_file_path` (String) Teleport identity file path. This can also be set with the environment variable `TF_TELEPORT_IDENTITY_FILE_PATH`.
-- `join_method` (String) Enables the native Terraform MachineID support. When set, Terraform uses MachineID to securely join the Teleport cluster and obtain credentials. See [the join method reference](./join-methods.mdx) for possible values, you must use [a delegated join method](./join-methods.mdx#secret-vs-delegated). This can also be set with the environment variable `TF_TELEPORT_JOIN_METHOD`.
-- `join_token` (String) Name of the token used for the native MachineID joining. This value is not sensitive for [delegated join methods](./join-methods.mdx#secret-vs-delegated). This can also be set with the environment variable `TF_TELEPORT_JOIN_TOKEN`.
+- `join_method` (String) Enables the native Terraform MachineID support. When set, Terraform uses MachineID to securely join the Teleport cluster and obtain credentials. See [the join method reference](../join-methods.mdx) for possible values. You must use [a delegated join method](../join-methods.mdx#secret-vs-delegated). This can also be set with the environment variable `TF_TELEPORT_JOIN_METHOD`.
+- `join_token` (String) Name of the token used for the native MachineID joining. This value is not sensitive for [delegated join methods](../join-methods.mdx#secret-vs-delegated). This can also be set with the environment variable `TF_TELEPORT_JOIN_TOKEN`.
 - `key_base64` (String, Sensitive) Base64 encoded TLS auth key. This can also be set with the environment variable `TF_TELEPORT_KEY_BASE64`.
 - `key_path` (String) Path to Teleport auth key file. This can also be set with the environment variable `TF_TELEPORT_KEY`.
 - `profile_dir` (String) Teleport profile path. This can also be set with the environment variable `TF_TELEPORT_PROFILE_PATH`.