From 871dc0a6b26dcf12e1716b8be2ba6269bb9d5e65 Mon Sep 17 00:00:00 2001 From: Ian Bouchard Date: Wed, 16 Oct 2024 02:07:21 -0400 Subject: [PATCH] Add tutorial section (#16) --- .vitepress/config.mts | 9 ++- .vitepress/sidebars/concepts.ts | 8 +- .vitepress/sidebars/guides.ts | 11 +-- .vitepress/sidebars/index.ts | 1 + .vitepress/sidebars/tutorials.ts | 22 +++++ render.yaml | 3 + src/concepts/essentials/package.md | 77 ++++++++++++++++++ src/concepts/index.md | 9 ++- src/guides/index.md | 80 +------------------ src/index.md | 4 + src/tutorials/index.md | 9 +++ src/{guides/plugins => tutorials}/notebook.md | 0 12 files changed, 141 insertions(+), 92 deletions(-) create mode 100644 .vitepress/sidebars/tutorials.ts create mode 100644 src/concepts/essentials/package.md create mode 100644 src/tutorials/index.md rename src/{guides/plugins => tutorials}/notebook.md (100%) diff --git a/.vitepress/config.mts b/.vitepress/config.mts index e1aa7bf..c265b9c 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -1,6 +1,11 @@ import { defineConfig } from "vitepress"; -import { conceptsSidebar, guidesSidebar, referenceSidebar } from "./sidebars"; +import { + conceptsSidebar, + guidesSidebar, + referenceSidebar, + tutorialsSidebar, +} from "./sidebars"; // https://vitepress.dev/reference/site-config export default defineConfig({ @@ -40,6 +45,7 @@ export default defineConfig({ nav: [ { text: "Guides", link: "/guides/" }, + { text: "Tutorials", link: "/tutorials/" }, { text: "Reference", link: "/reference/" }, { text: "Concepts", link: "/concepts/" }, { text: "Policy", link: "/policy.md" }, @@ -49,6 +55,7 @@ export default defineConfig({ "/reference/": referenceSidebar, "/guides/": guidesSidebar, "/concepts/": conceptsSidebar, + "/tutorials/": tutorialsSidebar, }, outline: { diff --git a/.vitepress/sidebars/concepts.ts b/.vitepress/sidebars/concepts.ts index d0893a7..32450de 100644 --- a/.vitepress/sidebars/concepts.ts +++ b/.vitepress/sidebars/concepts.ts @@ -2,10 +2,10 @@ import type { DefaultTheme } from "vitepress"; export const conceptsSidebar: DefaultTheme.SidebarItem[] = [ { - text: "Introduction", + text: "Concepts", items: [ { - text: "Directory", + text: "Introduction", link: "/concepts/", }, ], @@ -13,6 +13,10 @@ export const conceptsSidebar: DefaultTheme.SidebarItem[] = [ { text: "Essentials", items: [ + { + text: "Plugin Architecture", + link: "/concepts/essentials/package", + }, { text: "Tooling", link: "/concepts/essentials/tooling", diff --git a/.vitepress/sidebars/guides.ts b/.vitepress/sidebars/guides.ts index 5dbada6..d32c4d9 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: "Introduction", + text: "Guides", items: [ { text: "Getting Started", @@ -10,15 +10,6 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ }, ], }, - { - text: "Example Plugins", - items: [ - { - text: "Notebook", - link: "/guides/plugins/notebook", - }, - ], - }, { text: "Frontend", items: [ diff --git a/.vitepress/sidebars/index.ts b/.vitepress/sidebars/index.ts index eab8513..d36a3d9 100644 --- a/.vitepress/sidebars/index.ts +++ b/.vitepress/sidebars/index.ts @@ -1,3 +1,4 @@ export * from "./reference"; export * from "./guides"; export * from "./concepts"; +export * from "./tutorials"; diff --git a/.vitepress/sidebars/tutorials.ts b/.vitepress/sidebars/tutorials.ts new file mode 100644 index 0000000..ec70ded --- /dev/null +++ b/.vitepress/sidebars/tutorials.ts @@ -0,0 +1,22 @@ +import type { DefaultTheme } from "vitepress"; + +export const tutorialsSidebar: DefaultTheme.SidebarItem[] = [ + { + text: "Tutorials", + items: [ + { + text: "Introduction", + link: "/tutorials/", + }, + ], + }, + { + text: "Example Plugins", + items: [ + { + text: "Notebook", + link: "/tutorials/notebook/", + }, + ], + }, +]; diff --git a/render.yaml b/render.yaml index 3eb237d..0e81ad0 100644 --- a/render.yaml +++ b/render.yaml @@ -23,6 +23,9 @@ services: - type: redirect source: /concepts/essentials/plugins/backend.html destination: /guides/ + - type: redirect + source: /guides/plugins/notebook.html + destination: /tutorials/notebook.html domains: - developer.caido.io envVars: diff --git a/src/concepts/essentials/package.md b/src/concepts/essentials/package.md new file mode 100644 index 0000000..bff88c2 --- /dev/null +++ b/src/concepts/essentials/package.md @@ -0,0 +1,77 @@ +# Plugin Architecture + +As Caido utilizes a **client/server architecture** - inherently, this means plugin development consists of many parts: + +- A manifest.json file +- A frontend plugin +- A backend plugin + +These parts are packaged together in a single entity known as a **plugin package**. + +### Manifest.json + +The `manifest.json` configuration file defines the plugin package structure and also contains metadata used by the Caido installer. + +Here's an example of what the `manifest.json` file should look like: + +```json +{ + "id": "authmatrix", + "name": "AuthMatrix", + "version": "0.2.0", + "description": "Grid-based authorization testing across multiple users and roles.", + "author": { + "name": "Caido Labs Inc.", + "email": "dev@caido.io", + "url": "https://github.com/caido-community/authmatrix" + }, + "plugins": [ + { + "kind": "frontend", + "id": "authmatrix-frontend", + "name": "Authmatrix Frontend", + "entrypoint": "frontend/script.js", + "style": "frontend/style.css", + "backend": { + "id": "authmatrix-backend" + } + }, + { + "kind": "backend", + "id": "authmatrix-backend", + "name": "Authmatrix Backend", + "runtime": "javascript", + "entrypoint": "backend/script.js" + } + ] +} +``` + +::: info +For more information on the `manifest.json` file, refer to the [manifest.json reference](/reference/manifest.md). +::: + +### Frontend Plugin + +Frontend plugins allow you to customize the UI of the Caido application: + +- Add new pages, components and elements. +- Modify the appearance, behavior and functionality of the user-interface. +- Handle user interactions, render data and communicate with the backend server via Caido's API. + +::: info +You can find the full list of available frontend SDK functions in the [frontend SDK reference](/reference/sdks/frontend/index.md). +::: + +### Backend Plugin + +Backend plugins allow you to extend the server-side functionality of the Caido application: + +- Interact with the application's data and databases. +- Perform HTTP requests to external APIs. +- Handle computationally intensive tasks. +- Respond to events that occur within Caido. + +::: info +You can find the full list of available backend SDK functions in the [backend SDK reference](/reference/sdks/backend/index.md). +::: diff --git a/src/concepts/index.md b/src/concepts/index.md index f5d1898..863ce91 100644 --- a/src/concepts/index.md +++ b/src/concepts/index.md @@ -1,9 +1,12 @@ -# Directory +# Concepts + +Here you will find explanations of the core concepts that underpin Caido plugins. ## Essentials -- **[Runtime](./essentials/runtime.md)** - javascript runtime used by Plugins. -- **[Tooling](./essentials/tooling.md)** - tools for the ease of Plugin development. +- [Plugin Architecture](./essentials/package.md) - The structure of a plugin package. +- [Runtime](./essentials/runtime.md) - Javascript runtimes used by plugins. +- [Tooling](./essentials/tooling.md) - Tools for the ease of plugin development. ## Modules diff --git a/src/guides/index.md b/src/guides/index.md index b26588e..b58bbc7 100644 --- a/src/guides/index.md +++ b/src/guides/index.md @@ -2,89 +2,17 @@ Caido allows users to develop custom features in the form of plugins. -Conceptualize them as extensive [Workflows](https://docs.caido.io/concepts/essentials/workflows.html). While they both provide task automation - plugins offer a greater level of complexity and flexibility. +Plugin development is done in JavaScript and consists of many parts: -Plugins are written in JavaScript. - -## Plugin Packages - -As Caido utilizes a **client/server architecture** - inherently, this means plugin development consists of many parts: - -- A manifest.json file +- A `manifest.json` file - A frontend plugin - A backend plugin These parts are packaged together in a single entity known as a **plugin package**. -### Manifest.json - -The `manifest.json` configuration file defines the plugin package structure and also contains metadata used by the Caido installer. - -Here's an example of what the `manifest.json` file should look like: - -```json -{ - "id": "authmatrix", - "name": "AuthMatrix", - "version": "0.2.0", - "description": "Grid-based authorization testing across multiple users and roles.", - "author": { - "name": "Caido Labs Inc.", - "email": "dev@caido.io", - "url": "https://github.com/caido-community/authmatrix" - }, - "plugins": [ - { - "kind": "frontend", - "id": "authmatrix-frontend", - "name": "Authmatrix Frontend", - "entrypoint": "frontend/script.js", - "style": "frontend/style.css", - "backend": { - "id": "authmatrix-backend" - } - }, - { - "kind": "backend", - "id": "authmatrix-backend", - "name": "Authmatrix Backend", - "runtime": "javascript", - "entrypoint": "backend/script.js" - } - ] -} -``` - -::: info -For more information on the `manifest.json` file, refer to the [manifest.json reference](/reference/manifest.md). -::: - -### Frontend Plugin - -Frontend plugins allow you to customize the UI of the Caido application: - -- Add new pages, components and elements. -- Modify the appearance, behavior and functionality of the user-interface. -- Handle user interactions, render data and communicate with the backend server via Caido's API. - -::: info -You can find the full list of available frontend SDK functions in the [frontend SDK reference](/reference/sdks/frontend/index.md). -::: - -### Backend Plugin - -Backend plugins allow you to extend the server-side functionality of the Caido application: - -- Interact with the application's data and databases. -- Perform HTTP requests to external APIs. -- Handle computationally intensive tasks. -- Respond to events that occur within Caido. - -::: info -You can find the full list of available backend SDK functions in the [backend SDK reference](/reference/sdks/backend/index.md). -::: +For more information on the structure of a plugin package, see [Plugin Architecture](/concepts/essentials/package.md). -## Creating Your First Plugin Package +## Creating a Plugin Package ::: info Requirements Plugins are developed in JavaScript and require the following to be installed on your device: diff --git a/src/index.md b/src/index.md index 842b1c9..07a73e0 100644 --- a/src/index.md +++ b/src/index.md @@ -15,6 +15,10 @@ hero: text: Guides link: /guides/ + - theme: alt + text: Tutorials + link: /tutorials/ + - theme: alt text: Reference link: /reference/ diff --git a/src/tutorials/index.md b/src/tutorials/index.md new file mode 100644 index 0000000..e005093 --- /dev/null +++ b/src/tutorials/index.md @@ -0,0 +1,9 @@ +# Tutorials + +This section of the documentation is dedicated to providing step-by-step tutorials for developers to get started with Caido. + +If you are new to plugin development, the tutorials here will give you a feel for what it's like to build plugins for Caido. + +## Example Plugins + +- [Notebook](/tutorials/notebook.md): A simple notebook plugin for in-app note taking. diff --git a/src/guides/plugins/notebook.md b/src/tutorials/notebook.md similarity index 100% rename from src/guides/plugins/notebook.md rename to src/tutorials/notebook.md