Skip to content

Commit 3446e4f

Browse files
bajrangCoderbajrangCoder
committed
feat: update the docs and apis etc
1 parent 5fd16d9 commit 3446e4f

12 files changed

Lines changed: 747 additions & 121 deletions

File tree

‎.vitepress/config.mts‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ export default defineConfig({
55
lastUpdated: true,
66
cleanUrls: true,
77
base: "/",
8+
srcExclude: ["Acode/**"],
89
head: [["link", { rel: "icon", href: "/acode.png" }]],
910

1011
locales: {
@@ -102,7 +103,7 @@ export default defineConfig({
102103
collapsed: true,
103104
items: [
104105
{
105-
text: "Ace",
106+
text: "CodeMirror & Legacy Ace",
106107
link: "/docs/global-apis/ace",
107108
},
108109
{
@@ -196,9 +197,17 @@ export default defineConfig({
196197
link: "/docs/utilities/projects",
197198
},
198199
{
199-
text: "ACE Modes",
200+
text: "Commands",
201+
link: "/docs/utilities/commands",
202+
},
203+
{
204+
text: "Editor Languages",
200205
link: "/docs/utilities/ace-modes",
201206
},
207+
{
208+
text: "Editor Themes",
209+
link: "/docs/utilities/editor-themes",
210+
},
202211
{
203212
text: "Encoding",
204213
link: "/docs/utilities/encoding",
@@ -303,6 +312,14 @@ export default defineConfig({
303312
text: "Terminal",
304313
link: "/docs/advanced-apis/terminal",
305314
},
315+
{
316+
text: "LSP",
317+
link: "/docs/advanced-apis/lsp",
318+
},
319+
{
320+
text: "File Handlers",
321+
link: "/docs/advanced-apis/file-handlers",
322+
},
306323
{
307324
text: "Action Stack",
308325
link: "/docs/advanced-apis/action-stack",

‎docs/advanced-apis/file-handlers.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# File Handlers API
2+
3+
Use this API to register custom open handlers for file extensions.
4+
5+
## `acode.registerFileHandler(id, options)`
6+
7+
Registers a handler.
8+
9+
```js
10+
acode.registerFileHandler("com.example.svg-viewer", {
11+
extensions: ["svgx", ".svgalt"],
12+
handleFile: async (fileInfo) => {
13+
console.log(fileInfo.name, fileInfo.uri);
14+
},
15+
});
16+
```
17+
18+
`options` fields:
19+
20+
- `extensions` (required): extension array. Dots are allowed and normalized.
21+
- `handleFile` (required): async function receiving file info.
22+
23+
## `acode.unregisterFileHandler(id)`
24+
25+
Removes a handler.
26+
27+
```js
28+
acode.unregisterFileHandler("com.example.svg-viewer");
29+
```
30+
31+
## Notes
32+
33+
- Handler ids must be unique.
34+
- Extensions are matched case-insensitively.
35+
- `"*"` can be used to match any extension.

‎docs/advanced-apis/lsp.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# LSP API
2+
3+
Use this API to register/manage language servers used by Acode's CodeMirror LSP client.
4+
5+
## Import
6+
7+
```js
8+
const lsp = acode.require("lsp");
9+
```
10+
11+
## Important Transport Reality
12+
13+
CodeMirror's LSP client in Acode communicates via **WebSocket** transport.
14+
15+
- `transport.kind: "websocket"` is the recommended and practical mode.
16+
- `transport.kind: "stdio"` is **not a direct stdio pipe** to the editor.
17+
- In this codebase, `stdio` mode still expects a **WebSocket bridge URL**.
18+
19+
For local stdio language servers, use an **AXS bridge** (`launcher.bridge`) and keep transport as websocket.
20+
21+
::: warning
22+
`stdio` with only `transport.command` is not enough in Acode.
23+
You still need a WebSocket bridge endpoint (AXS or equivalent) for the client connection.
24+
:::
25+
26+
## Recommended Setup (Local Server via AXS Bridge)
27+
28+
```js
29+
lsp.registerServer(
30+
{
31+
id: "typescript-custom",
32+
label: "TypeScript (Custom)",
33+
languages: ["javascript", "javascriptreact", "typescript", "typescriptreact", "tsx", "jsx"],
34+
transport: {
35+
kind: "websocket",
36+
// url can be omitted when using launcher.bridge auto-port mode
37+
},
38+
launcher: {
39+
bridge: {
40+
kind: "axs",
41+
command: "typescript-language-server",
42+
args: ["--stdio"],
43+
},
44+
checkCommand: "which typescript-language-server",
45+
install: {
46+
command:
47+
"apk add --no-cache nodejs npm && npm install -g typescript-language-server typescript",
48+
},
49+
},
50+
enabled: true,
51+
initializationOptions: {
52+
provideFormatter: true,
53+
},
54+
},
55+
{ replace: true },
56+
);
57+
```
58+
59+
## Remote/External WebSocket Server
60+
61+
```js
62+
lsp.registerServer({
63+
id: "remote-lsp",
64+
label: "Remote LSP",
65+
languages: ["json"],
66+
transport: {
67+
kind: "websocket",
68+
url: "ws://127.0.0.1:2087/",
69+
options: {
70+
binary: true,
71+
timeout: 5000,
72+
},
73+
},
74+
enabled: true,
75+
});
76+
```
77+
78+
## API Reference
79+
80+
### `registerServer(definition, options?)`
81+
82+
- `options.replace?: boolean` (default `false`)
83+
- `false`: existing server with same id is kept
84+
- `true`: existing server is replaced
85+
86+
Definition fields commonly used:
87+
88+
- `id` (required): normalized to lowercase
89+
- `label` (optional)
90+
- `languages` (required): non-empty array, normalized to lowercase
91+
- `enabled` (optional, default `true`)
92+
- `transport` (required)
93+
- `kind`: `"websocket"` or `"stdio"` (see transport note above)
94+
- `url?: string`
95+
- `command?: string` (required by registry validation when using `stdio`)
96+
- `args?: string[]`
97+
- `options?: { binary?, timeout?, reconnect?, maxReconnectAttempts? }`
98+
- `launcher` (optional)
99+
- `startCommand?: string | string[]`
100+
- `command?: string`
101+
- `args?: string[]`
102+
- `checkCommand?: string`
103+
- `install?: { command?: string }`
104+
- `bridge?: { kind: "axs", command: string, args?: string[], port?: number, session?: string }`
105+
- `initializationOptions?: object`
106+
- `clientConfig?: object`
107+
- `startupTimeout?: number`
108+
- `capabilityOverrides?: object`
109+
- `rootUri?: (uri, context) => string | null`
110+
- `resolveLanguageId?: (context) => string | null`
111+
- `useWorkspaceFolders?: boolean`
112+
113+
### Other Registry Methods
114+
115+
- `unregisterServer(id)`
116+
- `updateServer(id, updater)`
117+
- `getServer(id)`
118+
- `listServers()`
119+
- `getServersForLanguage(languageId, options?)`
120+
121+
```js
122+
const jsServers = lsp.getServersForLanguage("javascript");
123+
124+
lsp.updateServer("typescript-custom", (current) => ({
125+
...current,
126+
enabled: false,
127+
}));
128+
```
129+
130+
`getServersForLanguage` options:
131+
132+
- `includeDisabled?: boolean` (default `false`)
133+
134+
## Client Manager
135+
136+
- `clientManager.setOptions(options)`
137+
- `clientManager.getActiveClients()`
138+
139+
```js
140+
lsp.clientManager.setOptions({
141+
diagnosticsUiExtension: [],
142+
});
143+
144+
const activeClients = lsp.clientManager.getActiveClients();
145+
console.log(activeClients);
146+
```

‎docs/editor-components/editor-file.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Both methods are equivalent and accept & return the same parameters.
4646
| cursorPos | `object` | Cursor position | - |
4747
| scrollLeft | `number` | Scroll left position | - |
4848
| scrollTop | `number` | Scroll top position | - |
49-
| folds | [`Array<Fold>`](https://ajaxorg.github.io/ace-api-docs/classes/src_edit_session_fold.Fold.html) | Code folds | - |
49+
| folds | `Array<{ fromLine: number, fromCol: number, toLine: number, toCol: number }>` | Code folds | - |
5050
| type | `string` | Type of content (e.g., 'editor') | `'editor'` |
5151
| tabIcon | `string` | Icon class for the file tab | `'file file_type_default'` |
5252
| content | string \| [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) | Custom content element or HTML string. Strings are sanitized using DOMPurify | - |
@@ -76,7 +76,7 @@ Both methods are equivalent and accept & return the same parameters.
7676
| SAFMode | `'single' \| 'tree' \| null` | Storage access framework mode |
7777
| loaded | `boolean` | Whether file has completed loading text |
7878
| loading | `boolean` | Whether file is still loading text |
79-
| session | `AceAjax.IEditSession` | EditSession of the file |
79+
| session | `Proxy<EditorState>` | Session state with Ace-compatible helper methods |
8080
| readOnly | `boolean` | Whether file is readonly |
8181
| markChanged | `boolean` | Whether to mark changes when session text changes |
8282

‎docs/getting-started/understanding-plugin.md‎

Lines changed: 94 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,100 @@
1-
# Understanding Plugins
1+
# Understanding How Plugins Work
22

3-
:::warning
4-
**Note:** Work is in progress 🚧
5-
:::
3+
This page is the practical mental model for writing Acode plugins: what Acode does, what your plugin must do, and what happens during load/unload.
64

7-
We are currently working on this section to provide you with detailed and comprehensive information about how Acode plugins work. Please check back soon for updates!
5+
## The Plugin Contract
86

9-
## Contribute to the Documentation
7+
From Acode's perspective, your plugin is:
108

11-
We welcome contributions from the community! If you would like to help improve this documentation, please visit our [GitHub repository](https://github.com/bajrangCoder/acode-plugin-docs) and follow the contribution guidelines.
9+
1. A folder in `PLUGIN_DIR`
10+
2. A `plugin.json`
11+
3. An entry script (usually `main.js`)
1212

13-
:::tip
14-
You can suggest changes, add new content, or improve existing sections. Every bit of help is appreciated! 🤗
15-
:::
13+
From your perspective, your script should register:
1614

17-
For more information, see official [Guide](https://acode.app/plugin-docs).
15+
- `acode.setPluginInit(pluginId, initFn)`
16+
- `acode.setPluginUnmount(pluginId, unmountFn)` (strongly recommended)
17+
18+
If you skip `setPluginInit`, your script may load, but your plugin logic will not run through Acode's lifecycle.
19+
20+
## Lifecycle In One View
21+
22+
1. Acode discovers plugin folders.
23+
2. It decides which plugins to load (enabled, not broken, not already loaded).
24+
3. It loads your entry script.
25+
4. It calls your registered `init` with runtime context.
26+
5. Later, on disable/uninstall/reload, it calls your registered `unmount`.
27+
28+
## What You Get In `init`
29+
30+
Your init function receives:
31+
32+
- `baseUrl`: internal base URL to your plugin files
33+
- `$page`: a plugin page object for UI screens
34+
- `cache`: object with:
35+
- `cacheFileUrl`
36+
- `cacheFile`
37+
- `firstInit`
38+
- `ctx`
39+
40+
Use `firstInit` for one-time setup or migration.
41+
42+
## Recommended `main.js` Shape
43+
44+
```js
45+
import plugin from "../plugin.json";
46+
47+
function init(baseUrl, $page, cache) {
48+
const commands = acode.require("commands");
49+
50+
commands.addCommand({
51+
name: "example.open",
52+
description: "Open Example Panel",
53+
exec: () => {
54+
$page.innerHTML = "<h2>Example Plugin</h2>";
55+
$page.show();
56+
},
57+
});
58+
}
59+
60+
function unmount() {
61+
const commands = acode.require("commands");
62+
commands.removeCommand("example.open");
63+
}
64+
65+
acode.setPluginInit(plugin.id, init);
66+
acode.setPluginUnmount(plugin.id, unmount);
67+
```
68+
69+
## What Happens On Disable / Enable / Uninstall
70+
71+
- Disable:
72+
- Acode calls `acode.unmountPlugin(id)` which triggers your unmount.
73+
- Plugin runtime state is cleared (including plugin cache file).
74+
- Enable:
75+
- Acode loads the plugin again and runs init again.
76+
- Uninstall:
77+
- Plugin files are removed.
78+
- Acode runs unmount cleanup for loaded resources.
79+
80+
Treat `init` as repeatable and `unmount` as mandatory cleanup.
81+
82+
## Failure Behavior You Should Know
83+
84+
If your plugin throws during load/init:
85+
86+
- it is marked as broken for the session flow,
87+
- Acode skips loading it again until user/action retries it.
88+
89+
For programmatic recovery:
90+
91+
```js
92+
acode.clearBrokenPluginMark("com.example.plugin");
93+
```
94+
95+
## Author Guidelines
96+
97+
- Keep `init` fast; do heavy work lazily.
98+
- Register commands through `acode.require("commands")`.
99+
- Always remove listeners, commands, intervals, and UI hooks in `unmount`.
100+
- Avoid storing important state only in memory; use cache/settings when needed.

0 commit comments

Comments
 (0)