@docsector/docsector-reader 4.1.0 → 4.3.0

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/mcp-webmcp.md

@@ -0,0 +1,90 @@
+# MCP and WebMCP Reference
+
+Docsector can expose documentation to agents through MCP, WebMCP, Markdown negotiation, and `llms.txt`. Use these sources when an assistant needs current docs instead of only the static guidance in this skill.
+
+## MCP Server
+
+When configured, Docsector generates an MCP endpoint at:
+
+```text
+/mcp
+```
+
+The server exposes tools named with the configured suffix:
+
+| Tool                | Purpose                               |
+| ------------------- | ------------------------------------- |
+| `search_{suffix}`   | Search documentation pages by keyword |
+| `get_page_{suffix}` | Fetch raw Markdown for a page path    |
+
+This repository configures `toolSuffix: 'docsector'`, so connected MCP clients should see:
+
+```text
+search_docsector
+get_page_docsector
+```
+
+## MCP Page Paths
+
+`get_page_{suffix}` expects paths without a leading slash, trailing slash, or `.md` suffix. It can try an `/overview` fallback when the primary path is not found.
+
+Useful examples:
+
+```text
+manual/content/blocks/quick-links/overview
+manual/content/blocks/cards/overview
+manual/content/blocks/code-examples/overview
+manual/content/blocks/api-reference/overview
+manual/content/blocks/timeline/showcase
+guide/getting-started/overview
+```
+
+## Recommended Agent Flow
+
+1. Use `search_{suffix}` for discovery, such as `search_docsector` with `"timeline block"`.
+2. Use `get_page_{suffix}` with the best matching path.
+3. Read the returned Markdown examples before authoring or changing a custom element.
+4. Prefer the live manual page when it conflicts with this static skill.
+5. If MCP is not connected, use Markdown URLs, `llms.txt`, or the references bundled with this skill.
+
+## WebMCP Browser Tools
+
+When `navigator.modelContext` is available in a secure browser context, Docsector can register browser-side tools. Typical tool names are:
+
+| Tool                     | Purpose                                                           |
+| ------------------------ | ----------------------------------------------------------------- |
+| `docs.search_docs`       | Search docs through the MCP bridge                                |
+| `docs.get_page`          | Fetch page Markdown through the MCP bridge                        |
+| `docs.navigate_to`       | Navigate the single-page app to a route and optional hash         |
+| `docs.copy_current_page` | Return the current page path, Markdown URL, and optionally source |
+
+Use these tools when working inside a Docsector page with a browser agent. Use MCP tools directly when working from an editor or external assistant.
+
+## Markdown and LLM Discovery
+
+Docsector pages can expose raw Markdown in several ways:
+
+- Append `.md` to a page URL.
+- Send `Accept: text/markdown` to use Markdown negotiation.
+- Use `/llms.txt` for an index of pages when `siteUrl` is configured.
+- Use `/llms-full.txt` for concatenated full content when generated.
+
+These are useful fallbacks when MCP is unavailable.
+
+## Discovery Artifacts
+
+Docsector can also publish machine-readable discovery files:
+
+| Artifact                               | Purpose                      |
+| -------------------------------------- | ---------------------------- |
+| `/.well-known/mcp/server-card.json`    | MCP server discovery         |
+| `/.well-known/agent-skills/index.json` | Agent Skills Discovery index |
+| `/.well-known/api-catalog`             | API catalog Linkset JSON     |
+
+## Caveats
+
+- MCP search indexes pages, not individual component schemas.
+- Public API JSON files under `/api/...` and `/quasar-api/...` are static assets and may not be directly searchable through MCP page search.
+- WebMCP requires browser support for `navigator.modelContext` and a secure context, except where localhost is allowed by the browser.
+- Generated MCP indexes are build artifacts, so a production build is required after source changes.
+- If multiple Docsector sites are connected to the same assistant, each site should use a unique MCP tool suffix.

package/public/.well-known/agent-skills/docsector-documentation-authoring/references/page-structure.md

