diff --git a/README.md b/README.md
index b907eab7..5715024b 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,15 @@ Terraform Provider for [Pact Broker](https://github.com/pact-foundation/pact_bro
 
 Example:
 ```hcl
+terraform {
+  required_providers {
+    pact = {
+      source = "pactflow/pact"
+      version = "0.1.2"
+    }
+  }
+}
+
 variable "token" {
   type = string
 }
@@ -123,13 +132,13 @@ For either installation method, documentation about the provider specific config
 
 | Plugin      | Type     | Platform Support       | Description |
 | ----------- | -------- | ---------------------- | ----------- |
-| [Pact](docs/provider_pact.html.markdown)        | Provider | Pact Broker + Pactflow | Configures a target Pact Broker (such as a pactflow.io account) |
-| [Pacticipant](docs/resource_pacticipant.html.markdown)  | Resource | Pact Broker + Pactflow | Create applications (known as Pacticipants) |
-| [Webhook](docs/resource_webhook.html.markdown)     | Resource | Pact Broker + Pactflow | Configures a webhook to trigger on certain platform events |
-| [Secret](docs/resource_secret.html.markdown)      | Resource | Pactflow               | Create an encrypted secret for use in Webhooks |
-| [API Token](docs/resource_token.html.markdown)   | Resource | Pactflow               | Manage Pactflow API Tokens |
-| [Users](docs/resource_user.html.markdown)   | Resource | Pactflow               | Manage Pactflow Users |
-| [Roles](docs/resource_role.html.markdown)   | Resource | Pactflow               | Manage Pactflow Roles |
+| [Pact](docs/index.md)        | Provider | Pact Broker + Pactflow | Configures a target Pact Broker (such as a pactflow.io account) |
+| [Pacticipant](docs/resources/pacticipant.md)  | Resource | Pact Broker + Pactflow | Create applications (known as Pacticipants) |
+| [Webhook](docs/resources/webhook.md)     | Resource | Pact Broker + Pactflow | Configures a webhook to trigger on certain platform events |
+| [Secret](docs/resources/secret.md)      | Resource | Pactflow               | Create an encrypted secret for use in Webhooks |
+| [API Token](docs/resources/token.md)   | Resource | Pactflow               | Manage Pactflow API Tokens |
+| [Users](docs/resources/user.md)   | Resource | Pactflow               | Manage Pactflow Users |
+| [Roles](docs/resources/role.md)   | Resource | Pactflow               | Manage Pactflow Roles |
 
 See our [Docs](./docs) folder for all plugins.
 
diff --git a/docs/provider_pact.html.markdown b/docs/index.md
similarity index 92%
rename from docs/provider_pact.html.markdown
rename to docs/index.md
index 3c84036a..4d4614d4 100644
--- a/docs/provider_pact.html.markdown
+++ b/docs/index.md
@@ -2,7 +2,7 @@
 
 Pact Broker Provider sets up a connection to a hosted Broker.
 
-_NOTE_: We currently support both the Open Source Pact Broker and our Pactflow.io platform.
+-> We currently support both the Open Source Pact Broker and our Pactflow.io platform.
 
 ## Example Usage
 The following examples show the basic usage of the resouproviderrce.
diff --git a/docs/resource_pacticipant.html.markdown b/docs/resources/pacticipant.md
similarity index 100%
rename from docs/resource_pacticipant.html.markdown
rename to docs/resources/pacticipant.md
diff --git a/docs/resource_role.html.markdown b/docs/resources/role.md
similarity index 100%
rename from docs/resource_role.html.markdown
rename to docs/resources/role.md
diff --git a/docs/resource_secret.html.markdown b/docs/resources/secret.md
similarity index 95%
rename from docs/resource_secret.html.markdown
rename to docs/resources/secret.md
index 5889e811..4dcaf9bc 100644
--- a/docs/resource_secret.html.markdown
+++ b/docs/resources/secret.md
@@ -2,7 +2,7 @@
 
 This resource manages the lifecycle of a _Secret_. A Secret is an application that may perform the role of a consumer or a provider in the Pact ecosystem.
 
-_NOTE_: this is currently only supported for the Pactflow.io platform.
+-> this is currently only supported for the Pactflow.io platform.
 
 ## Example Usage
 The following examples show the basic usage of the resource.
diff --git a/docs/resource_token.html.markdown b/docs/resources/token.md
similarity index 90%
rename from docs/resource_token.html.markdown
rename to docs/resources/token.md
index ba09893f..e514aeb4 100644
--- a/docs/resource_token.html.markdown
+++ b/docs/resources/token.md
@@ -2,11 +2,9 @@
 
 This resource manages the lifecycle of an _API Token_. A Token can be used to make API calls to the Pactflow platform.
 
-**It is highly recommended that this resource only be used to import existing tokens, and not be used to update existing tokens**
-
-_NOTE_: this is currently only supported for the Pactflow.io platform.
-
+!> **It is highly recommended that this resource only be used to import existing tokens, and not be used to update existing tokens - you are likely to end up locking yourself out this way**
 
+-> this is currently only supported for the Pactflow.io platform.
 
 ## Example Usage
 
diff --git a/docs/resource_user.html.markdown b/docs/resources/user.md
similarity index 100%
rename from docs/resource_user.html.markdown
rename to docs/resources/user.md
diff --git a/docs/resource_webhook.html.markdown b/docs/resources/webhook.md
similarity index 100%
rename from docs/resource_webhook.html.markdown
rename to docs/resources/webhook.md