diff --git a/.vitepress/sidebars/guides.ts b/.vitepress/sidebars/guides.ts index 3829afc..dc4adea 100644 --- a/.vitepress/sidebars/guides.ts +++ b/.vitepress/sidebars/guides.ts @@ -2,7 +2,7 @@ import type { DefaultTheme } from "vitepress"; export const guidesSidebar: DefaultTheme.SidebarItem[] = [ { - text: "Guides", + text: "Getting Started", items: [ { text: "Getting Started", @@ -19,7 +19,7 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ ], }, { - text: "Frontend", + text: "Building User Interfaces", items: [ { text: "Creating a Page", @@ -33,10 +33,6 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ text: "Customizing Context Menus", link: "/guides/menu", }, - { - text: "Storing Frontend Data", - link: "/guides/frontend_storage", - }, { text: "Using the Component Library", link: "/guides/styling", @@ -44,65 +40,84 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ ], }, { - text: "Backend", + text: "Working with HTTP", items: [ { - text: "Creating and Calling a Custom Function", - link: "/guides/rpc", + text: "Sending HTTP Requests", + link: "/guides/request", }, { - text: "Handling Backend Events", - link: "/guides/backend_events", + text: "Sending a Fetch Request", + link: "/guides/fetch", }, { text: "Fetching Proxied Requests", link: "/guides/querying_requests", }, { - text: "Sending HTTP Requests", - link: "/guides/request", + text: "Using Invalid UTF-8", + link: "/guides/utf", }, + ], + }, + { + text: "Working with Caido Features", + items: [ { - text: "Sending a Fetch Request", - link: "/guides/fetch", + text: "Using Findings", + link: "/guides/findings", }, { - text: "Sending Events to the Frontend", - link: "/guides/events", + text: "Using Environment Variables", + link: "/guides/env", }, + ], + }, + { + text: "Storing Data", + items: [ { - text: "Spawning a Process", - link: "/guides/spawning_process", + text: "Storing Frontend Data", + link: "/guides/frontend_storage", }, { text: "Storing Data in SQLite", link: "/guides/sqlite", }, { - text: "Using Findings", - link: "/guides/findings", - }, - { - text: "Using Invalid UTF-8", - link: "/guides/utf", + text: "Adding Files", + link: "/guides/files", }, ], }, { - text: "Shared", + text: "Communication & Events", items: [ { - text: "Adding Files", - link: "/guides/files", + text: "Creating and Calling a Custom Function", + link: "/guides/rpc", }, { - text: "Using Environment Variables", - link: "/guides/env", + text: "Handling Backend Events", + link: "/guides/backend_events", + }, + { + text: "Sending Events to the Frontend", + link: "/guides/events", + }, + ], + }, + { + text: "System Integration", + items: [ + { + text: "Spawning a Process", + link: "/guides/spawning_process", }, ], }, { - text: "Community Store", + text: "Distribution", items: [ { text: "Setting Up Your Repository", diff --git a/AGENTS.md b/AGENTS.md index ef46368..11be2c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,24 +65,49 @@ src/ ├── tutorials/ # Step-by-step learning experiences │ ├── index.md │ └── notebook.md -├── guides/ # Task-oriented how-to guides +├── guides/ # Task-oriented how-to guides (all files flattened) │ ├── index.md -│ ├── components/ # Component-specific guides │ ├── config.md -│ ├── contributions/ # Contribution guides -│ └── distribution/ # Distribution guides +│ ├── vibe_coding.md +│ ├── page.md +│ ├── command.md +│ ├── menu.md +│ ├── styling.md +│ ├── request.md +│ ├── fetch.md +│ ├── querying_requests.md +│ ├── utf.md +│ ├── findings.md +│ ├── env.md +│ ├── frontend_storage.md +│ ├── sqlite.md +│ ├── files.md +│ ├── rpc.md +│ ├── backend_events.md +│ ├── events.md +│ ├── spawning_process.md +│ ├── repository.md +│ ├── store.md +│ └── documentation.md ├── reference/ # Technical reference documentation │ ├── index.md -│ ├── sdks/ # SDK documentation -│ ├── modules/ # Module documentation +│ ├── sdks/ # Generated SDK documentation +│ ├── modules/ # Generated module documentation │ ├── config.md -│ └── manifest.md -└── concepts/ # Explanatory documentation +│ ├── manifest.md +│ ├── plugin_packages.md +│ ├── api.md +│ └── authentication.md +└── concepts/ # Explanatory documentation (all files flattened) ├── index.md - ├── essentials/ # Core concepts - ├── frontend/ # Frontend concepts - ├── backend/ # Backend concepts - └── modules/ # Module concepts + ├── package.md + ├── tooling.md + ├── runtime.md + ├── signing.md + ├── ui.md + ├── binary.md + ├── workflow.md + └── child_process.md ``` ## How to Contribute (For AI Agents) @@ -101,7 +126,73 @@ Before writing or editing documentation, determine which type it should be: - All documentation files are Markdown (`.md`) - Files must be linked in the appropriate `index.md` file to appear in navigation - Use descriptive, lowercase filenames with hyphens (e.g., `creating-commands.md`) -- Place files in the appropriate subdirectory based on topic +- **Guides are now flattened**: All guide files are directly in `src/guides/` (no subdirectories) +- **Concepts are now flattened**: All concept files are directly in `src/concepts/` (no subdirectories) +- **Reference non-generated pages are flattened**: Non-generated reference files are directly in `src/reference/` (generated SDK/module docs remain in subdirectories) + +#### Guides Sidebar Organization + +The guides sidebar is organized by **user goals and tasks**, not by technical boundaries (Frontend/Backend). This follows Diátaxis principles for how-to guides, which should be organized around "what the user wants to accomplish." + +**Current Sidebar Structure:** + +1. **Getting Started** - Onboarding and setup + - Getting Started + - Configuring Your Package + - AI Assisted Coding + +2. **Building User Interfaces** - Creating UI components and interactions + - Creating a Page + - Creating a Command + - Customizing Context Menus + - Using the Component Library + +3. **Working with HTTP** - Sending, fetching, and manipulating HTTP requests + - Sending HTTP Requests + - Sending a Fetch Request + - Fetching Proxied Requests + - Using Invalid UTF-8 + +4. **Working with Caido Features** - Interacting with Caido's built-in features/objects + - Using Findings + - Using Environment Variables + - (Future: Scopes, HTTP History, Filters, etc.) + +5. **Storing Data** - Storing your plugin's own data + - Storing Frontend Data + - Storing Data in SQLite + - Adding Files + +6. **Communication & Events** - Frontend-backend communication and event handling + - Creating and Calling a Custom Function + - Handling Backend Events + - Sending Events to the Frontend + +7. **System Integration** - System-level operations + - Spawning a Process + +8. **Distribution** - Publishing and sharing plugins + - Setting Up Your Repository + - Submitting to the Store + +9. **Contributions** - Contributing to the documentation + - Documentation + +**Key Principles:** + +- **Task-oriented, not SDK-oriented**: Guides are grouped by what users want to accomplish, not which SDK they use +- **No technical boundaries**: Frontend/backend separation is hidden - users find guides by their goal +- **Conceptual groupings**: Related concepts are grouped together (e.g., all HTTP guides together, all Caido features together) +- **User mental models**: Organization matches how users think about problems ("I want to build a UI" not "I want to use the frontend SDK") + +**When adding a new guide:** + +1. Determine the user's goal: What task are they trying to accomplish? +2. Find the appropriate section based on that goal +3. If it's about interacting with Caido's built-in features (Findings, Scopes, Environment Variables, HTTP History, etc.), use "Working with Caido Features" +4. If it's about sending/manipulating HTTP requests, use "Working with HTTP" +5. If it's about storing your plugin's data, use "Storing Data" +6. Update the sidebar in `.vitepress/sidebars/guides.ts` ### 3. Writing Guidelines diff --git a/SIDEBAR_ANALYSIS.md b/SIDEBAR_ANALYSIS.md deleted file mode 100644 index a0890cd..0000000 --- a/SIDEBAR_ANALYSIS.md +++ /dev/null @@ -1,215 +0,0 @@ -# Guides Sidebar Analysis - -## Current Structure - -``` -Guides -├── Getting Started -├── Configuring Your Package -└── AI Assisted Coding - -Frontend -├── Creating a Page -├── Creating a Command -├── Customizing Context Menus -├── Storing Frontend Data -└── Using the Component Library - -Backend -├── Creating and Calling a Custom Function -├── Handling Backend Events -├── Fetching Proxied Requests -├── Sending HTTP Requests -├── Sending a Fetch Request -├── Sending Events to the Frontend -├── Spawning a Process -├── Storing Data in SQLite -├── Using Findings -└── Using Invalid UTF-8 - -Shared -├── Adding Files -└── Using Environment Variables - -Community Store -├── Setting Up Your Repository -└── Submitting to the Store - -Contributions -└── Documentation -``` - -## Issues with Current Structure - -### 1. **Technical Organization vs. Task-Oriented Organization** - -**Problem**: The sidebar is organized by technical boundaries (Frontend/Backend/Shared) rather than by user tasks. This violates Diátaxis principles for how-to guides, which should be organized around "what the user wants to accomplish." - -**Example**: A user wanting to "create a command" needs to understand both frontend (registering the command) and potentially backend (if the command calls backend functions), but these are separated. - -### 2. **Mixed Abstraction Levels** - -Some guides are very specific ("Sending a Fetch Request") while others are more conceptual ("Creating a Page"). This makes it harder for users to find what they need at their level of understanding. - -### 3. **Not Aligned with User Mental Models** - -Users think in terms of: - -- "I want to build a UI" -- "I want to handle HTTP requests" -- "I want to store data" -- "I want to communicate between frontend and backend" - -Not in terms of: - -- "I want to use the frontend SDK" -- "I want to use the backend SDK" - -### 4. **Missing Conceptual Groupings** - -Based on the missing guides analysis, there are clear conceptual patterns that should be grouped: - -- Editor extensions and view modes -- Event subscriptions -- Scope management -- Query/filter management -- Slots system - -## Recommended Structure (Task-Oriented) - -``` -Getting Started -├── Getting Started -├── Configuring Your Package -└── AI Assisted Coding - -Building User Interfaces -├── Creating a Page -├── Creating a Command -├── Customizing Context Menus -├── Using the Component Library -└── Showing Dialogs (missing) - -Working with HTTP -├── Sending HTTP Requests -├── Sending a Fetch Request -├── Fetching Proxied Requests -└── Using Findings - -Storing Data -├── Storing Frontend Data -├── Storing Data in SQLite -└── Adding Files - -Communication & Events -├── Creating and Calling a Custom Function (RPC) -├── Handling Backend Events -├── Sending Events to the Frontend -└── Listening to Application Events (missing) - -System Integration -├── Spawning a Process -├── Using Environment Variables -└── Using Invalid UTF-8 - -Distribution -├── Setting Up Your Repository -└── Submitting to the Store - -Contributions -└── Documentation -``` - -## Alternative Structure (By User Goal) - -If we want to be even more task-oriented, we could organize by common user goals: - -``` -Getting Started -├── Getting Started -├── Configuring Your Package -└── AI Assisted Coding - -Creating Plugin Features -├── Building User Interfaces -│ ├── Creating a Page -│ ├── Creating a Command -│ ├── Customizing Context Menus -│ ├── Using the Component Library -│ └── Showing Dialogs (missing) -├── Working with HTTP -│ ├── Sending HTTP Requests -│ ├── Sending a Fetch Request -│ ├── Fetching Proxied Requests -│ └── Using Findings -└── Managing Data - ├── Storing Frontend Data - ├── Storing Data in SQLite - └── Adding Files - -Connecting Components -├── Creating and Calling a Custom Function (RPC) -├── Handling Backend Events -├── Sending Events to the Frontend -└── Listening to Application Events (missing) - -System Operations -├── Spawning a Process -├── Using Environment Variables -└── Using Invalid UTF-8 - -Sharing Your Plugin -├── Setting Up Your Repository -└── Submitting to the Store - -Contributing -└── Documentation -``` - -## Recommended Approach - -I recommend the **first alternative structure** (Task-Oriented) because: - -1. **Clear task groupings** - Each section answers "what do I want to do?" -2. **Progressive disclosure** - Users can expand sections as needed -3. **No technical boundaries** - Frontend/backend separation is hidden -4. **Scalable** - Easy to add new guides to appropriate sections -5. **Matches Diátaxis** - How-to guides should be organized by user goals - -## Implementation Notes - -1. **Rename sections** to be more user-friendly: - - "Frontend" → "Building User Interfaces" - - "Backend" → Split into "Working with HTTP", "Communication & Events", "System Integration" - - "Shared" → Merge into appropriate sections - -2. **Group related concepts**: - - All HTTP-related guides together - - All event-related guides together - - All storage-related guides together - -3. **Consider adding missing guides** as placeholders: - - "Showing Dialogs" under Building User Interfaces - - "Listening to Application Events" under Communication & Events - -4. **Keep "Getting Started" separate** - It serves a different purpose (onboarding) - -5. **Keep "Distribution" and "Contributions" separate** - These are meta-topics about the plugin ecosystem, not plugin development itself - -## Comparison: Current vs. Recommended - -| Current | Recommended | Benefit | -|---------|-------------|---------| -| Frontend/Backend/Shared | Task-oriented sections | Users find guides by what they want to do, not which SDK | -| Technical boundaries | User goals | Better matches mental models | -| Mixed abstraction | Consistent grouping | Easier to find related guides | -| SDK-focused | Concept-focused | Aligns with Diátaxis principles | - -## Next Steps - -1. Reorganize the sidebar structure in `.vitepress/sidebars/guides.ts` -2. Consider renaming some guides to be more task-oriented: - - "Creating and Calling a Custom Function" → "Communicating Between Frontend and Backend" - - "Sending a Fetch Request" → "Making HTTP Requests with Fetch" -3. Add placeholders for missing high-priority guides -4. Update guide titles to be more consistent (all start with action verbs)