@@ -0,0 +1,101 @@
+# Docsector Page Structure
+
+Use this reference when adding or editing Docsector content files, assets, examples, and API reference data.
+
+## Page Sources
+
+Docsector pages are registered in index files such as `src/pages/manual.index.js` and backed by localized Markdown files under `src/pages/`.
+
+Manual content blocks follow this pattern:
+
+```text
+src/pages/manual/content/blocks/{block}.overview.en-US.md
+src/pages/manual/content/blocks/{block}.showcase.en-US.md
+src/pages/manual/content/blocks/{block}.overview.pt-BR.md
+src/pages/manual/content/blocks/{block}.showcase.pt-BR.md
+```
+
+The route path maps to MCP/page paths such as:
+
+```text
+manual/content/blocks/cards/overview
+manual/content/blocks/cards/showcase
+```
+
+## Overview and Showcase
+
+Use `overview` for conceptual explanation, syntax, attributes, and authoring notes. Use `showcase` for varied examples that demonstrate the block in realistic content.
+
+Most block docs should include both subpages. Structure docs such as page, subpage, or books may use different subpage rules depending on their registry configuration.
+
+## Localization
+
+Localized Markdown files use locale suffixes such as `.en-US.md` and `.pt-BR.md`. Keep route structure and headings aligned across locales when possible so translation progress and navigation remain useful.
+
+New repository-facing documentation and AI customization files should be written in English unless the file is explicitly a locale-specific translation.
+
+## Assets
+
+Use public site paths in Markdown:
+
+| Asset Type      | Repo Location           | Public Path       |
+| --------------- | ----------------------- | ----------------- |
+| Images          | `public/images/...`     | `/images/...`     |
+| Files           | `public/files/...`      | `/files/...`      |
+| Manual API JSON | `public/api/manual/...` | `/api/manual/...` |
+| Quasar API JSON | `public/quasar-api/...` | `/quasar-api/...` |
+
+Prefer absolute public paths in documentation so pages keep working when routes move.
+
+## Code Examples
+
+Live code examples are Vue SFC files discovered from `src/examples/**/*.vue`.
+
+Reference them with:
+
+```html
+<d-block-code-example
+  src="manual/code-examples/basic-counter"
+  title="Basic counter"
+/>
+```
+
+The `src` value is normalized to kebab-case and resolves to a PascalCase `.vue` file. For example, `manual/code-examples/basic-counter` resolves to `src/examples/manual/code-examples/BasicCounter.vue`.
+
+Use `file` as an alias for `src` only when migrating from Quasar Docs-style examples.
+
+## API Reference JSON
+
+API blocks fetch JSON from same-origin public assets:
+
+```html
+<d-block-api
+  src="/api/manual/http-client.json"
+  title="HTTP Client API"
+  page-link="true"
+/>
+```
+
+The JSON can follow Quasar's API schema. Useful sections include `props`, `methods`, `events`, `value`, `arg`, and `quasarConfOptions`. Entries marked `internal: true` are hidden.
+
+## Navigation and Metadata
+
+Page registry entries in `src/pages/*.index.js` define titles, status, icons, books, menu placement, subpage availability, descriptions, and search tags.
+
+When adding new content, check the nearest existing entry and keep metadata consistent with that section.
+
+## Authoring Rules
+
+- Prefer Markdown for simple content.
+- Use custom elements only when they add structure, interaction, or a clearer reading path.
+- Use `to` for internal Docsector routes and `href` for external URLs.
+- Avoid repeating the same Markdown source in multiple routes.
+- Keep page headings outside Expandable, Stepper, and Timeline bodies when they are meant to appear in the page-level table of contents.
+- Avoid unsupported nested custom block combinations unless current manual docs explicitly show the pattern.
+
+## Validation Pointers
+
+- Parser behavior is centered in `src/components/page-section-tokens.js`.
+- Rendering is dispatched by `src/components/DPageTokens.vue`.
+- Manual block registration is covered by `tests/manual-content-showcases.spec.js`.
+- Parser and block edge cases are covered by focused tests such as `tests/page-section-tokens.spec.js`, `tests/code-example-source.spec.js`, `tests/embedded-url-providers.spec.js`, and `tests/api-block-model.spec.js`.

