astro-discovery/docs/create-placeholders.js

#!/usr/bin/env node
import { writeFileSync, mkdirSync } from 'fs';
import { dirname } from 'path';

const pages = [
  // Getting Started
  {
    path: 'getting-started/first-steps.md',
    title: 'First Steps',
    description: 'Learn the basics of using @astrojs/discovery',
    content: 'This guide covers the fundamental concepts and first steps with @astrojs/discovery.'
  },

  // Tutorials
  {
    path: 'tutorials/basic-setup.md',
    title: 'Basic Setup',
    description: 'Set up @astrojs/discovery with default configuration',
    content: 'Learn how to set up @astrojs/discovery with the default configuration for immediate use.'
  },
  {
    path: 'tutorials/configure-robots.md',
    title: 'Configure robots.txt',
    description: 'Customize your robots.txt file',
    content: 'Learn how to configure robots.txt to control search engine and bot crawling behavior.'
  },
  {
    path: 'tutorials/setup-llms.md',
    title: 'Setup llms.txt',
    description: 'Configure AI assistant discovery and instructions',
    content: 'Set up llms.txt to help AI assistants understand and interact with your site.'
  },
  {
    path: 'tutorials/create-humans.md',
    title: 'Create humans.txt',
    description: 'Add team credits and tech stack information',
    content: 'Learn how to create a humans.txt file to credit your team and document your tech stack.'
  },
  {
    path: 'tutorials/security-canary.md',
    title: 'Security & Canary Files',
    description: 'Set up security.txt and canary.txt',
    content: 'Configure security contact information and warrant canaries for transparency.'
  },
  {
    path: 'tutorials/webfinger.md',
    title: 'WebFinger Discovery',
    description: 'Enable WebFinger resource discovery',
    content: 'Set up WebFinger for ActivityPub, OpenID Connect, and other federated protocols.'
  },

  // How-to Guides
  {
    path: 'how-to/block-bots.md',
    title: 'Block Specific Bots',
    description: 'How to block unwanted bots from crawling your site',
    content: 'Learn how to block specific bots or user agents from accessing your site.'
  },
  {
    path: 'how-to/customize-llm-instructions.md',
    title: 'Customize LLM Instructions',
    description: 'Provide specific instructions for AI assistants',
    content: 'Create custom instructions for AI assistants to follow when helping users with your site.'
  },
  {
    path: 'how-to/add-team-members.md',
    title: 'Add Team Members',
    description: 'Add team member information to humans.txt',
    content: 'Learn how to add team members and collaborators to your humans.txt file.'
  },
  {
    path: 'how-to/filter-sitemap.md',
    title: 'Filter Sitemap Pages',
    description: 'Control which pages appear in your sitemap',
    content: 'Configure filtering to control which pages are included in your sitemap.'
  },
  {
    path: 'how-to/cache-headers.md',
    title: 'Set Cache Headers',
    description: 'Configure HTTP caching for discovery files',
    content: 'Optimize cache headers for discovery files to balance freshness and performance.'
  },
  {
    path: 'how-to/environment-config.md',
    title: 'Environment-specific Configuration',
    description: 'Use different configs for dev and production',
    content: 'Configure different settings for development and production environments.'
  },
  {
    path: 'how-to/content-collections.md',
    title: 'Use with Content Collections',
    description: 'Integrate with Astro content collections',
    content: 'Automatically generate discovery content from your Astro content collections.'
  },
  {
    path: 'how-to/custom-templates.md',
    title: 'Custom Templates',
    description: 'Create custom templates for discovery files',
    content: 'Override default templates to fully customize the output of discovery files.'
  },
  {
    path: 'how-to/activitypub.md',
    title: 'ActivityPub Integration',
    description: 'Connect with the Fediverse via WebFinger',
    content: 'Set up ActivityPub integration to make your site discoverable on Mastodon and the Fediverse.'
  },

  // Reference
  {
    path: 'reference/configuration.md',
    title: 'Configuration Options',
    description: 'Complete reference for all configuration options',
    content: 'Comprehensive reference documentation for all available configuration options.'
  },
  {
    path: 'reference/api.md',
    title: 'API Reference',
    description: 'API and programmatic interface reference',
    content: 'Complete API reference for programmatic usage of @astrojs/discovery.'
  },
  {
    path: 'reference/robots.md',
    title: 'robots.txt Options',
    description: 'Configuration reference for robots.txt',
    content: 'Detailed reference for all robots.txt configuration options and behaviors.'
  },
  {
    path: 'reference/llms.md',
    title: 'llms.txt Options',
    description: 'Configuration reference for llms.txt',
    content: 'Complete reference for llms.txt configuration options and structure.'
  },
  {
    path: 'reference/humans.md',
    title: 'humans.txt Options',
    description: 'Configuration reference for humans.txt',
    content: 'Full reference for humans.txt configuration and formatting options.'
  },
  {
    path: 'reference/security.md',
    title: 'security.txt Options',
    description: 'Configuration reference for security.txt (RFC 9116)',
    content: 'RFC 9116 compliant security.txt configuration reference.'
  },
  {
    path: 'reference/canary.md',
    title: 'canary.txt Options',
    description: 'Configuration reference for canary.txt',
    content: 'Complete reference for warrant canary configuration options.'
  },
  {
    path: 'reference/webfinger.md',
    title: 'WebFinger Options',
    description: 'Configuration reference for WebFinger (RFC 7033)',
    content: 'RFC 7033 compliant WebFinger configuration reference.'
  },
  {
    path: 'reference/sitemap.md',
    title: 'Sitemap Options',
    description: 'Configuration reference for sitemap generation',
    content: 'Reference for sitemap configuration options (passed to @astrojs/sitemap).'
  },
  {
    path: 'reference/cache.md',
    title: 'Cache Options',
    description: 'HTTP caching configuration reference',
    content: 'Configure cache control headers for all discovery files.'
  },
  {
    path: 'reference/typescript.md',
    title: 'TypeScript Types',
    description: 'TypeScript type definitions and interfaces',
    content: 'Complete TypeScript type reference for configuration and APIs.'
  },

  // Explanation
  {
    path: 'explanation/why-discovery.md',
    title: 'Why Use Discovery Files?',
    description: 'Understanding the importance of discovery files',
    content: 'Learn why discovery files are essential for modern websites and their benefits.'
  },
  {
    path: 'explanation/robots-explained.md',
    title: 'Understanding robots.txt',
    description: 'Deep dive into robots.txt and its purpose',
    content: 'Comprehensive explanation of robots.txt, its history, and modern usage.'
  },
  {
    path: 'explanation/llms-explained.md',
    title: 'Understanding llms.txt',
    description: 'What is llms.txt and why it matters',
    content: 'Learn about the llms.txt specification and how it helps AI assistants.'
  },
  {
    path: 'explanation/humans-explained.md',
    title: 'Understanding humans.txt',
    description: 'The human side of discovery files',
    content: 'Explore the humans.txt initiative and how it credits the people behind websites.'
  },
  {
    path: 'explanation/security-explained.md',
    title: 'Security.txt Standard (RFC 9116)',
    description: 'Understanding the security.txt RFC',
    content: 'Learn about RFC 9116 and why security.txt is important for responsible disclosure.'
  },
  {
    path: 'explanation/canary-explained.md',
    title: 'Warrant Canaries',
    description: 'Understanding warrant canaries and transparency',
    content: 'Learn how warrant canaries work and their role in organizational transparency.'
  },
  {
    path: 'explanation/webfinger-explained.md',
    title: 'WebFinger Protocol (RFC 7033)',
    description: 'Understanding WebFinger resource discovery',
    content: 'Deep dive into the WebFinger protocol and its role in federated identity.'
  },
  {
    path: 'explanation/seo.md',
    title: 'SEO & Discoverability',
    description: 'How discovery files improve SEO',
    content: 'Understand how properly configured discovery files enhance search engine optimization.'
  },
  {
    path: 'explanation/ai-integration.md',
    title: 'AI Assistant Integration',
    description: 'How AI assistants use discovery files',
    content: 'Learn how AI assistants discover and use information from your site.'
  },
  {
    path: 'explanation/architecture.md',
    title: 'Architecture & Design',
    description: 'How @astrojs/discovery works internally',
    content: 'Technical explanation of the integration architecture and design decisions.'
  },

  // Examples
  {
    path: 'examples/ecommerce.md',
    title: 'E-commerce Site',
    description: 'Complete example for an e-commerce website',
    content: 'Full configuration example for an e-commerce site with product catalogs and APIs.'
  },
  {
    path: 'examples/documentation.md',
    title: 'Documentation Site',
    description: 'Example configuration for docs sites',
    content: 'Configuration example optimized for technical documentation websites.'
  },
  {
    path: 'examples/blog.md',
    title: 'Personal Blog',
    description: 'Example for personal blogs',
    content: 'Simple configuration example for personal blogs and content sites.'
  },
  {
    path: 'examples/api-platform.md',
    title: 'API Platform',
    description: 'Example for API-first platforms',
    content: 'Configuration example for API platforms with extensive endpoint documentation.'
  },
  {
    path: 'examples/multilanguage.md',
    title: 'Multi-language Site',
    description: 'Example for internationalized sites',
    content: 'Configuration example for sites with multiple languages and locales.'
  },
  {
    path: 'examples/federated-social.md',
    title: 'Federated Social Profile',
    description: 'Example for ActivityPub/Mastodon integration',
    content: 'Complete example for setting up federated social profiles with WebFinger.'
  },

  // Community
  {
    path: 'community/contributing.md',
    title: 'Contributing',
    description: 'How to contribute to @astrojs/discovery',
    content: 'Guidelines for contributing to the @astrojs/discovery project.'
  },
  {
    path: 'community/changelog.md',
    title: 'Changelog',
    description: 'Version history and changes',
    content: 'Complete changelog of all versions and changes to @astrojs/discovery.'
  },
  {
    path: 'community/troubleshooting.md',
    title: 'Troubleshooting',
    description: 'Common issues and solutions',
    content: 'Solutions to common issues and problems when using @astrojs/discovery.'
  },
  {
    path: 'community/faq.md',
    title: 'FAQ',
    description: 'Frequently asked questions',
    content: 'Answers to frequently asked questions about @astrojs/discovery.'
  },
];

const baseDir = 'src/content/docs';

pages.forEach(page => {
  const fullPath = `${baseDir}/${page.path}`;
  const dir = dirname(fullPath);

  // Create directory if it doesn't exist
  mkdirSync(dir, { recursive: true });

  // Create markdown content
  const content = `---
title: ${page.title}
description: ${page.description}
---

${page.content}

:::note[Work in Progress]
This page is currently being developed. Check back soon for complete documentation.
:::

## Coming Soon

This section will include:
- Detailed explanations
- Code examples
- Best practices
- Common patterns
- Troubleshooting tips

## Related Pages

- [Configuration Reference](/reference/configuration/)
- [API Reference](/reference/api/)
- [Examples](/examples/ecommerce/)

## Need Help?

- Check our [FAQ](/community/faq/)
- Visit [Troubleshooting](/community/troubleshooting/)
- Open an issue on [GitHub](https://github.com/withastro/astro-discovery/issues)
`;

  writeFileSync(fullPath, content);
  console.log(`✅ Created: ${fullPath}`);
});

console.log(`\n🎉 Created ${pages.length} placeholder pages!`);