refactor: externalize template files and introduce a fetching and registry system.

Author: DevRohit06

README.md

@@ -7,7 +7,7 @@ The open-source Mintlify alternative. Beautiful documentation sites from Markdow
 ✨ **Simple Setup** - Point to your docs folder and go
 🚀 **Astro-Powered** - Leverages Astro's speed and SEO optimization
 📝 **Markdown & MDX** - Full support for both formats with frontmatter
-🎨 **Responsive Design** - Mobile-friendly, beautiful documentation
+🎨 **Customizable Templates** - Use GitHub-hosted or local templates
 🔥 **Hot Reload** - Dev server with live file watching
 ⚡ **Fast Builds** - Static site generation for optimal performance
 🎯 **SEO Optimized** - Meta tags, semantic HTML, and proper structure
@@ -44,20 +44,10 @@ superdocs build --input ./my-docs --output ./dist
 
 - `-i, --input <path>` (required) - Path to your docs folder
 - `-o, --output <path>` - Output directory (default: `./dist`)
-- `-t, --theme <name>` - Theme to use (`default`, `dark`)
+- `-t, --template <name>` - Template to use (see [Templates](#templates))
 - `-b, --base-url <url>` - Base URL for the site (default: `/`)
 - `--search` - Enable search functionality
-
-**Example:**
-
-```bash
-superdocs build \
-  --input ./docs \
-  --output ./public \
-  --theme dark \
-  --base-url /docs/ \
-  --search
-```
+- `--refresh` - Force re-download template from GitHub
 
 ### Dev Command
 
@@ -70,32 +60,70 @@ superdocs dev --input ./my-docs
 **Options:**
 
 - `-i, --input <path>` (required) - Path to your docs folder
-- `-t, --theme <name>` - Theme to use
+- `-t, --template <name>` - Template to use
 - `-b, --base-url <url>` - Base URL for the site
 - `-p, --port <number>` - Port for dev server (default: `4321`)
 - `--search` - Enable search functionality
+- `--refresh` - Force re-download template
 
-**Example:**
+### Eject Command
+
+Export the full Astro project source code to customize it further:
 
 ```bash
-superdocs dev --input ./docs --port 3000
+superdocs eject --input ./my-docs --output ./my-project
 ```
 
-### Eject Command
+## Templates
 
-Export the full Astro project source code to customize it further:
+SuperDocs supports flexible template sources:
+
+### Default Template
 
 ```bash
-superdocs eject --input ./my-docs --output ./my-project
+superdocs dev -i ./docs
 ```
 
-**Options:**
+### GitHub Templates
 
-- `-i, --input <path>` (required) - Path to your docs folder
-- `-o, --output <path>` - Output directory for the project (default: `./astro-docs-project`)
-- `-t, --theme <name>` - Theme to use
-- `-b, --base-url <url>` - Base URL for the site
-- `--search` - Enable search functionality
+Use templates hosted on GitHub:
+
+```bash
+# From a GitHub repo
+superdocs dev -i ./docs --template github:owner/repo
+
+# Specific branch or tag
+superdocs dev -i ./docs --template github:owner/repo#v1.0.0
+
+# Template in a subdirectory
+superdocs dev -i ./docs --template github:owner/repo/templates/modern
+```
+
+### Local Templates
+
+Use a local template folder:
+
+```bash
+superdocs dev -i ./docs --template ./my-custom-template
+```
+
+### Template Management
+
+```bash
+# List available templates
+superdocs template list
+
+# Clear template cache
+superdocs template cache --clear
+```
+
+### Update Templates
+
+Templates are cached for 24 hours. Force update with:
+
+```bash
+superdocs dev -i ./docs --refresh
+```
 
 ## Documentation Structure
 
@@ -131,11 +159,12 @@ Your content here...
 
 The CLI tool:
 
-1. **Scaffolds** - Creates a temporary Astro project from an internal template
-2. **Syncs** - Copies your docs into `src/pages/` for automatic routing
-3. **Configures** - Generates dynamic `astro.config.mjs` with your options
-4. **Builds/Serves** - Spawns native Astro CLI commands (`astro build` or `astro dev`)
-5. **Watches** (dev mode) - Uses `chokidar` to monitor file changes
+1. **Resolves Template** - Fetches from GitHub or uses local template
+2. **Scaffolds** - Creates a temporary Astro project from the template
+3. **Syncs** - Copies your docs into `src/pages/` for automatic routing
+4. **Configures** - Generates dynamic `astro.config.mjs` with your options
+5. **Builds/Serves** - Spawns native Astro CLI commands
+6. **Watches** (dev mode) - Uses `chokidar` to monitor file changes
 
 ## Development
 
@@ -150,18 +179,16 @@ superdocs/
 │   ├── commands/
 │   │   ├── build.js        # Build command
 │   │   ├── dev.js          # Dev command with watcher
-│   │   └── eject.js        # Eject command
+│   │   ├── eject.js        # Eject command
+│   │   └── template.js     # Template management
 │   ├── core/
 │   │   ├── scaffold.js     # Project scaffolding
 │   │   ├── sync.js         # File syncing
 │   │   ├── config.js       # Config generation
 │   │   ├── astro.js        # Astro CLI spawning
-│   │   └── output.js       # Output copying
-│   └── template/           # Internal Astro template
-│       ├── src/
-│       │   ├── layouts/
-│       │   └── pages/
-│       └── package.json
+│   │   ├── template-fetcher.js   # GitHub template fetching
+│   │   └── template-registry.js  # Template name registry
+│   └── template/           # Bundled fallback template
 └── package.json
 ```
 

src/cli.js

@@ -3,6 +3,7 @@ import pc from 'picocolors';
 import { buildCommand } from './commands/build.js';
 import { devCommand } from './commands/dev.js';
 import { ejectCommand } from './commands/eject.js';
+import { templateListCommand, templateCacheCommand } from './commands/template.js';
 
 export async function cli() {
   const program = new Command();
@@ -17,31 +18,50 @@ export async function cli() {
     .description('Build the documentation site')
     .requiredOption('-i, --input <path>', 'Path to the docs folder')
     .option('-o, --output <path>', 'Output directory for the built site', './dist')
-    .option('-t, --theme <name>', 'Theme to use', 'default')
+    .option('-t, --template <name>', 'Template to use (default, github:owner/repo, or local path)', 'default')
     .option('-b, --base-url <url>', 'Base URL for the site', '/')
     .option('--search', 'Enable search functionality', false)
+    .option('--refresh', 'Force re-download template (bypass cache)', false)
     .action(buildCommand);
 
   program
     .command('dev')
     .description('Start development server with watch mode')
     .requiredOption('-i, --input <path>', 'Path to the docs folder')
-    .option('-t, --theme <name>', 'Theme to use', 'default')
+    .option('-t, --template <name>', 'Template to use (default, github:owner/repo, or local path)', 'default')
     .option('-b, --base-url <url>', 'Base URL for the site', '/')
     .option('--search', 'Enable search functionality', false)
     .option('-p, --port <number>', 'Port for dev server', '4321')
+    .option('--refresh', 'Force re-download template (bypass cache)', false)
     .action(devCommand);
 
   program
     .command('eject')
     .description('Export the full Astro project source code')
     .requiredOption('-i, --input <path>', 'Path to the docs folder')
     .option('-o, --output <path>', 'Output directory for the project', './astro-docs-project')
-    .option('-t, --theme <name>', 'Theme to use', 'default')
+    .option('-t, --template <name>', 'Template to use (default, github:owner/repo, or local path)', 'default')
     .option('-b, --base-url <url>', 'Base URL for the site', '/')
     .option('--search', 'Enable search functionality', false)
+    .option('--refresh', 'Force re-download template (bypass cache)', false)
     .action(ejectCommand);
 
+  // Template management commands
+  const templateCmd = program
+    .command('template')
+    .description('Manage documentation templates');
+
+  templateCmd
+    .command('list')
+    .description('List available templates')
+    .action(templateListCommand);
+
+  templateCmd
+    .command('cache')
+    .description('Manage template cache')
+    .option('--clear', 'Clear all cached templates')
+    .action(templateCacheCommand);
+
   try {
     await program.parseAsync(process.argv);
   } catch (error) {

src/commands/build.js

@@ -8,6 +8,7 @@ import { generateConfig } from '../core/config.js';
 import { runAstroBuild } from '../core/astro.js';
 import { syncDocsConfig } from '../core/config-sync.js';
 import { copyOutput } from '../core/output.js';
+import { getTemplatePath } from '../core/template-fetcher.js';
 
 export async function buildCommand(options) {
   try {
@@ -23,9 +24,14 @@ export async function buildCommand(options) {
 
     const s = spinner();
 
+    // Step 0: Resolve template
+    s.start('Resolving template...');
+    const templatePath = await getTemplatePath(options.template, options.refresh);
+    s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
+
     // Step 1: Scaffold temporary Astro project
     s.start('Setting up Astro project...');
-    const projectDir = await scaffoldProject();
+    const projectDir = await scaffoldProject(templatePath);
     s.stop('Astro project scaffolded');
 
     // Step 2: Install dependencies

src/commands/dev.js

@@ -8,6 +8,7 @@ import { syncDocs } from '../core/sync.js';
 import { generateConfig } from '../core/config.js';
 import { runAstroDev } from '../core/astro.js';
 import { syncDocsConfig } from '../core/config-sync.js';
+import { getTemplatePath } from '../core/template-fetcher.js';
 
 export async function devCommand(options) {
   try {
@@ -23,9 +24,14 @@ export async function devCommand(options) {
 
     const s = spinner();
 
+    // Step 0: Resolve template
+    s.start('Resolving template...');
+    const templatePath = await getTemplatePath(options.template, options.refresh);
+    s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
+
     // Step 1: Scaffold temporary Astro project
     s.start('Setting up Astro project...');
-    const projectDir = await scaffoldProject();
+    const projectDir = await scaffoldProject(templatePath);
     s.stop('Astro project scaffolded');
 
     // Register cleanup handlers

src/commands/eject.js

@@ -7,6 +7,7 @@ import { scaffoldProject, cleanupProject } from '../core/scaffold.js';
 import { syncDocs } from '../core/sync.js';
 import { generateConfig } from '../core/config.js';
 import { syncDocsConfig } from '../core/config-sync.js';
+import { getTemplatePath } from '../core/template-fetcher.js';
 
 export async function ejectCommand(options) {
   try {
@@ -29,9 +30,14 @@ export async function ejectCommand(options) {
 
     const s = spinner();
 
+    // Step 0: Resolve template
+    s.start('Resolving template...');
+    const templatePath = await getTemplatePath(options.template, options.refresh);
+    s.stop(templatePath ? `Using template: ${pc.cyan(templatePath)}` : 'Using bundled template');
+
     // Step 1: Scaffold temporary Astro project
     s.start('Scaffolding Astro project...');
-    const projectDir = await scaffoldProject();
+    const projectDir = await scaffoldProject(templatePath);
     s.stop('Astro project scaffolded');
 
     // Step 2: Sync docs to Astro

src/commands/template.js

@@ -0,0 +1,80 @@
+import { intro, outro, spinner, log, note } from '@clack/prompts';
+import pc from 'picocolors';
+import { listCachedTemplates, clearTemplateCache } from '../core/template-fetcher.js';
+import { getRegistryNames, getRegistryInfo } from '../core/template-registry.js';
+
+/**
+ * List available templates
+ */
+export async function templateListCommand() {
+    intro(pc.inverse(pc.cyan(' SuperDocs - Templates ')));
+
+    // Show registry templates
+    const names = getRegistryNames();
+
+    log.info(pc.bold('Available Templates:'));
+    console.log('');
+
+    for (const name of names) {
+        const info = getRegistryInfo(name);
+        console.log(`  ${pc.blue('●')} ${pc.bold(name)} ${pc.dim(`→ ${info.source}`)}`);
+    }
+
+    console.log('');
+    log.info(pc.dim('You can also use GitHub URLs directly:'));
+    console.log(pc.dim('  superdocs dev -i . --template github:owner/repo'));
+    console.log(pc.dim('  superdocs dev -i . --template github:owner/repo#v1.0.0'));
+    console.log('');
+
+    // Show cached templates
+    const cached = await listCachedTemplates();
+    if (cached.length > 0) {
+        log.info(pc.bold('Cached Templates:'));
+        console.log('');
+        for (const t of cached) {
+            const age = Math.round((Date.now() - t.cachedAt) / (1000 * 60));
+            console.log(`  ${pc.yellow('●')} ${t.owner}/${t.repo}#${t.ref} ${pc.dim(`(cached ${age}m ago)`)}`);
+        }
+        console.log('');
+    }
+
+    outro(pc.dim('Use --template to select a template'));
+}
+
+/**
+ * Manage template cache
+ */
+export async function templateCacheCommand(options) {
+    intro(pc.inverse(pc.cyan(' SuperDocs - Template Cache ')));
+
+    if (options.clear) {
+        const s = spinner();
+        s.start('Clearing template cache...');
+        await clearTemplateCache();
+        s.stop('Template cache cleared');
+        outro(pc.green('Done!'));
+        return;
+    }
+
+    // Show cache info
+    const cached = await listCachedTemplates();
+
+    if (cached.length === 0) {
+        log.info('No templates cached.');
+        outro('');
+        return;
+    }
+
+    log.info(pc.bold(`${cached.length} template(s) cached:`));
+    console.log('');
+
+    for (const t of cached) {
+        const age = Math.round((Date.now() - t.cachedAt) / (1000 * 60 * 60));
+        console.log(`  ${pc.cyan(t.owner)}/${pc.cyan(t.repo)}#${pc.yellow(t.ref)}`);
+        console.log(`    ${pc.dim(`Cached ${age}h ago`)}`);
+    }
+
+    console.log('');
+    note('superdocs template cache --clear', 'To clear cache');
+    outro('');
+}

src/core/scaffold.js

@@ -11,7 +11,7 @@ const __dirname = dirname(__filename);
 // Use a consistent directory path instead of random temp directories
 const SUPERDOCS_DIR = join(tmpdir(), '.superdocs');
 
-export async function scaffoldProject() {
+export async function scaffoldProject(customTemplatePath = null) {
   // Ensure the directory exists (creates if it doesn't)
   await ensureDir(SUPERDOCS_DIR);
 
@@ -20,8 +20,8 @@ export async function scaffoldProject() {
 
   const tempDir = SUPERDOCS_DIR;
 
-  // Copy template to temp directory, excluding node_modules and lock files
-  const templatePath = join(__dirname, '../template');
+  // Use custom template path if provided, otherwise use bundled template
+  const templatePath = customTemplatePath || join(__dirname, '../template');
   await copy(templatePath, tempDir, {
     filter: (src) => {
       const name = basename(src);