feat: shallow clone git repository sources (including auth changes)

docs/content/docs/2.collections/3.sources.md

@@ -80,7 +80,7 @@ source: {
 
 ### `repository`
 
-External source representing a remote git repository URL (e.g., <https://github.com/nuxt/content>).
+External source representing a remote git repository URL (e.g., <https://github.com/nuxt/content>). Only supports downloading from Github and Bitbucket by default, unless `cloneRepository` is set.
 
 When defining an external source you must also define the `include` option.
 `include` pattern is essential for the module to know which files to use for the collection.
@@ -101,27 +101,105 @@ export default defineContentConfig({
 })
 ```
 
-### `authToken`
+### `cloneRepository`
+This option allows for shallow-cloning any Git repository (`git clone --depth=1`), with an optional Git reference. Enabling this to `true` will clone the repository at build-time, and work as normal.
 
-Authentication token for private repositories (e.g., GitHub personal access token).
+```js
+export default defineContentConfig({
+  collections: {
+    docs: defineCollection({
+      type: 'page',
+      source: {
+        repository: 'https://github.com/nuxt/content',
+        include: 'docs/content/**',
+        cloneRepository: true
+      },
+    })
+  }
+})
+```
+
+### `ref`
+Declares the Git branch or tag the content source downloads from.
+```js
+export default defineContentConfig({
+  collections: {
+    docs: defineCollection({
+      type: 'page',
+      source: {
+        repository: 'https://github.com/nuxt/content',
+        include: 'docs/content/**',
+        cloneRepository: true,
+        ref: {
+          branch: "main"
+          // tag: "v4.0.0"
+        }
+      },
+    })
+  }
+})
+```
+
+
+### `authBasic`
+A basic authentication configuration for private repositories (e.g. Bitbucket username and password).
 
 ::warning{icon="i-lucide-shield-alert"}
-Never commit authentication tokens or credentials directly in your code. Use environment variables or other secure methods to provide these values at runtime.
+Never commit Git provider credentials directly in your code. Use environment variables or other secure methods to provide these values at runtime.
 ::
 
-### `authBasic`
+```js
+export default defineContentConfig({
+  collections: {
+    docs: defineCollection({
+      type: 'page',
+      source: {
+        repository: 'https://bitbucket.org/user/repo',
+        authBasic: {
+          username: 'username',
+          password: 'password',
+        }
+      },
+    })
+  }
+})
+```
 
-Basic authentication for private repositories (e.g., Bitbucket username and password).
+### `authToken`
+Authentication token for private repositories (e.g., Github Personal Access Token). Recommended for Github [Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and Bitbucket [API Tokens](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/).
 
-```ts
-defineCollection({
-  type: 'page',
-  source: {
-    repository: 'https://bitbucket.org/username/repo',
-    authBasic: {
-      username: 'username',
-      password: 'password',
-    },
-  },
+::warning{icon="i-lucide-shield-alert"}
+Never commit authentication tokens directly in your code. Use environment variables or other secure methods to provide these values at runtime.
+::
+```js
+export default defineContentConfig({
+  collections: {
+    docs: defineCollection({
+      type: 'page',
+      source: {
+        repository: 'https://github.com/user/repo',
+        authToken: {
+          // Note: providing a username is *optional* for Github.
+          username: "octocat",
+          authToken: "ghp_TOKENHERE"
+        }
+      },
+    })
+  }
+})
+```
+If your provider does not need a username, you can simply declare `authToken` as a string.
+
+```js
+export default defineContentConfig({
+  collections: {
+    docs: defineCollection({
+      type: 'page',
+      source: {
+        repository: 'https://github.com/user/repo',
+        authToken: "ghp_TOKENHERE"
+      },
+    })
+  }
 })
 ```

package.json

@@ -72,6 +72,7 @@
     "defu": "^6.1.4",
     "destr": "^2.0.5",
     "git-url-parse": "^16.1.0",
+    "isomorphic-git": "^1.33.1",
     "jiti": "^2.5.1",
     "json-schema-to-typescript": "^15.0.4",
     "knitwork": "^1.2.0",