diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dc348ef97..3ea20828b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -280,8 +280,16 @@ docker compose down
 ## Contribute Docs
 
 Project documentation is made with docusaurus and is located under [./docs](./docs).
+
+### Local Testing
 Please refer to the [README](./docs/README.md) for more information and local testing.
 
+### Style Guide
+
+- **Code with variables**: Make sure that code snippets can be used by setting environment variables, instead of manually replacing a placeholder.
+- **Embedded files**: When embedding mdx files, make sure the template ist prefixed by "_" (lowdash). The content will be rendered inside the parent page, but is not accessible individually (eg, by search).
+
+### Docs Pull Request
 When making a pull request use `docs(<scope>): <short summary>` as title for the semantic release.
 Scope can be left empty (omit the brackets) or refer to the top navigation sections.
 
diff --git a/docs/docs/guides/integrate/authmethods.mdx b/docs/docs/guides/integrate/_authmethods.mdx
similarity index 83%
rename from docs/docs/guides/integrate/authmethods.mdx
rename to docs/docs/guides/integrate/_authmethods.mdx
index 7908f0dfd..9ec104b61 100644
--- a/docs/docs/guides/integrate/authmethods.mdx
+++ b/docs/docs/guides/integrate/_authmethods.mdx
@@ -1,11 +1,10 @@
 import TabItem from "@theme/TabItem";
 import Tabs from "@theme/Tabs";
