Experiments

Experiments Scratchpad

Document code experiments, proof-of-concepts, and technical explorations.

Content Collection Experiments

Custom Schema Extension

Date: 2025-08-28

Goal: Explore extending Starlight’s schema for scratchpad-specific metadata.

// Potential content.config.ts extension
import { defineCollection } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

const scratchpadSchema = docsSchema().extend({
  category: z.enum(['idea', 'research', 'experiment', 'performance', 'deployment']),
  status: z.enum(['draft', 'active', 'completed', 'archived']).optional(),
  tags: z.array(z.string()).optional(),
  priority: z.enum(['low', 'medium', 'high']).optional(),
});

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  scratchpad: defineCollection({ loader: docsLoader(), schema: scratchpadSchema }),
};

Status: Experimental - needs validation with Astro build process Next Step: Test schema extension without breaking existing functionality

Development-Only Navigation

Date: 2025-08-28

Goal: Show scratchpad only in development environment.

// astro.config.mjs experiment
const isDevelopment = import.meta.env.DEV;

const sidebarItems = [
  {
    label: 'Getting Started',
    items: [{ label: 'Introduction', slug: 'introduction' }],
  },
  // ... other sections
];

// Add scratchpad only in development
if (isDevelopment) {
  sidebarItems.push({
    label: 'Scratchpad',
    items: [
      { label: 'Overview', slug: 'scratchpad' },
      { label: 'Ideas', slug: 'scratchpad/ideas' },
      { label: 'Research', slug: 'scratchpad/research' },
      // ... other scratchpad items
    ],
  });
}

Status: Theoretical - requires testing with Astro’s build process Consideration: May need different approach for static generation

GitHub Integration Experiments

Automated Issue Creation

Date: 2025-08-28

Goal: Script to convert scratchpad entries to GitHub issues.

#!/bin/bash
# scratchpad-to-issue.sh - Convert scratchpad entry to GitHub issue

SCRATCHPAD_FILE=$1
TITLE=$(grep "^### " "$SCRATCHPAD_FILE" | head -1 | sed 's/### //')
CONTENT=$(sed -n '/^### /,/^### /p' "$SCRATCHPAD_FILE" | sed '1d;$d')

gh issue create \
  --title "[From Scratchpad]: $TITLE" \
  --body "$CONTENT

Originated from scratchpad entry in: $SCRATCHPAD_FILE" \
  --label "scratchpad-origin"

Status: Proof-of-concept - needs refinement for production use Enhancement: Add template selection based on scratchpad category

Issue Template Enhancement

Date: 2025-08-28

Goal: Add scratchpad-specific issue template.

.github/ISSUE_TEMPLATE/scratchpad_conversion.yml

name: Scratchpad to Issue
description: Convert a scratchpad entry into a formal GitHub issue
title: "[Scratchpad]: "
labels: ["scratchpad-origin"]

body:
  - type: input
    id: scratchpad-source
    attributes:
      label: Scratchpad Source
      description: Which scratchpad file/section does this come from?
      placeholder: "scratchpad/ideas.md - Interactive Documentation"
    validations:
      required: true

  - type: textarea
    id: scratchpad-content
    attributes:
      label: Original Scratchpad Content
      description: Copy the relevant scratchpad entry here
    validations:
      required: true

  - type: textarea
    id: additional-context
    attributes:
      label: Additional Context
      description: Any new information or context since the scratchpad entry

Status: Ready for implementation Integration: Fits well with existing issue template system

Build Process Experiments

Conditional Content Generation

Date: 2025-08-28

Goal: Exclude scratchpad from production builds while keeping in development.

// Experimental build configuration
export default defineConfig({
  // ... other config
  vite: {
    define: {
      __DEV_SCRATCHPAD__: JSON.stringify(process.env.NODE_ENV === 'development'),
    },
  },
  integrations: [
    starlight({
      // ... existing config
      customCss: process.env.NODE_ENV === 'development'
        ? ['./src/styles/scratchpad-dev.css']
        : [],
    }),
  ],
});

Status: Experimental - needs validation with Cloudflare Pages build Risk: Static generation may not support runtime environment detection

Performance Experiments

Search Index Optimization

Date: 2025-08-28

Goal: Optimize Pagefind indexing for scratchpad content.

// Potential pagefind configuration
{
  "glob": "**/*.{html}",
  "exclude_selectors": [
    ".scratchpad-dev-only",
    ".private-note"
  ],
  "meta_selector": "meta[name='pagefind-meta']",
  "filters": {
    "section": "data-section"
  }
}

Research: Pagefind supports filtering and selective indexing Application: Could categorize scratchpad vs documentation in search results

---

Experiment Guidelines

Documentation Standards

1. Goal: Clear statement of what the experiment aims to achieve
2. Code/Config: Include relevant code snippets or configuration
3. Status: Current state (experimental, tested, ready, abandoned)
4. Next Steps: What needs to happen to move forward
5. Risks: Potential issues or limitations identified

Testing Approach

1. Create isolated test in feature branch
2. Validate with minimal reproduction case
3. Test integration with existing systems
4. Document results and learnings
5. Convert successful experiments to formal implementation

Integration Process

1. Move successful experiments to implementation todos
2. Create GitHub issues for complex experiments requiring formal development
3. Update documentation when experiments prove valuable
4. Archive unsuccessful experiments with lessons learned