{"id":18376921,"url":"https://github.com/bbc/typescript-docs-verifier","last_synced_at":"2025-08-03T04:10:06.264Z","repository":{"id":33048910,"uuid":"105253850","full_name":"bbc/typescript-docs-verifier","owner":"bbc","description":"Verifies that MarkDown TypeScript documentation snippets compile","archived":false,"fork":false,"pushed_at":"2025-07-18T12:57:08.000Z","size":1508,"stargazers_count":18,"open_issues_count":2,"forks_count":5,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-07-18T14:12:29.282Z","etag":null,"topics":["compilation","documentation","javascript","nodejs","typescript","typescript-library"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":".github/CONTRIBUTING.md","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":"2017-09-29T09:16:49.000Z","updated_at":"2025-07-18T12:57:05.000Z","dependencies_parsed_at":"2024-06-18T19:47:48.473Z","dependency_job_id":"532ace67-4ef6-4837-9870-94f0debeb29a","html_url":"https://github.com/bbc/typescript-docs-verifier","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/bbc/typescript-docs-verifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Ftypescript-docs-verifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Ftypescript-docs-verifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Ftypescript-docs-verifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Ftypescript-docs-verifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/typescript-docs-verifier/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Ftypescript-docs-verifier/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268492472,"owners_count":24258823,"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","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"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":["compilation","documentation","javascript","nodejs","typescript","typescript-library"],"created_at":"2024-11-06T00:25:24.607Z","updated_at":"2025-08-03T04:10:06.254Z","avatar_url":"https://github.com/bbc.png","language":"TypeScript","readme":"# `typescript-docs-verifier`\n\n_Verifies that typescript examples in markdown files actually compile._\n\n[![TypeScript](https://img.shields.io/badge/%3C/%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![Apache 2.0](https://img.shields.io/hexpm/l/plug.svg)](https://www.apache.org/licenses/LICENSE-2.0)\n[![TypeScript docs verifier](https://img.shields.io/badge/checked_with_%E2%9C%93-TS_docs_verifier-blue.svg)](https://github.com/bbc/typescript-docs-verifier)\n\n## Why?\n\nEver copied a TypeScript code example from a README and found that it didn't even compile? This tool can help by verifying that all of your code examples compile correctly. And yes, the TypeScript code samples in this `README` are checked using this tool.\n\n![demo](demo.gif)\n\nInspired the by the [tut](https://github.com/tpolecat/tut) documentation compilation tool for scala.\n\n## How it works\n\nThe selected markdown files are searched for `TypeScript` code blocks marked like this:\n\n````Markdown\n```typescript\n// Some TypeScript code here\nconst write = 'some code';\n```\n````\n\nThese code blocks are extracted and any imports from the current project are replaced with an import of the `main` or `exports` from `package.json` (e.g. `import { compileSnippets } from 'typescript-docs-verifier'` would be replaced with `import { compileSnippets } from './dist/index'` for this project).\n\nEach code snippet is compiled (but not run) and any compilation errors are reported. Code snippets must compile independently from any other code snippets in the file.\n\nThe library can also be used to type check `.tsx` files:\n\n````Markdown\n```tsx\nimport React from 'react'\n\nconst SomeComponent = () =\u003e (\n  \u003cdiv\u003e\n    This is a TSX component!\n  \u003c/div\u003e\n)\n```\n````\n\n### Ignoring code blocks\n\nIndividual code blocks can be ignored by preceding them with a `\u003c!-- ts-docs-verifier:ignore --\u003e` comment:\n\n````Markdown\n\u003c!-- ts-docs-verifier:ignore --\u003e\n```typescript\n// This block won't be compiled by typescript-docs-verifier\n```\n````\n\n## Script usage\n\n```bash\nnode_modules/.bin/typescript-docs-verifier [--input-files \u003cmarkdown-files-to-test\u003e] [--project \u003cpath-to-tsconfig-file\u003e]\n```\n\n- `--input-files` is optional and defaults to `README.md`.\n- `--project` is optional and defaults to the `tsconfig.json` file in the package root.\n- Any compilation errors will be reported on the console.\n- The exit code is 1 if there are any compilation errors and 0 otherwise.\n\n## Library usage\n\n### TypeScript\n\n```typescript\nimport {\n  compileSnippets,\n  SnippetCompilationResult,\n} from \"typescript-docs-verifier\";\n\nconst markdownFiles = [\"README\", \"examples.md\"]; // defaults to 'README.md' if not provided\nconst tsconfigPath = \"docs-tsconfig.json\"; // defaults to the 'tsconfig.json' file in the package root\ncompileSnippets({ markdownFiles, project: tsconfigPath })\n  .then((results: SnippetCompilationResult[]) =\u003e {\n    results.forEach((result: SnippetCompilationResult) =\u003e {\n      if (result.error) {\n        console.log(\n          `Error compiling example code block ${result.index} in file ${result.file}`\n        );\n        console.log(result.error.message);\n        console.log(\"Original code:\");\n        console.log(result.snippet);\n      }\n    });\n  })\n  .catch((error: unknown) =\u003e {\n    console.error(\"Error compiling TypeScript snippets\", error);\n  });\n```\n\n### JavaScript\n\n```javascript\nconst { compileSnippets } = require(\"typescript-docs-verifier\");\n\nconst markdownFiles = [\"README.md\", \"examples.md\"]; // defaults to 'README.md' if not provided\nconst tsconfigPath = \"docs-tsconfig.json\"; // defaults to the 'tsconfig.json' file in the package root\ncompileSnippets({ markdownFiles, project: tsconfigPath })\n  .then((results) =\u003e {\n    results.forEach((result) =\u003e {\n      if (result.error) {\n        console.log(\n          `Error compiling example code block ${result.index} in file ${result.file}`\n        );\n        console.log(result.error.message);\n        console.log(\"Original code:\");\n        console.log(result.snippet);\n      }\n    });\n  })\n  .catch((error) =\u003e {\n    console.error(\"Error compiling TypeScript snippets\", error);\n  });\n```\n\n## Development\n\nRun the tests:\n\n```sh\nnpm install\nnpm test\n```\n\n## Contributing\n\nSee [these notes](./.github/CONTRIBUTING.md) for information for contributors.\n\n## License\n\n`typescript-docs-verifier` is available to all via the [Apache-2.0](./LICENSE) license.\n\nCopyright \u0026copy; 2017 BBC\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Ftypescript-docs-verifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Ftypescript-docs-verifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Ftypescript-docs-verifier/lists"}