{"id":28374751,"url":"https://github.com/markedit-app/markedit-api","last_synced_at":"2025-06-26T02:32:25.693Z","repository":{"id":268673180,"uuid":"853764121","full_name":"MarkEdit-app/MarkEdit-api","owner":"MarkEdit-app","description":"Type definitions for the latest MarkEdit API.","archived":false,"fork":false,"pushed_at":"2025-06-19T02:20:03.000Z","size":39,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-19T03:28:22.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MarkEdit-app.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-07T13:24:38.000Z","updated_at":"2025-06-19T02:19:35.000Z","dependencies_parsed_at":"2025-01-02T09:21:25.230Z","dependency_job_id":"af1eaf43-c522-43f1-b0a0-0c8c2af368ab","html_url":"https://github.com/MarkEdit-app/MarkEdit-api","commit_stats":null,"previous_names":["markedit-app/markedit-api"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/MarkEdit-app/MarkEdit-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkEdit-app%2FMarkEdit-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkEdit-app%2FMarkEdit-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkEdit-app%2FMarkEdit-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkEdit-app%2FMarkEdit-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarkEdit-app","download_url":"https://codeload.github.com/MarkEdit-app/MarkEdit-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarkEdit-app%2FMarkEdit-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261986689,"owners_count":23240689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T22:10:57.230Z","updated_at":"2025-06-26T02:32:25.678Z","avatar_url":"https://github.com/MarkEdit-app.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MarkEdit-api\n\nType definitions for the latest [MarkEdit](https://github.com/MarkEdit-app/MarkEdit) API.\n\n## References\n\n- [MarkEdit Customization Guide](https://github.com/MarkEdit-app/MarkEdit/wiki/Customization)\n- [List of Extensions](https://github.com/MarkEdit-app/MarkEdit/wiki/Extensions)\n- [Example: Markdown Table Editor](https://github.com/MarkEdit-app/MarkEdit-mte)\n- [Example: Text Highlight](https://github.com/MarkEdit-app/MarkEdit-highlight)\n- [Example: Vue Language Package](https://github.com/MarkEdit-app/MarkEdit-lang-vue)\n\n## Usage\n\n\u003e The general workflow for creating a MarkEdit script involves leveraging [CodeMirror extensions](https://codemirror.net/docs/extensions/) or [Lezer parsers](https://lezer.codemirror.net/) to modify the app's behavior.\n\nAdd `markedit-api` to your (TypeScript) project's devDependencies:\n\n```json\n{\n  \"devDependencies\": {\n    \"markedit-api\": \"https://github.com/MarkEdit-app/MarkEdit-api#v0.10.0\"\n  }\n}\n```\n\nImport type declarations with:\n\n```ts\nimport { MarkEdit } from 'markedit-api';\n```\n\nThe `MarkEdit` object provides these interfaces:\n\n```ts\ninterface MarkEdit {\n  // Configuration of the current editor.\n  editorConfig: Record\u003cstring, unknown\u003e;\n  // User-defined settings loaded from the settings.json file.\n  userSettings: JSONObject;\n  // CodeMirror EditorView instance of the current editor.\n  editorView: EditorView;\n  // Convenient text editing interfaces.\n  editorAPI: TextEditable;\n  // CodeMirror modules used by MarkEdit.\n  codemirror: { view, state, language, commands, search };\n  // Lezer modules used by MarkEdit.\n  lezer: { common, highlight, markdown, lr };\n  // Get notified when the editor is initialized.\n  onEditorReady(listener: (editorView: EditorView) =\u003e void): void;\n  // Get information of the current file.\n  getFileInfo(): Promise\u003cFileInfo | undefined\u003e;\n  // Get all items from the native pasteboard.\n  getPasteboardItems(): Promise\u003cPasteboardItem[]\u003e;\n  // Get the string from the native pasteboard.\n  getPasteboardString(): Promise\u003cstring | undefined\u003e;\n  // Add an extension to MarkEdit.\n  addExtension(extension: Extension): void;\n  // Add a Markdown config to MarkEdit.\n  addMarkdownConfig(config: MarkdownConfig): void;\n  // Add a language to be highlighted (in code blocks) to MarkEdit.\n  addCodeLanguage(language: LanguageDescription): void;\n  // Add a menu item to the status bar.\n  addMainMenuItem(item: MenuItem | MenuItem[]): void;\n  // Present a contextual menu to receive user input.\n  showContextMenu(items: MenuItem[], location?: Point): void;\n  // Present an alert to receive user input.\n  showAlert(alert: Alert): Promise\u003cnumber\u003e;\n  // Present a text box to receive user input.\n  showTextBox(textBox?: TextBox): Promise\u003cstring | undefined\u003e;\n  // Present a save panel for saving the file.\n  showSavePanel(options: SavePanelOptions): Promise\u003cnumber\u003e;\n}\n```\n\nAlso, you can import and use [CodeMirror](https://codemirror.net/) and [Lezer](https://lezer.codemirror.net/) dependencies like this:\n\n```ts\nimport { keymap } from '@codemirror/view';\nimport { Prec } from '@codemirror/state';\nimport { Tag } from '@lezer/highlight';\nimport { MarkdownConfig } from '@lezer/markdown';\n```\n\nBuild [CodeMirror extension](https://codemirror.net/docs/extensions/) with these dependencies, and add it to MarkEdit with:\n\n```ts\nMarkEdit.addExtension(extension); // Can also add an array of extensions\n```\n\nBuild [MarkdownConfig](https://github.com/lezer-parser/markdown?tab=readme-ov-file#user-content-markdownconfig) with these dependencies, and add it to MarkEdit with:\n\n```ts\nMarkEdit.addMarkdownConfig(config);\n```\n\nMarkEdit supports syntax highlighting for code blocks, you can also build your own [Language Package](https://codemirror.net/examples/lang-package/), and add it to MarkEdit with:\n\n```ts\nMarkEdit.addCodeLanguage(language);\n```\n\n\u003e While extensions and configs can theoretically be added at any time, it is recommended that they be added immediately after loading the script.\n\n## Handling User Input\n\nWhile you can certainly build user interfaces with JavaScript and CSS, leveraging native UI components might be a better option.\n\nTo create UI entries for your features, you can use the [addMainMenuItem](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+addMainMenuItem\u0026type=code) function, which adds an item to the \"Extensions\" submenu of the main menu, with keyboard shortcuts support.\n\nTo request user input, try using [showContextMenu](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+showContextMenu\u0026type=code), [showAlert](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+showAlert\u0026type=code), and [showTextBox](https://github.com/search?q=repo%3AMarkEdit-app%2FMarkEdit-api+showTextBox\u0026type=code).\n\n## Building\n\nIn your build configuration, mark used MarkEdit and CodeMirror dependencies as `external`.\n\nHere is an example of [vite](https://vitejs.dev/) config:\n\n```ts\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  build: {\n    rollupOptions: {\n      external: [\n        'markedit-api',\n        '@codemirror/view',\n        '@codemirror/state',\n        // ...\n      ],\n    },\n    lib: {\n      entry: 'main.ts',\n      formats: ['cjs'], // CommonJS\n    },\n  },\n});\n```\n\n\u003e Note: If you're using packages that are **not** supported in MarkEdit, such as leveraging [@codemirror/lang-vue](https://github.com/codemirror/lang-vue) to add syntax highlighting for Vue, they should **not** be marked as external.\n\nIt is recommended to build as [cjs](https://commonjs.org/), building as [umd](https://github.com/umdjs/umd) should work too. If you build it as an [iife](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), make sure to replace imports as globals like this:\n\n```\nrollupOptions: {\n  external: [\n    'markedit-api',\n    '@codemirror/view',\n    '@codemirror/state',\n  ],\n  output: {\n    globals: {\n      'markedit-api': 'MarkEdit',\n      '@codemirror/view': 'MarkEdit.codemirror.view',\n      '@codemirror/state': 'MarkEdit.codemirror.state',\n    },\n  },\n},\n```\n\nThe reason is to ensure that user scripts and MarkEdit use the same modules, rather than being separately bundled from different projects.\n\nThe final step is to copy the built script to `~/Library/Containers/app.cyan.markedit/Data/Documents/scripts/`, and restart the app.\n\nEnsure the build system produces a single JavaScript file. If the build generates multiple chunks, you can use [vite-plugin-singlefile](https://github.com/richardtallent/vite-plugin-singlefile) to bundle everything into one file.\n\n\u003e [!TIP]\n\u003e You can also use [MarkEdit-vite](https://github.com/MarkEdit-app/MarkEdit-vite) to simplify the workflow.\n\n## Using JavaScript\n\nIf you just want to quickly prototype with JavaScript, you can directly access CodeMirror and MarkEdit interfaces through objects assigned to the `MarkEdit` object. For example:\n\n```js\nconst keymap = MarkEdit.codemirror.view.keymap;\nconst editorAPI = MarkEdit.editorAPI;\n```\n\n----\n\nFor complete examples, refer to [Example: Markdown Table Editor](https://github.com/MarkEdit-app/MarkEdit-mte), [Example: Text Highlight](https://github.com/MarkEdit-app/MarkEdit-highlight) and [Example: Vue Language Package](https://github.com/MarkEdit-app/MarkEdit-lang-vue).\n\nAlso, [markedit.d.ts](./markedit.d.ts) is fully typed and documented, use it as the API reference.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkedit-app%2Fmarkedit-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkedit-app%2Fmarkedit-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkedit-app%2Fmarkedit-api/lists"}