{"id":15130892,"url":"https://github.com/rigwild/apidoc-markdown","last_synced_at":"2025-04-06T07:14:08.537Z","repository":{"id":49792648,"uuid":"184038011","full_name":"rigwild/apidoc-markdown","owner":"rigwild","description":"📝 Generate a Simple and Portable Markdown documentation for your API","archived":false,"fork":false,"pushed_at":"2023-12-22T19:55:53.000Z","size":2159,"stargazers_count":79,"open_issues_count":0,"forks_count":41,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T01:43:42.539Z","etag":null,"topics":["api-documentation","apidoc","command-line","generator","mardown-documentation","markdown","portable","programmatic"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/apidoc-markdown","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/rigwild.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}},"created_at":"2019-04-29T09:09:58.000Z","updated_at":"2024-07-05T12:12:22.000Z","dependencies_parsed_at":"2024-06-18T13:52:55.800Z","dependency_job_id":"fef427ff-553d-4c6b-9cce-7c27df180362","html_url":"https://github.com/rigwild/apidoc-markdown","commit_stats":{"total_commits":181,"total_committers":10,"mean_commits":18.1,"dds":"0.26519337016574585","last_synced_commit":"e8721d7f5032d0e5fbda37ab2da64489867bf38f"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigwild%2Fapidoc-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigwild%2Fapidoc-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigwild%2Fapidoc-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigwild%2Fapidoc-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rigwild","download_url":"https://codeload.github.com/rigwild/apidoc-markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445680,"owners_count":20939961,"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":["api-documentation","apidoc","command-line","generator","mardown-documentation","markdown","portable","programmatic"],"created_at":"2024-09-26T03:07:59.865Z","updated_at":"2025-04-06T07:14:08.509Z","avatar_url":"https://github.com/rigwild.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\t\u003cimg width=\"360\" src=\"logo.png\" alt=\"apidoc-markdown logo\" /\u003e\n\t\u003cbr\u003e\n\t\u003cbr\u003e\n\n📝 Generate a Simple and Portable Markdown documentation for your API\n\n[![Node.js CI](https://github.com/rigwild/apidoc-markdown/workflows/Node.js%20CI/badge.svg)](https://github.com/rigwild/apidoc-markdown/actions)\n[![npm package](https://img.shields.io/npm/v/apidoc-markdown.svg?logo=npm)](https://www.npmjs.com/package/apidoc-markdown)\n[![npm downloads](https://img.shields.io/npm/dw/apidoc-markdown)](https://www.npmjs.com/package/apidoc-markdown)\n[![license](https://img.shields.io/npm/l/apidoc-markdown?color=blue)](./LICENSE)\n\n\u003c/div\u003e\n\n# apidoc-markdown\n\n## Before starting\n\n`apidoc-markdown` uses [apiDoc](https://github.com/apidoc/apidoc) internally. To generate your nice Markdown documentation, you first need to add some [apiDoc](https://github.com/apidoc/apidoc) API documentation comments in your code.\n\nTake a look at https://apidocjs.com/ to discover it if it's your first time using it! 😉\n\nYou create your API documentation directly in your code with comments like this:\n\n```ts\n/**\n * @api {post} /admin/invite/new Send Invite\n * @apiPermission GlobalAdmin\n * @apiDescription Create \u0026 email a new Strider invite.\n * @apiName SendInvite\n * @apiGroup Admin\n * @apiVersion 1.0.0\n *\n * @apiExample {curl} CURL Example:\n *    curl -X POST -d invite_code=xoxox -d email=me[at]email.com http://localhost/invite/new\n *\n * @apiParam (RequestBody) {String} invite_code The invite code/token to use in the invitation\n * @apiParam (RequestBody) {String} email The email address of the new user being invited\n */\napp.post('/invite/new', (req, res) =\u003e res.end())\n```\n\n## How does it look? Give me some examples!\n\nSome examples are available in the [`example`](./example) directory.\n\nTake a look at [`example/strider/api.md`](./example/strider/api.md) which shows a real-world example taken from the [Strider](https://github.com/Strider-CD/strider) API.\n\n## Install\n\n```bash\n# For the global CLI\npnpm install --global apidoc-markdown\n\n# For programmatic usage or local project CLI install\npnpm install apidoc-markdown\n```\n\nThen, generate your documentation using your newly added command `apidoc-markdown` or [programmatically](#programmatic-usage-API).\n\n**Note**: Node.js v14+ minimum is required. `apidoc-markdown` uses [`apidoc-light`](https://github.com/rigwild/apidoc-light) internally.\n\n## CLI usage\n\n```\nGenerate a Simple and Portable Markdown documentation for your API.\nUsage: apidoc-markdown -i \u003cpath\u003e -o \u003coutput_file\u003e [-t \u003ctemplate_name\u003e] [--multi] [--createPath] [--prepend \u003cfile_path\u003e]\n\nOptions:\n      --version     Show version number                                                                                            [boolean]\n  -i, --input       Input source files path                                                             [string] [required] [default: \"src\"]\n  -o, --output      Output file or directory to write output to.                                                         [string] [required]\n  -t, --template    Name of the template to be used (`default`, `bitbucket`) or path to an EJS template file.  [string] [default: \"default\"]\n      --header      Path to file content to add at the top of the documentation.                                                    [string]\n      --footer      Path to file content to add at the bottom of the documentation.                                                 [string]\n      --prepend     Path to file content to add before route groups documentation.                                                  [string]\n      --multi       Output one file per group to the `output` directory.                                          [boolean] [default: false]\n      --createPath  Recursively create directory arborescence to the `output` directory.                          [boolean] [default: false]\n  -h, --help        Show help                                                                                                      [boolean]\n\nExamples:\n  apidoc-markdown -i src -o doc.md                           Generate from `src` source files to `doc.md`\n  apidoc-markdown --input src --output doc.md                Generate from `src` source files to `doc.md`\n  apidoc-markdown -i src -o doc.md -t bitbucket              Generate from `src` source files to `doc.md` using the `bitbucket` template\n  apidoc-markdown -i src -o doc.md -t my_custom_template.md  Generate from `src` source files to `doc.md` using a provided template file\n  apidoc-markdown -i src -o doc --multi                      Generate from `src` source files to `doc/\u003cgroup\u003e.md`\n\napidoc-markdown - https://github.com/rigwild/apidoc-markdown\n```\n\n### Examples\n\nGenerate documentation (See [`./example/basic/example.md`](./example/basic/example.md)).\n\n```\napidoc-markdown -i src -o doc.md\n```\n\nYou can select a provided template by using `-t` or `--template` (`default`, `bitbucket`).\n\n```\napidoc-markdown -i src -o doc.md -t bitbucket\n```\n\nYou can pass the path to your own template by using `-t` or `--template`.\n\n```\napidoc-markdown -i src -o doc.md -t my_custom_template.md\n```\n\nYou can inject a header, footer or prepend section in your documentation with the content of a file using `--header`, `--footer` and `--prepend`.\n\n```\napidoc-markdown -i src -o doc.md --header header.md\napidoc-markdown -i src -o doc.md --footer footer.md\napidoc-markdown -i src -o doc.md --prepend prepend.md\n\napidoc-markdown -i src -o doc.md --header header.md --footer footer.md --prepend prepend.md\n```\n\nGenerate documentation with one file per group (See [`./example/multi`](./example/multi)).\n\n```\napidoc-markdown -i src -o doc --multi\n```\n\n### Quick and easy project integration\n\nInstall `apidoc-markdown` as a dev dependency.\n\n```bash\npnpm install -D apidoc-markdown\n```\n\nAdd the following script to your `package.json` file (`src` is where are stored your source files containing some [apiDoc](https://apidocjs.com/) annotations).\n\n```json\n{\n  \"scripts\": {\n    \"doc\": \"apidoc-markdown -i src -o DOCUMENTATION.md\"\n  }\n}\n```\n\nRun the npm script to generate the `DOCUMENTATION.md` file.\n\n```bash\npnpm doc\n```\n\n## Programmatic usage API\n\n#### generateMarkdownFileSystem\n\nGenerate mardown documentation using the file system and creating output file(s).\n\n```ts\nimport path from 'path'\nimport { generateMarkdownFileSystem } from 'apidoc-markdown'\n\nconst documentation: Doc = await generateMarkdownFileSystem({\n  /** Input source files path */\n  input: path.resolve(__dirname, 'path', 'to', 'your', 'sources', 'directory'),\n\n  /** Output file or directory to write output to */\n  output: path.resolve(__dirname, 'doc.md'),\n\n  /** Optional: Name of template to be used (`default`, `bitbucket`)\n   * or path to EJS template file\n   * or raw EJS plain text template\n   * (will use default template if ommitted). */\n  template: 'default',\n\n  /** Optional: Path to file content to add at the top of the documentation */\n  header: path.resolve(__dirname, 'add-this-to-the-top'),\n\n  /** Optional: Path to file content to add at the bottom of the documentation */\n  footer: path.resolve(__dirname, 'add-this-to-the-bottom'),\n\n  /** Optional: Path to file content to add before route groups documentation */\n  prepend: path.resolve(__dirname, 'prepend-this-to-api-routes'),\n\n  /** Optional: Output one file per group to the `output` directory */\n  multi: false,\n\n  /** Optional: Recursively create directory arborescence to the `output` directory */\n  createPath: true\n})\n\n// Output\ntype Doc = Array\u003c{\n  name: string // Api group name\n  content: string // Documentation content\n}\u003e\n\n// (if `multi` is `false`, you get an array with 1 element!)\n```\n\n#### generateMarkdown\n\nGenerate mardown documentation by passing directly the apiDoc output.\n\n```ts\nimport { generateMarkdown } from 'apidoc-markdown'\n\nconst documentation: Doc = await generateMarkdown({\n  /** apiDoc project JSON data object `apidoc.json` file content) */\n  apiDocProjectData: { name: 'test', version: '0.13.0' /* ... */ },\n\n  /** apiDoc documentation JSON data object (`api_data.json` file content) */\n  apiDocApiData: [{ type: 'get', url: '/define' /* ... */ }],\n\n  /** Optional: Name of template to be used (`default`, `bitbucket`)\n   * or path to EJS template file\n   * or raw EJS plain text template\n   * (will use default template if ommitted). */\n  template: 'my EJS template \u003c%= project.name %\u003e v\u003c%= project.version %\u003e',\n\n  /** Optional: Content to add at the top of the documentation */\n  header: 'Add this text at the top of the doc!',\n\n  /** Optional: Content to add at the bottom of the documentation */\n  footer: 'Add this text at the bottom of the doc!',\n\n  /** Optional: Content to add before route groups documentation */\n  prepend: 'Prepend this before the API routes documentation!',\n\n  /** Optional: Generate one documentation output per group */\n  multi: false\n})\n\n// Output\ntype Doc = Array\u003c{\n  name: string // Api group name\n  content: string // Documentation content\n}\u003e\n\n// (if `multi` is `false`, you get an array with 1 element!)\n```\n\n## Configuration\n\n### Using `apidoc.json`\n\nThe `header`, `footer` and `prepend` options can be configured directly in your `apidoc.json` (see [`apidoc.json` documentation](https://apidocjs.com/#configuration)).\n\nAdd it like this:\n\n```json\n{\n  \"name\": \"test\",\n  \"version\": \"0.1.2\",\n  \"description\": \"test\",\n  \"title\": \"test\",\n  \"url\": \"https://test.example.com/\",\n  \"header\": {\n    \"filename\": \"header.md\"\n  },\n  \"footer\": {\n    \"filename\": \"footer.md\"\n  },\n  \"prepend\": {\n    \"filename\": \"prepend.md\"\n  }\n}\n```\n\n**Note:** This only works if you use the CLI or [`generateMarkdownFileSystem`](#generateMarkdownFileSystem).\n\n### API groups order\n\nYou can choose the order in which the documentation groups gets generated by adding an `order` key in `apidoc.json`. [See example `apidoc.json`](./test/_testFiles/input/apidoc.json#L15-L22) and [generated example output](./example/basic/example.md).\n\n**Note:** This is only useful when generating the documentation to a single output file (`multi` is `false`).\n\n## Contribute\n\nShare your custom templates in [this discussion!](https://github.com/rigwild/apidoc-markdown/discussions/24)\n\nSuggest any feature you would like by creating an [issue](https://github.com/rigwild/apidoc-markdown/issues) or a [pull request](https://github.com/rigwild/apidoc-markdown/pulls).\n\nWhen reporting bugs, please fill the issue template correctly with as much info as possible to help me debug and understand what's happening.\n\n⭐ Star the project to help it grow! 😄\n\n## License\n\n[The MIT license](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frigwild%2Fapidoc-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frigwild%2Fapidoc-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frigwild%2Fapidoc-markdown/lists"}