Refactor documentation for clarity and structure

[danielmarv]

• Updated "05 - Testing and Quality Checks" to provide a comprehensive overview of quality assurance processes, including mandatory checks, linting, build verification, E2E testing, and manual verification.
• Enhanced "06 - GitHub Automation Guide" with detailed explanations of automation commands, workflows, and status label synchronization for issues and PRs.
• Revamped "README.md" to improve organization, target audience clarity, and provide a structured reading path for first-time contributors, including a comprehensive overview of documentation architecture and common workflow patterns.

[Copilot]

Pull request overview

This pull request comprehensively refactors the contributor documentation in the docs/ directory, transforming brief guides into detailed, structured references. The updates aim to improve onboarding experience, clarify workflows, and provide comprehensive technical guidance for contributors to the Open Elements Next.js website project.

Changes:

• Enhanced documentation structure with detailed sections, tables, examples, and troubleshooting guidance across all seven documentation files
• Expanded testing and quality checks guide (05) to include comprehensive validation procedures, common failure patterns, and debugging workflows
• Detailed GitHub automation guide (06) documenting issue commands, PR workflows, status label synchronization, and troubleshooting automation issues

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
docs/README.md	Restructured as comprehensive entry point with target audience definitions, documentation architecture table, recommended reading paths, and workflow patterns
docs/06-github-automation.md	Expanded from basic overview to detailed guide covering issue commands, PR automation, status labels, configuration, and troubleshooting
docs/05-testing-and-quality-checks.md	Enhanced with comprehensive quality assurance philosophy, mandatory checks, E2E testing guidance, manual verification checklists, and common failure patterns
docs/04-first-contribution-checklist.md	Transformed into phase-based workflow guide with detailed setup, branching, validation, PR creation, and review collaboration steps
docs/03-adding-pages.md	Expanded with step-by-step implementation workflow, code examples, content templates, and PR submission expectations
docs/02-content-folder.md	Enhanced with comprehensive content organization patterns, front matter standards, localization guidelines, and URL/SEO best practices
docs/01-repo-overview.md	Expanded with detailed technology stack, directory structure, content architecture, development setup, and contribution principles

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The reference to content/en and content/de directories is incorrect. The codebase doesn't use separate language directories. Instead, localization is achieved through file naming conventions:

• English: index.md, <name>.md
• German: index.de.md, <name>.de.md

This is already correctly documented in 02-content-folder.md. The text should be revised to reflect the actual file-naming approach rather than directory-based organization.

Suggested change

	- **Consistent Structure**: Keep directory structure and file naming consistent between `content/en` and `content/de` concepts
	- **Consistent Structure**: Keep file naming consistent between English and German content (e.g. `index.md`/`index.de.md`, `<name>.md`/`<name>.de.md`)

[Copilot]

The type Page is referenced but doesn't appear to be defined in the codebase. Looking at src/lib/markdown.ts, the actual types are PostData and PostFrontmatter. This example code won't compile and will mislead contributors trying to implement new pages.

[Copilot]

Spelling error: "parityBetween" should be "parity between" (missing space between words).

Suggested change

	- Pages visible to end users must maintain structural parityBetween English and German
	- Pages visible to end users must maintain structural parity between English and German

[Copilot]

Spelling error: There is an extra space before "Fix" creating " Fix" instead of "Fix" in the heading.

Suggested change

	** Fix**:
	**Fix**:

[Copilot]

The code example is missing the await for params. Based on the actual codebase patterns, the code should be:

export async function generateMetadata(
  { params }: PageProps
): Promise<Metadata> {
  const { locale } = await params;  // Need to await params
  
  // Load content to extract metadata
  const content: Page | null = await getPageContent('faq', locale);
  // ... rest of code
}

This is the pattern used consistently in src/app/[locale]/layout.tsx, src/app/[locale]/posts/[slug]/page.tsx, and other page files.

Suggested change

	const locale = params.locale;
	const { locale } = await params;

[Copilot]

The code example is missing the await for params. The Page component should be:

export default async function Page({ params }: PageProps): Promise<ReactNode> {
  const { locale } = await params;  // Need to await params
  
  // Load page content
  const content = await getPageContent('faq', locale);
  // ... rest of code
}

This pattern is consistently used across the codebase (see src/app/[locale]/impressum/page.tsx, src/app/[locale]/newsletter/page.tsx, etc.).

[Copilot]

The bash command uses incorrect escaping. In a bash code block, the square brackets don't need to be escaped with backslashes. The command should be:

mkdir -p src/app/[locale]/faq

The backslashes are only needed in some shell contexts where brackets have special meaning, but in this case they would create a directory literally named \[locale\] instead of [locale].

Suggested change

	mkdir -p src/app/\[locale\]/faq
	mkdir -p src/app/[locale]/faq

[Copilot]

The function getPageContent doesn't exist in the codebase. Looking at src/lib/markdown.ts, the actual functions available are:

• getPostBySlug(slug: string, locale: string)
• getAllPosts(locale: string)
• getAllPostSlugs()
• postExistsForLocale(slug: string, locale: string)

The code example should either:

1. Use an actual function from the codebase, or
2. Clearly indicate this is pseudocode/example and contributors should adapt it to their needs, or
3. Provide guidance on creating such a function if it doesn't exist

As written, this will confuse contributors who try to follow the example literally.

[Copilot]

The relative path to GitHub workflows is incorrect. The path should be ../.github/workflows since the docs folder is at the root level, and .github is at the repository root. The current path .github/workflows would only work if there was a .github folder inside the docs/ directory.

Suggested change

	- **[GitHub Workflows](.github/workflows)** - Automated CI/CD pipeline definitions
	- **[GitHub Workflows](../.github/workflows)** - Automated CI/CD pipeline definitions

[Copilot]

The TypeScript interface for PageProps is incorrect. In the actual codebase, params is a Promise that needs to be awaited. The interface should be:

interface PageProps {
  params: Promise<{
    locale: string;
  }>;
}

And then in the generateMetadata function, you need to await the params:

export async function generateMetadata(
  { params }: PageProps
): Promise<Metadata> {
  const { locale } = await params;
  // ... rest of the code
}

This pattern is consistently used throughout the codebase (see src/app/[locale]/layout.tsx, src/app/[locale]/impressum/page.tsx, etc.).