Integrate markdown guides into phpDocumentor output

Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.

- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jonathanhefner

.github/workflows/docs.yml

@@ -24,15 +24,12 @@ jobs:
       - name: Install Composer
         uses: "ramsey/composer-install@v3"
 
-      - name: Generate API Documentation
+      - name: Generate Documentation
         run: make docs
 
-      - name: Copy API docs into docs directory
-        run: cp -r build/docs docs/api
-
       - name: Deploy to gh-pages branch
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
-          enable_jekyll: true
+          publish_dir: ./build/docs
+          enable_jekyll: false

.gitignore

@@ -10,5 +10,5 @@ results
 
 # phpDocumentor
 build/
-.phpdoc/
+.phpdoc/cache/
 phpDocumentor.phar

.phpdoc/template/base.html.twig

@@ -0,0 +1,8 @@
+{% extends 'layout.html.twig' %}
+
+{% set topMenu = {
+    "menu": [
+        { "name": "Guides", "url": "guide/docs/index.html"}
+    ]
+}
+%}

docs/_config.yml

@@ -0,0 +1,7 @@
+# MCP PHP SDK Guides
+
+- [MCP Elements](mcp-elements.html) — Core capabilities (Tools, Resources, Resource Templates, and Prompts) with registration methods.
+- [Server Builder](server-builder.html) — Fluent builder class for creating and configuring MCP server instances.
+- [Transports](transports.html) — STDIO and HTTP transport implementations with guidance on choosing between them.
+- [Client Communication](client-communication.html) — Methods for servers to communicate back to clients: sampling, logging, progress, and notifications.
+- [Examples](examples.html) — Example projects demonstrating attribute-based discovery, dependency injection, HTTP transport, and more.

docs/index.html

@@ -20,6 +20,13 @@
                 <path>tests/**/*</path>
             </ignore>
         </api>
+        <guide format="md">
+            <source dsn=".">
+                <path>docs</path>
+            </source>
+            <output>guide</output>
+        </guide>
     </version>
+    <setting name="guides.enabled" value="true"/>
     <setting name="graphs.enabled" value="true"/>
 </phpdocumentor>