-import PKCE from "./authmethods/pkce.mdx";
-
-import Basic from "./authmethods/basic.mdx";
-import Implicit from "./authmethods/implicit.mdx";
-import PKCENative from "./authmethods/pkcenative.mdx";
-import JWTPrivateKey from "./authmethods/jwtpk.mdx";
+import PKCE from "./authmethods/_pkce.mdx";
+import Basic from "./authmethods/_basic.mdx";
+import Implicit from "./authmethods/_implicit.mdx";
+import PKCENative from "./authmethods/_pkcenative.mdx";
+import JWTPrivateKey from "./authmethods/_jwtpk.mdx";
 
 export default function AuthMethods(props) {
   return props.selected == "web" ? (
diff --git a/docs/docs/guides/integrate/application/application.mdx b/docs/docs/guides/integrate/application/_application.mdx
similarity index 88%
rename from docs/docs/guides/integrate/application/application.mdx
rename to docs/docs/guides/integrate/application/_application.mdx
index c7d8c30c7..ff0492629 100644
--- a/docs/docs/guides/integrate/application/application.mdx
+++ b/docs/docs/guides/integrate/application/_application.mdx
@@ -1,8 +1,8 @@
 import ThemedImage from "@theme/ThemedImage";
-import AuthType from "./auth-type.mdx";
-import RedirectURIs from "./redirect-uris.mdx";
-import GenerateKey from "./generate-key.mdx";
-import ReviewConfig from "./review-config.mdx";
+import AuthType from "./_auth-type.mdx";
+import RedirectURIs from "./_redirect-uris.mdx";
+import GenerateKey from "./_generate-key.mdx";
+import ReviewConfig from "./_review-config.mdx";
 
 export default function CreateApp(props) {
   return (
diff --git a/docs/docs/guides/integrate/application/auth-type.mdx b/docs/docs/guides/integrate/application/_auth-type.mdx
similarity index 100%
rename from docs/docs/guides/integrate/application/auth-type.mdx
rename to docs/docs/guides/integrate/application/_auth-type.mdx
diff --git a/docs/docs/guides/integrate/application/generate-key.mdx b/docs/docs/guides/integrate/application/_generate-key.mdx
similarity index 100%
rename from docs/docs/guides/integrate/application/generate-key.mdx
rename to docs/docs/guides/integrate/application/_generate-key.mdx
diff --git a/docs/docs/guides/integrate/application/redirect-uris.mdx b/docs/docs/guides/integrate/application/_redirect-uris.mdx
similarity index 100%
rename from docs/docs/guides/integrate/application/redirect-uris.mdx
rename to docs/docs/guides/integrate/application/_redirect-uris.mdx
diff --git a/docs/docs/guides/integrate/application/review-config.mdx b/docs/docs/guides/integrate/application/_review-config.mdx
similarity index 100%
rename from docs/docs/guides/integrate/application/review-config.mdx
rename to docs/docs/guides/integrate/application/_review-config.mdx
diff --git a/docs/docs/guides/integrate/auth0-oidc.md b/docs/docs/guides/integrate/auth0-oidc.mdx
similarity index 97%
rename from docs/docs/guides/integrate/auth0-oidc.md
rename to docs/docs/guides/integrate/auth0-oidc.mdx
index 54d3173d5..a455ca90a 100644
--- a/docs/docs/guides/integrate/auth0-oidc.md
+++ b/docs/docs/guides/integrate/auth0-oidc.mdx
@@ -2,6 +2,8 @@
 title: Connect with Auth0 through OIDC
 ---
 
+import CreateApp from "./application/_application.mdx";
+
 This guide shows how to enable login with ZITADEL on Auth0.
 
 It covers how to:
@@ -38,8 +40,6 @@ Next we have to switch to the ZITADEL console.
 
 First of all we create the application in your project.
 
-import CreateApp from "./application/application.mdx";
-
 <CreateApp appType="web" authType="code" appName="Auth0" redirectURI="https://<TENANT>.<REGION>.auth0.com/login/callback"/>
 
 ## **Auth0**: Connect ZITADEL
diff --git a/docs/docs/guides/integrate/authmethods/basic.mdx b/docs/docs/guides/integrate/authmethods/_basic.mdx
similarity index 100%
rename from docs/docs/guides/integrate/authmethods/basic.mdx
rename to docs/docs/guides/integrate/authmethods/_basic.mdx
diff --git a/docs/docs/guides/integrate/authmethods/implicit.mdx b/docs/docs/guides/integrate/authmethods/_implicit.mdx
similarity index 100%
rename from docs/docs/guides/integrate/authmethods/implicit.mdx
rename to docs/docs/guides/integrate/authmethods/_implicit.mdx
diff --git a/docs/docs/guides/integrate/authmethods/jwtpk.mdx b/docs/docs/guides/integrate/authmethods/_jwtpk.mdx
similarity index 100%
rename from docs/docs/guides/integrate/authmethods/jwtpk.mdx
rename to docs/docs/guides/integrate/authmethods/_jwtpk.mdx
diff --git a/docs/docs/guides/integrate/authmethods/pkce.mdx b/docs/docs/guides/integrate/authmethods/_pkce.mdx
similarity index 100%
rename from docs/docs/guides/integrate/authmethods/pkce.mdx
rename to docs/docs/guides/integrate/authmethods/_pkce.mdx
diff --git a/docs/docs/guides/integrate/authmethods/pkcenative.mdx b/docs/docs/guides/integrate/authmethods/_pkcenative.mdx
similarity index 100%
rename from docs/docs/guides/integrate/authmethods/pkcenative.mdx
rename to docs/docs/guides/integrate/authmethods/_pkcenative.mdx
diff --git a/docs/docs/guides/integrate/gitlab-self-hosted.md b/docs/docs/guides/integrate/gitlab-self-hosted.mdx
similarity index 97%
rename from docs/docs/guides/integrate/gitlab-self-hosted.md
rename to docs/docs/guides/integrate/gitlab-self-hosted.mdx
index c2bb76547..bdbbd361e 100644
--- a/docs/docs/guides/integrate/gitlab-self-hosted.md
+++ b/docs/docs/guides/integrate/gitlab-self-hosted.mdx
@@ -2,6 +2,9 @@
 title: Gitlab OmniAuth Provider
 ---
 
+import CreateApp from "./application/_application.mdx";
+
+
 This guide shows how to enable login with ZITADEL on self-hosted Gitlab instances.
 
 It covers how to:
@@ -16,8 +19,6 @@ Prerequisites:
 - existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects)
 - running Gitlab instance see [installation guide](https://docs.gitlab.com/ee/install/)
 
-import CreateApp from "./application/application.mdx";
-
 <CreateApp appType="web" authType="code" appName="Gitlab" redirectURI="https://<your_gitlab_url>/users/auth/openid_connect/callback"/>
 
 ## Gitlab configuration
diff --git a/docs/docs/guides/integrate/login-users.mdx b/docs/docs/guides/integrate/login-users.mdx
index 7fc8e5461..b6e7096d5 100644
--- a/docs/docs/guides/integrate/login-users.mdx
+++ b/docs/docs/guides/integrate/login-users.mdx
@@ -4,7 +4,7 @@ title: Login Users into your Application
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
-import AuthMethods from "./authmethods.mdx";
+import AuthMethods from "./_authmethods.mdx";
 
 ## Overview
 
diff --git a/docs/docs/guides/manage/console/applications.mdx b/docs/docs/guides/manage/console/applications.mdx
index f17a3f340..0266c5ae4 100644
--- a/docs/docs/guides/manage/console/applications.mdx
+++ b/docs/docs/guides/manage/console/applications.mdx
@@ -4,10 +4,8 @@ title: Applications
 
 import ThemedImage from "@theme/ThemedImage";
 
-import AuthType from "../../integrate/application/auth-type.mdx";
-import RedirectURIs from "../../integrate/application/redirect-uris.mdx";
-import GenerateKey from "../../integrate/application/generate-key.mdx";
-import ReviewConfig from "../../integrate/application/review-config.mdx";
+import AuthType from "../../integrate/application/_auth-type.mdx";
+import ReviewConfig from "../../integrate/application/_review-config.mdx";
 
 # What is an application?