Docs: Documentation site for the project

[krokoko]

Describe the feature

Provide a documentation site for the Agent Plugins for AWS project so that design guidelines, development and maintainer guides, plugin/skill authoring, and API/schema references are available in a structured, navigable, and (optionally) versioned form, separate from raw Markdown in the repo.

Desired capabilities (to be refined):

• Publish existing docs/ content (e.g. DESIGN_GUIDELINES, DEVELOPMENT_GUIDE, MAINTAINERS_GUIDE, TROUBLESHOOTING) as a coherent site.
• Clear navigation and optional search.
• Optionally: versioned docs tied to releases or branches.
• Optionally: schema reference (e.g. plugin, marketplace, MCP, skill frontmatter) generated or included so plugin authors can look up fields and validation in one place.

The exact scope (static site generator, hosting, versioning) can be decided during implementation.

Use Case

• Discoverability: New contributors and plugin authors often land on the repo; a dedicated docs site (e.g. agent-plugins.github.io or a subpath on an existing AWS/OSS site) makes it easier to find “how to design a plugin” or “how to add a new skill” without digging through the repo tree.
• Consistency: A single site can present design guidelines, schemas, and examples in a uniform layout and style.
• Onboarding: Maintainers and reviewers can point to “the docs site” for design checklist, review criteria, and troubleshooting instead of multiple Markdown links.

Proposed Solution

1. Choose a static site generator

   • Options: MkDocs (with Material theme), Docusaurus, VitePress, or similar. Prefer something that renders Markdown well, supports navigation from a config file, and can be built in CI (e.g. GitHub Actions).

2. Content source

   • Keep source of truth in the repo (e.g. docs/*.md). The generator reads from docs/ (and optionally schemas/ or generated schema docs). Avoid duplicating content; the site is “built from” the repo.

3. Navigation and structure

   • Define a nav/sidebar (e.g. Design Guidelines, Development, Maintainers, Troubleshooting, Schemas/Reference). Map existing docs to sections.

4. Build and deploy

   • Add a workflow (e.g. on push to main or a docs branch) that builds the site and deploys to GitHub Pages or another host. If the repo already uses GitHub Pages, use a branch or path (e.g. /docs) for the site.

5. Optional

   • Schema reference: add a step or script that generates HTML or Markdown from schemas/*.json (e.g. with a schema-doc generator) and include it in the site.
   • Versioning: if useful, build docs from the default branch and optionally from release tags so “latest” and “v1.0” are both available.

Other Information

• Existing docs live in docs/ (DESIGN_GUIDELINES.md, DEVELOPMENT_GUIDE.md, MAINTAINERS_GUIDE.md, TROUBLESHOOTING.md). Schemas are in schemas/. No new content duplication is desired; the site should reflect the repo.
• Consider link-checking in CI so internal links in the built site stay valid.
• If the project is under an AWS org, check whether there is a standard place or template for OSS doc sites (e.g. GitHub Pages, Read the Docs, or an internal docs pipeline).

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change