feat: refactor VitePress plugin with top-level repo config

- Add repoURL as top-level plugin option
- Add contentPath option for docs directory
- Auto-configure GitChangelog from repoURL
- Enhance useSourceCode with plugin config
- Add useNimiqConfig composable with SSR safety
- Update docs with new configuration examples

Author: onmax

docs/vite.config.ts

@@ -23,7 +23,8 @@ export default defineConfig(async () => ({
     Inspect(),
     UnoCSS(),
     NimiqVitepressVitePlugin({
-      gitChangelog: { repoURL: 'https://github.com/onmax/nimiq-ui' },
+      repoURL: 'https://github.com/onmax/nimiq-ui',
+      contentPath: 'docs',
     }),
   ],
 }))

docs/vitepress-theme/index.md

@@ -119,6 +119,55 @@ export default defineNimiqThemeConfig({
 
 This will install the layout and will register the Nimiq Components globally.
 
+### Configure the Vite plugin
+
+The theme provides a Vite plugin that adds Git changelog functionality and source code features:
+
+::: code-group
+
+```ts [vite.config.ts]
+import { NimiqVitepressVitePlugin } from 'nimiq-vitepress-theme/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig(() => {
+  return {
+    plugins: [
+      NimiqVitepressVitePlugin({
+        // GitHub repository URL (required for source code features)
+        repoURL: 'https://github.com/your-org/your-repo',
+
+        // Content directory path relative to repository root
+        // Use this if your docs are not in the repository root
+        contentPath: 'docs', // Optional, defaults to ''
+
+        // Git changelog configuration (optional)
+        // If not provided, will use repoURL as default
+        // Set to false to disable changelog
+        gitChangelog: {
+          repoURL: 'https://github.com/your-org/your-repo' // Can be different from main repoURL
+        }
+      })
+    ]
+  }
+})
+```
+
+:::
+
+#### Plugin Options
+
+| Option         | Type              | Default        | Description                                                                      |
+| -------------- | ----------------- | -------------- | -------------------------------------------------------------------------------- |
+| `repoURL`      | `string`          | -              | GitHub repository URL used for source code links and as default for GitChangelog |
+| `contentPath`  | `string`          | `''`           | Directory path where documentation files are located relative to repository root |
+| `gitChangelog` | `object \| false` | Uses `repoURL` | Git changelog configuration or `false` to disable                                |
+
+The plugin automatically:
+
+- Configures Git changelog functionality using the provided repository URL
+- Enables source code viewing and copying features
+- Constructs proper URLs for "View Source" and "Edit Page" links
+
 ### Register the theme as internal dependency
 
 This step is optional and only needed if you want to use the Vue components from `nimiq-vitepress-theme` in your project.

packages/nimiq-vitepress-theme/src/composables/useNimiqConfig.ts

@@ -0,0 +1,22 @@
+declare const __NIMIQ_VITEPRESS_CONFIG__: {
+  repoURL?: string
+  contentPath?: string
+} | undefined
+
+export interface NimiqVitepressConfig {
+  repoURL?: string
+  contentPath?: string
+}
+
+export function useNimiqConfig(): NimiqVitepressConfig {
+  // Check if running in browser environment and config is available
+  if (typeof window !== 'undefined' && typeof __NIMIQ_VITEPRESS_CONFIG__ !== 'undefined') {
+    return __NIMIQ_VITEPRESS_CONFIG__
+  }
+
+  // For SSR or when config is not available, return fallback
+  return {
+    repoURL: undefined,
+    contentPath: '',
+  }
+}

packages/nimiq-vitepress-theme/src/composables/useSourceCode.ts

@@ -4,10 +4,12 @@ import { useData } from 'vitepress'
 import { computed, ref } from 'vue'
 import { toast } from 'vue-sonner'
 import { useChangelog } from './useChangelog'
+import { useNimiqConfig } from './useNimiqConfig'
 
 export function useSourceCode() {
   const { page, frontmatter } = useData()
   const { repoURL } = useChangelog()
+  const nimiqConfig = useNimiqConfig()
 
   // Use a safer approach for SSR compatibility
   const clipboardResult = typeof window !== 'undefined'
@@ -56,17 +58,28 @@ export function useSourceCode() {
     return config.markdownLink || config.viewMarkdown || config.chatgpt || config.claude
   })
 
+  // Get the effective repo URL, prioritizing plugin config over changelog
+  const effectiveRepoURL = computed(() => {
+    return nimiqConfig.repoURL || repoURL.value
+  })
+
   const getRepoFilePath = computed(() => {
     const pathPrefix = frontmatter.value.sourceCodePathPrefix
 
+    // If explicit path prefix is set in frontmatter, use it
     if (pathPrefix !== undefined) {
       return pathPrefix ? join(pathPrefix, page.value.filePath) : page.value.filePath
     }
 
-    // Detect monorepo patterns to add docs/ prefix
-    if (repoURL.value && (
-      repoURL.value.includes('/nimiq-ui')
-      || repoURL.value.includes('/ui')
+    // Use contentPath from plugin config if available
+    if (nimiqConfig.contentPath) {
+      return join(nimiqConfig.contentPath, page.value.filePath)
+    }
+
+    // Fallback to legacy monorepo detection logic
+    if (effectiveRepoURL.value && (
+      effectiveRepoURL.value.includes('/nimiq-ui')
+      || effectiveRepoURL.value.includes('/ui')
       || page.value.filePath.includes('docs/') === false
     )) {
       return join('docs', page.value.filePath)
@@ -76,16 +89,16 @@ export function useSourceCode() {
   })
 
   const editUrl = computed(() => {
-    if (!repoURL.value)
+    if (!effectiveRepoURL.value)
       return ''
-    return `${repoURL.value.replace(/\/$/, '')}/${getRepoFilePath.value}`
+    return `${effectiveRepoURL.value.replace(/\/$/, '')}/${getRepoFilePath.value}`
   })
 
   const sourceCodeUrl = computed(() => {
-    if (!repoURL.value)
+    if (!effectiveRepoURL.value)
       return ''
 
-    return `${repoURL.value.replace(/\/$/, '')}/blob/main/${getRepoFilePath.value}`
+    return `${effectiveRepoURL.value.replace(/\/$/, '')}/blob/main/${getRepoFilePath.value}`
   })
 
   const sourceCodeLabel = computed(() => {

packages/nimiq-vitepress-theme/src/vite.ts

@@ -5,16 +5,48 @@ import { groupIconVitePlugin } from './code-groups/vite'
 type GitChangelogOptions = Parameters<typeof GitChangelog>[0]
 
 export interface NimiqVitepressVitePluginOptions {
-  gitChangelog: GitChangelogOptions | false
+  /**
+   * GitHub repository URL (e.g., 'https://github.com/owner/repo')
+   * Used as default for GitChangelog and for constructing source code URLs
+   */
+  repoURL?: string
+
+  /**
+   * Content directory path relative to repository root
+   * Specifies where documentation files are located
+   * @default '' (repository root)
+   */
+  contentPath?: string
+
+  /**
+   * Git changelog configuration
+   * If not provided, will use repoURL as default
+   * Set to false to disable changelog
+   */
+  gitChangelog?: GitChangelogOptions | false
 }
 
-export async function NimiqVitepressVitePlugin({ gitChangelog }: NimiqVitepressVitePluginOptions): Promise<Plugin[]> {
+export async function NimiqVitepressVitePlugin({
+  repoURL,
+  contentPath = '',
+  gitChangelog,
+}: NimiqVitepressVitePluginOptions): Promise<Plugin[]> {
   const { resolveId, configureServer, load, transform } = groupIconVitePlugin()
 
   const externalPlugins: Plugin[] = []
 
+  // Configure GitChangelog with repoURL as default
   if (gitChangelog !== false) {
-    externalPlugins.push(GitChangelog(gitChangelog))
+    const changelogConfig = gitChangelog || (repoURL ? { repoURL } : {})
+    if (Object.keys(changelogConfig).length > 0) {
+      externalPlugins.push(GitChangelog(changelogConfig))
+    }
+  }
+
+  // Store configuration in Vite config for use in composables
+  const nimiqConfig = {
+    repoURL,
+    contentPath,
   }
 
   return [
@@ -26,6 +58,9 @@ export async function NimiqVitepressVitePlugin({ gitChangelog }: NimiqVitepressV
       load,
       transform,
       config: () => ({
+        define: {
+          __NIMIQ_VITEPRESS_CONFIG__: JSON.stringify(nimiqConfig),
+        },
         optimizeDeps: {
           exclude: [
             'nimiq-vitepress-theme',