Use Source Code Snippets from pepr-excellent-examples Instead of README Mirrors

[samayer12]

Description

Code snippets in the pepr-excellent-examples README files are manually maintained copies of the actual source code. This creates a maintenance burden and risks the documentation becoming outdated when code changes. The build process should extract code snippets directly from the source files to ensure they're always current.

Current approach:

• Example README files contain manually copied code snippets
• Developers must remember to update README snippets when code changes
• No automated verification that README snippets match actual source code
• Risk of documentation drift over time

Problems:

• Manual synchronization required - Code changes require updating both source files and README snippets
• Documentation can become stale - Easy to forget to update README when refactoring code
• No single source of truth - Code exists in two places (source files and README)
• Maintenance overhead - Double the work for every code change
• Quality risk - Users may copy outdated or incorrect code from examples

Proposed solution:
Implement automated code snippet extraction during the build process

Alternative approaches:

• Use existing tools like remark-code-import or similar plugins
• Implement custom Astro/Starlight plugin for code inclusion
• Use GitHub's raw file URLs with fetch during build

Related Files

• https://github.com/defenseunicorns/pepr-docs/blob/main/scripts/index.mjs (lines 419-485)
• https://github.com/defenseunicorns/pepr-docs/blob/main/scripts/lib/examples-processing.mjs
• https://github.com/defenseunicorns/pepr-excellent-examples (external repository - all example directories)

Definition of Done

Code snippets from PEXEX that appear in the docs are always up to date.

Benefits:

• Always current documentation - Code snippets automatically reflect latest source
• Single source of truth - Code only exists in source files
• Reduced maintenance - No need to manually sync README with code changes
• Better quality - Users always get working, up-to-date examples
• Easier refactoring - Code changes automatically propagate to documentation