Configuration Reference

Overview

The configuration system centralizes all settings, patterns, and constants used throughout the application. All configuration is defined in src/config.ts with proper TypeScript typing.

Core Configuration (`CONFIG` object)

File and Directory Settings

CONTENT_DIR: 'content'                    // Source directory for content files
ORG_FILE_EXTENSION: '.org'               // File extension for Org files
SUPPORTED_EXTENSIONS: ['.org'] as const  // Supported file extensions

Denote Pattern Matching

DENOTE_FILENAME_PATTERN: /^(\d{8}T\d{6})--(.+?)(?:__(.+?))?\.org$/
// Matches: YYYYMMDDTHHMMSS--title__tags.org
// Groups: [1] timestamp, [2] title, [3] tags (optional)

IDENTIFIER_PATTERN: /#+identifier:\s*(.+)/i
// Matches: #+identifier: TIMESTAMP
// Case insensitive, captures the identifier value

Cache Configuration

BACKLINKS_CACHE_TTL: 5 * 60 * 1000  // 5 minutes in milliseconds
// How long to cache backlinks index before rebuilding

Performance Limits

MAX_FILE_SIZE: 1024 * 1024        // 1MB max file size for processing
MAX_RETRY_ATTEMPTS: 3              // Maximum retry attempts for operations
RETRY_DELAY: 1000                  // 1 second delay between retries

Org-mode Specific

TODO_KEYWORDS: ['TODO', 'DONE', 'IN-PROGRESS', 'STARTED', 'WAITING', 'CANCELLED', 'CANCELED']
// Supported TODO keyword states

Type Definitions

DenoteFileInfo Interface

interface DenoteFileInfo {
  timestamp: string;    // YYYYMMDDTHHMMSS format
  title: string;        // Human-readable title
  tags?: string[];      // Optional tags array
  slug: string;         // URL-safe slug
  identifier?: string;  // Optional identifier
}

ProcessingError Interface

interface ProcessingError extends Error {
  code: string;      // Error code for categorization
  file?: string;     // File path where error occurred
  retryable: boolean; // Whether this error can be retried
}

Utility Functions

createProcessingError()

createProcessingError(
  message: string,      // Human-readable error message
  code: string,         // Error code (e.g., 'INVALID_IDENTIFIER')
  file?: string,        // Optional file path
  retryable = false     // Whether operation can be retried
): ProcessingError

Usage:

throw createProcessingError(
  'Invalid identifier format',
  'INVALID_IDENTIFIER',
  '/path/to/file.org',
  false
);

parseDenoteFilename()

parseDenoteFilename(filename: string): DenoteFileInfo | null

Usage:

const info = parseDenoteFilename('20250617T235902--config-reference__documentation.org');
// Returns:
// {
//   timestamp: '20250617T235902',
//   title: 'config reference',
//   tags: ['documentation'],
//   slug: 'config-reference'
// }

Astro Configuration (`astro.config.mjs`)

Basic Setup

import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
import pagefind from 'astro-pagefind';
import org from './src/lib/astro-org';

export default defineConfig({
  site: 'https://mayphus.org',
  integrations: [
    org({
      // Plugin configuration here
    }),
    sitemap(),
    pagefind()
  ],
  // Additional Astro configuration...
});

Org Integration Options

org({
  uniorgPlugins: [
    // Array of uniorg plugins to run before HTML conversion
  ],
  rehypePlugins: [
    // Array of rehype plugins to run after HTML conversion
  ]
})

Package.json Scripts

Development Scripts

{
  "dev": "astro dev",                    // Start development server
  "start": "astro dev",                  // Alias for dev
  "build": "astro check && astro build", // Build with type checking
  "preview": "astro preview"             // Preview built site
}

Deployment Scripts

{
  "deploy": "npm run build && wrangler deploy",  // Build and deploy to Cloudflare
  "dev:wrangler": "wrangler dev"                 // Local Cloudflare development
}

Quality Assurance Scripts

{
  "check": "astro check",              // Astro type checking
  "lint": "npx eslint src/ --ext .ts,.astro",  // Code linting
  "type-check": "tsc --noEmit",        // TypeScript type checking
  "validate": "npm run check && npm run type-check"  // Full validation
}

Content Management Scripts

{
  "sync": "./scripts/sync-content.sh",     // Sync content from external source
  "dev:sync": "npm run sync && npm run dev" // Sync and start development
}

Wrangler Configuration (`wrangler.jsonc`)

Basic Cloudflare Workers Setup

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "mayphus",
  "compatibility_date": "2025-06-05",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

ESLint Configuration (`.eslintrc.json`)

TypeScript and Astro Support

{
  "extends": [
    "eslint:recommended",
    "@typescript-eslint/recommended",
    "plugin:astro/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "rules": {
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "prefer-const": "error",
    "no-console": "warn"
  }
}

TypeScript Configuration (`tsconfig.json`)

Strict Configuration

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "strictNullChecks": true
  }
}

Environment Variables

Development (.dev.vars)

# Local development variables # (not committed to git) DEBUG=true LOCAL_CONTENT_PATH=/path/to/content

Production (Cloudflare Dashboard)

Set environment variables through Cloudflare Workers dashboard
No sensitive data should be in configuration files

Performance Tuning

Cache TTL Adjustment

// In src/config.ts
BACKLINKS_CACHE_TTL: 10 * 60 * 1000  // Increase to 10 minutes for better performance

Build Performance

// In astro.config.mjs
export default defineConfig({
  build: {
    inlineStylesheets: 'auto',  // Inline small CSS files
    split: true                 // Split large chunks
  },
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['astro', 'unified', 'rehype']
          }
        }
      }
    }
  }
});