{"id":51402705,"url":"https://github.com/mcclowes/docusaurus-plugin-omg","last_synced_at":"2026-07-04T08:03:31.255Z","repository":{"id":353055030,"uuid":"1217767314","full_name":"mcclowes/docusaurus-plugin-omg","owner":"mcclowes","description":"Docusaurus plugin to embed omg.lol content (statuses, weblog posts, pastes) in your site","archived":false,"fork":false,"pushed_at":"2026-05-26T08:04:37.000Z","size":2750,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T10:04:42.219Z","etag":null,"topics":["docusaurus","oas","openapi","plugin"],"latest_commit_sha":null,"homepage":"https://docusaurus-plugins.mcclowes.com/docs/omg/overview","language":"TypeScript","has_issues":true,"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/mcclowes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T07:43:05.000Z","updated_at":"2026-05-26T08:00:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"0ea8dad0-f827-4d77-a595-8de50bd134af","html_url":"https://github.com/mcclowes/docusaurus-plugin-omg","commit_stats":null,"previous_names":["mcclowes/docusaurus-plugin-omg"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mcclowes/docusaurus-plugin-omg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcclowes%2Fdocusaurus-plugin-omg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcclowes%2Fdocusaurus-plugin-omg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcclowes%2Fdocusaurus-plugin-omg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcclowes%2Fdocusaurus-plugin-omg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcclowes","download_url":"https://codeload.github.com/mcclowes/docusaurus-plugin-omg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcclowes%2Fdocusaurus-plugin-omg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35114174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["docusaurus","oas","openapi","plugin"],"created_at":"2026-07-04T08:03:30.224Z","updated_at":"2026-07-04T08:03:31.243Z","avatar_url":"https://github.com/mcclowes.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docusaurus-plugin-omg\n\nDocusaurus v3 plugin that compiles [OMG](https://omg.gs/) (OpenAPI Markdown Grammar) source files to OpenAPI 3.1 at build time, ready for any OpenAPI renderer.\n\nOMG is a Markdown DSL for writing API specs — roughly 6× shorter than raw OpenAPI YAML. This plugin runs the `omg-parser` + `omg-compiler` pipeline as part of `docusaurus build` / `docusaurus start` and drops the resulting `.yaml` (or `.json`) on disk so a renderer plugin — [`redocusaurus`](https://github.com/rohit-gohri/redocusaurus), [`docusaurus-plugin-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs), standalone Swagger UI — can pick it up.\n\nDeliberately thin: no bundled renderer, no opinions about how the spec gets displayed.\n\n## Install\n\n```bash\nnpm install docusaurus-plugin-omg\n```\n\n## Configure\n\n```ts title=\"docusaurus.config.ts\"\nimport type { PluginOmgOptions } from 'docusaurus-plugin-omg'\n\nconst omgOptions: PluginOmgOptions = {\n  apis: [\n    { id: 'todo', input: 'api/todo/api.omg.md' },\n    { id: 'billing', input: 'api/billing/api.omg.md', format: 'json' },\n  ],\n}\n\nexport default {\n  plugins: [['docusaurus-plugin-omg', omgOptions]],\n}\n```\n\n### Options\n\n| Option      | Type               | Default        | Notes                                                        |\n| ----------- | ------------------ | -------------- | ------------------------------------------------------------ |\n| `apis`      | `OmgApiInput[]`    | `[]`           | APIs to compile.                                             |\n| `outputDir` | `string`           | `'static/api'` | Default directory for compiled specs, relative to site root. |\n| `format`    | `'yaml' \\| 'json'` | `'yaml'`       | Default output format for APIs that don't override it.       |\n\n### `OmgApiInput`\n\n| Field    | Type               | Default                     | Notes                                                                                         |\n| -------- | ------------------ | --------------------------- | --------------------------------------------------------------------------------------------- |\n| `id`     | `string`           | —                           | Required. Used as the compiled filename when `output` is not set; also surfaced in log lines. |\n| `input`  | `string`           | —                           | Required. Path to the root `.omg.md` file, relative to the Docusaurus site root.              |\n| `output` | `string`           | `\u003coutputDir\u003e/\u003cid\u003e.\u003cformat\u003e` | Output path, relative to the site root.                                                       |\n| `format` | `'yaml' \\| 'json'` | plugin-level `format`       | Overrides the default for this API only.                                                      |\n\nWith the default `outputDir` of `static/api`, the compiled spec lands in your site's `static/` directory and is served at `/api/\u003cid\u003e.yaml` (or `.json`) at runtime. Any renderer can fetch that URL, or a build-time renderer plugin can read the file directly.\n\n## OMG source layout\n\nOMG specs are a root `api.omg.md` plus per-endpoint files in `endpoints/` (and optional `partials/`):\n\n```\napi/todo/\n  api.omg.md                  # info: name, version, baseUrl, auth, servers\n  endpoints/\n    list-todos.omg.md         # method, path, body, responses\n    create-todo.omg.md\n  partials/\n    errors.omg.md             # shared response fragments\n```\n\nThe plugin's `input` points at the root `api.omg.md`; the parser walks the rest.\n\nSee the [OMG syntax reference](https://omg.gs/docs/syntax) for the source format.\n\n## When compilation runs\n\nThe plugin compiles at two points:\n\n1. **Plugin initialisation** (before any other plugin's `loadContent`). This guarantees the compiled spec exists on disk before renderer plugins like `redocusaurus` or `docusaurus-plugin-openapi-docs` try to read it — you can safely declare the OMG plugin alongside a renderer without worrying about plugin order.\n2. **On each `loadContent`** (for hot reload during `docusaurus start`).\n\nCompile errors fail the build loudly with a message identifying the offending api id.\n\n## Watch mode\n\nDuring `docusaurus start` the plugin reports the parent directory of each `input` via `getPathsToWatch`, so edits to `.omg.md` files trigger a rebuild.\n\n## Stale outputs\n\nThe plugin tracks the files it writes in `\u003csiteDir\u003e/.omg/manifest.json`. When you rename or remove an api, the previously-compiled spec is deleted on the next run. Add `.omg/` to your `.gitignore`.\n\n## Handing off to a renderer\n\n### Redocusaurus (Redoc)\n\n```ts\nplugins: [\n  ['docusaurus-plugin-omg', { apis: [{ id: 'todo', input: 'api/todo/api.omg.md' }] }],\n],\npresets: [\n  ['redocusaurus', {\n    specs: [{ id: 'todo', spec: 'static/api/todo.yaml', route: '/api/todo/' }],\n  }],\n],\n```\n\n### docusaurus-plugin-openapi-docs (MDX page per endpoint)\n\n```ts\nplugins: [\n  ['docusaurus-plugin-omg', { apis: [{ id: 'todo', input: 'api/todo/api.omg.md' }] }],\n  ['docusaurus-plugin-openapi-docs', {\n    id: 'api',\n    docsPluginId: 'classic',\n    config: {\n      todo: {\n        specPath: 'static/api/todo.yaml',\n        outputDir: 'docs/api/todo',\n        sidebarOptions: { groupPathsBy: 'tag' },\n      },\n    },\n  }],\n],\n```\n\nBoth plugins will pick up the file the OMG plugin just wrote. Run `docusaurus-plugin-openapi-docs`'s `gen-api-docs` script after each change.\n\n## Example site\n\n```bash\nnpm install\nnpm run build            # build the plugin once\nnpm run example:start    # starts examples/sample-site at http://localhost:3000\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcclowes%2Fdocusaurus-plugin-omg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcclowes%2Fdocusaurus-plugin-omg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcclowes%2Fdocusaurus-plugin-omg/lists"}