docs: improve docs by using code-styled markdown (#260)

docs/data-sources/git_auth.md

@@ -3,11 +3,16 @@
 page_title: "coder_git_auth Data Source - terraform-provider-coder"
 subcategory: ""
 description: |-
+  ~> Deprecated
+  Use the coder_external_auth data source instead.
   Use this data source to require users to authenticate with a Git provider prior to workspace creation. This can be used to perform an authenticated git clone in startup scripts.
 ---
 
 # coder_git_auth (Data Source)
 
+~> **Deprecated**
+Use the `coder_external_auth` data source instead.
+
 Use this data source to require users to authenticate with a Git provider prior to workspace creation. This can be used to perform an authenticated `git clone` in startup scripts.
 
 ## Example Usage

docs/data-sources/parameter.md

@@ -145,11 +145,11 @@ data "coder_parameter" "home_volume_size" {
 - `description` (String) Describe what this parameter does.
 - `display_name` (String) The displayed name of the parameter as it will appear in the interface.
 - `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds.
-- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `data.coder_workspace.me.access_url + "/icon/<path>"`.
+- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/<path>"`.
 - `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution!
-- `option` (Block List, Max: 64) Each "option" block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option))
+- `option` (Block List, Max: 64) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option))
 - `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order).
-- `type` (String) The type of this parameter. Must be one of: "number", "string", "bool", or "list(string)".
+- `type` (String) The type of this parameter. Must be one of: `"number"`, `"string"`, `"bool"`, or `"list(string)"`.
 - `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation))
 
 ### Read-Only
@@ -169,7 +169,7 @@ Required:
 Optional:
 
 - `description` (String) Describe what selecting this value does.
-- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons here: https://github.com/coder/coder/tree/main/site/static/icon. Use a built-in icon with `data.coder_workspace.me.access_url + "/icon/<path>"`.
+- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/<path>"`.
 
 
 <a id="nestedblock--validation"></a>

docs/data-sources/workspace.md

@@ -30,15 +30,15 @@ resource "kubernetes_pod" "dev" {
 - `access_url` (String) The access URL of the Coder deployment provisioning this workspace.
 - `id` (String) UUID of the workspace.
 - `name` (String) Name of the workspace.
-- `owner` (String, Deprecated: Use `coder_workspace_owner.name` instead.) Username of the workspace owner.
-- `owner_email` (String, Deprecated: Use `coder_workspace_owner.email` instead.) Email address of the workspace owner.
-- `owner_groups` (List of String, Deprecated: Use `coder_workspace_owner.groups` instead.) List of groups the workspace owner belongs to.
-- `owner_id` (String, Deprecated: Use `coder_workspace_owner.id` instead.) UUID of the workspace owner.
-- `owner_name` (String, Deprecated: Use `coder_workspace_owner.full_name` instead.) Name of the workspace owner.
-- `owner_oidc_access_token` (String, Deprecated: Use `coder_workspace_owner.oidc_access_token` instead.) A valid OpenID Connect access token of the workspace owner. This is only available if the workspace owner authenticated with OpenID Connect. If a valid token cannot be obtained, this value will be an empty string.
-- `owner_session_token` (String, Deprecated: Use `coder_workspace_owner.session_token` instead.) Session token for authenticating with a Coder deployment. It is regenerated everytime a workspace is started.
-- `start_count` (Number) A computed count based on "transition" state. If "start", count will equal 1.
+- `owner` (String, **Deprecated**: Use `coder_workspace_owner.name` instead.) Username of the workspace owner.
+- `owner_email` (String, **Deprecated**: Use `coder_workspace_owner.email` instead.) Email address of the workspace owner.
+- `owner_groups` (List of String, **Deprecated**: Use `coder_workspace_owner.groups` instead.) List of groups the workspace owner belongs to.
+- `owner_id` (String, **Deprecated**: Use `coder_workspace_owner.id` instead.) UUID of the workspace owner.
+- `owner_name` (String, **Deprecated**: Use `coder_workspace_owner.full_name` instead.) Name of the workspace owner.
+- `owner_oidc_access_token` (String, **Deprecated**: Use `coder_workspace_owner.oidc_access_token` instead.) A valid OpenID Connect access token of the workspace owner. This is only available if the workspace owner authenticated with OpenID Connect. If a valid token cannot be obtained, this value will be an empty string.
+- `owner_session_token` (String, **Deprecated**: Use `coder_workspace_owner.session_token` instead.) Session token for authenticating with a Coder deployment. It is regenerated everytime a workspace is started.
+- `start_count` (Number) A computed count based on `transition` state. If `start`, count will equal 1.
 - `template_id` (String) ID of the workspace's template.
 - `template_name` (String) Name of the workspace's template.
 - `template_version` (String) Version of the workspace's template.
-- `transition` (String) Either "start" or "stop". Use this to start/stop resources with "count".
+- `transition` (String) Either `start` or `stop`. Use this to start/stop resources with `count`.

docs/index.md

@@ -62,5 +62,5 @@ resource "google_compute_instance" "dev" {
 
 ### Optional
 
-- `feature_use_managed_variables` (Boolean, Deprecated: Terraform variables are now exclusively utilized for template-wide variables after the removal of support for legacy parameters.) Feature: use managed Terraform variables. The feature flag is not used anymore as Terraform variables are now exclusively utilized for template-wide variables.
+- `feature_use_managed_variables` (Boolean, **Deprecated**: Terraform variables are now exclusively utilized for template-wide variables after the removal of support for legacy parameters.) Feature: use managed Terraform variables. The feature flag is not used anymore as Terraform variables are now exclusively utilized for template-wide variables.
 - `url` (String) The URL to access Coder.

docs/resources/agent.md

@@ -66,32 +66,32 @@ resource "kubernetes_pod" "dev" {
 
 ### Required
 
-- `arch` (String) The architecture the agent will run on. Must be one of: "amd64", "armv7", "arm64".
-- `os` (String) The operating system the agent will run on. Must be one of: "linux", "darwin", or "windows".
+- `arch` (String) The architecture the agent will run on. Must be one of: `"amd64"`, `"armv7"`, `"arm64"`.
+- `os` (String) The operating system the agent will run on. Must be one of: `"linux"`, `"darwin"`, or `"windows"`.
 
 ### Optional
 
-- `auth` (String) The authentication type the agent will use. Must be one of: "token", "google-instance-identity", "aws-instance-identity", "azure-instance-identity".
+- `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`.
 - `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out.
-- `dir` (String) The starting directory when a user creates a shell session. Defaults to $HOME.
+- `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`.
 - `display_apps` (Block Set, Max: 1) The list of built-in apps to display in the agent bar. (see [below for nested schema](#nestedblock--display_apps))
 - `env` (Map of String) A mapping of environment variables to set inside the workspace.
-- `login_before_ready` (Boolean, Deprecated: Configure startup_script_behavior instead. This attribute will be removed in a future version of the provider.) This option defines whether or not the user can (by default) login to the workspace before it is ready. Ready means that e.g. the startup_script is done and has exited. When enabled, users may see an incomplete workspace when logging in.
-- `metadata` (Block List) Each "metadata" block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata))
-- `motd_file` (String) The path to a file within the workspace containing a message to display to users when they login via SSH. A typical value would be /etc/motd.
+- `login_before_ready` (Boolean, **Deprecated**: Configure `startup_script_behavior` instead. This attribute will be removed in a future version of the provider.) This option defines whether or not the user can (by default) login to the workspace before it is ready. Ready means that e.g. the `startup_script` is done and has exited. When enabled, users may see an incomplete workspace when logging in.
+- `metadata` (Block List) Each `metadata` block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata))
+- `motd_file` (String) The path to a file within the workspace containing a message to display to users when they login via SSH. A typical value would be `"/etc/motd"`.
 - `order` (Number) The order determines the position of agents in the UI presentation. The lowest order is shown first and agents with equal order are sorted by name (ascending order).
-- `shutdown_script` (String) A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a "coder_script" resource with "run_on_stop" set to true.
-- `shutdown_script_timeout` (Number, Deprecated: This feature is deprecated and has no effect. This attribute will be removed in a future version of the provider.) Time in seconds until the agent lifecycle status is marked as timed out during shutdown, this happens when the shutdown script has not completed (exited) in the given time.
-- `startup_script` (String) A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a "coder_script" resource with "run_on_start" set to true.
-- `startup_script_behavior` (String) This option sets the behavior of the "startup_script". When set to "blocking", the startup_script must exit before the workspace is ready. When set to "non-blocking", the startup_script may run in the background and the workspace will be ready immediately. Default is "non-blocking", although "blocking" is recommended. This option is an alias for defining a "coder_script" resource with "start_blocks_login" set to true (blocking).
-- `startup_script_timeout` (Number, Deprecated: This feature is deprecated and has no effect. This attribute will be removed in a future version of the provider.) Time in seconds until the agent lifecycle status is marked as timed out during start, this happens when the startup script has not completed (exited) in the given time.
+- `shutdown_script` (String) A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a `coder_script` resource with `run_on_stop` set to `true`.
+- `shutdown_script_timeout` (Number, **Deprecated**: This feature is deprecated and has no effect. This attribute will be removed in a future version of the provider.) Time in seconds until the agent lifecycle status is marked as timed out during shutdown, this happens when the shutdown script has not completed (exited) in the given time.
+- `startup_script` (String) A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a `coder_script` resource with `run_on_start` set to `true`.
+- `startup_script_behavior` (String) This option sets the behavior of the `startup_script`. When set to `"blocking"`, the `startup_script` must exit before the workspace is ready. When set to `"non-blocking"`, the `startup_script` may run in the background and the workspace will be ready immediately. Default is `"non-blocking"`, although `"blocking"` is recommended. This option is an alias for defining a `coder_script` resource with `start_blocks_login` set to `true` (blocking).
+- `startup_script_timeout` (Number, **Deprecated**: This feature is deprecated and has no effect. This attribute will be removed in a future version of the provider.) Time in seconds until the agent lifecycle status is marked as timed out during start, this happens when the startup script has not completed (exited) in the given time.
 - `troubleshooting_url` (String) A URL to a document with instructions for troubleshooting problems with the agent.
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
 - `init_script` (String) Run this script on startup of an instance to initialize the agent.
-- `token` (String, Sensitive) Set the environment variable "CODER_AGENT_TOKEN" with this token to authenticate an agent.
+- `token` (String, Sensitive) Set the environment variable `CODER_AGENT_TOKEN` with this token to authenticate an agent.
 
 <a id="nestedblock--display_apps"></a>
 ### Nested Schema for `display_apps`

docs/resources/agent_instance.md

@@ -8,7 +8,7 @@ description: |-
 
 # coder_agent_instance (Resource)
 
-Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for "google_compute_instance", "aws_instance", "azurerm_linux_virtual_machine", and "azurerm_windows_virtual_machine" resources.
+Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources.
 
 ## Example Usage
 
@@ -34,7 +34,7 @@ resource "coder_agent_instance" "dev" {
 
 ### Required
 
-- `agent_id` (String) The "id" property of a "coder_agent" resource to associate with.
+- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with.
 - `instance_id` (String) The instance identifier of a provisioned resource.
 
 ### Read-Only