package/public/api/manual/http-client.json

@@ -0,0 +1,91 @@
+{
+  "meta": {
+    "docsUrl": "https://example.com/sdk/http-client"
+  },
+  "props": {
+    "baseUrl": {
+      "type": "String",
+      "desc": "Base URL used by the client.",
+      "default": "https://api.example.com",
+      "examples": ["https://api.example.com", "https://staging.example.com"],
+      "category": "configuration"
+    },
+    "timeout": {
+      "type": "Number",
+      "desc": "Request timeout in milliseconds.",
+      "default": 10000,
+      "category": "configuration"
+    },
+    "retries": {
+      "type": "Number",
+      "desc": "Retry attempts for idempotent calls.",
+      "default": 2,
+      "category": "behavior"
+    }
+  },
+  "methods": {
+    "request": {
+      "desc": "Perform an HTTP request.",
+      "params": {
+        "options": {
+          "type": "Object",
+          "desc": "Request options.",
+          "required": true,
+          "definition": {
+            "url": {
+              "type": "String",
+              "desc": "Absolute or relative URL.",
+              "required": true,
+              "examples": ["/status", "https://example.com/health"]
+            },
+            "method": {
+              "type": "String",
+              "desc": "HTTP method.",
+              "default": "GET",
+              "examples": ["GET", "POST"]
+            },
+            "headers": {
+              "type": "Object",
+              "desc": "Additional request headers.",
+              "required": false
+            }
+          }
+        }
+      },
+      "returns": {
+        "type": "Promise<ResponseLike>",
+        "desc": "Resolves with the parsed response wrapper."
+      },
+      "examples": ["client.request({ url: '/status' })"]
+    },
+    "cancelAll": {
+      "desc": "Abort all in-flight requests.",
+      "returns": {
+        "type": "void",
+        "desc": "No return value."
+      }
+    }
+  },
+  "events": {
+    "response": {
+      "desc": "Emitted after a response is resolved.",
+      "params": {
+        "payload": {
+          "type": "Object",
+          "desc": "Resolved response payload.",
+          "required": true
+        }
+      }
+    },
+    "error": {
+      "desc": "Emitted when a request fails.",
+      "params": {
+        "error": {
+          "type": "Error",
+          "desc": "The original request error.",
+          "required": true
+        }
+      }
+    }
+  }
+}

package/public/quasar-api/QSeparator.json

@@ -0,0 +1,39 @@
+{
+  "meta": {
+    "docsUrl": "https://v2.quasar.dev/vue-components/separator"
+  },
+
+  "props": {
+    "dark": {
+      "extends": "dark"
+    },
+
+    "spaced": {
+      "type": ["Boolean", "String"],
+      "desc": "If set to true, the corresponding direction margins will be set to 8px; It can also be set to a size in CSS units, including unit name, or one of the xs|sm|md|lg|xl predefined sizes",
+      "examples": ["'12px'", "'sm'", "'md'"],
+      "category": "content"
+    },
+
+    "inset": {
+      "type": ["Boolean", "String"],
+      "desc": "If set to Boolean true, the left and right margins will be set to 16px. If set to 'item' then it will match a QItem's design. If set to 'item-thumbnail' then it will match the design of a QItem with a thumbnail on the left side",
+      "values": ["true", "false", "'item'", "'item-thumbnail'"],
+      "category": "content"
+    },
+
+    "vertical": {
+      "type": "Boolean",
+      "desc": "If set to true, the separator will be vertical.",
+      "category": "content"
+    },
+
+    "size": {
+      "extends": "size"
+    },
+
+    "color": {
+      "extends": "color"
+    }
+  }
+}