{"id":13727090,"url":"https://github.com/phryneas/remark-typescript-tools","last_synced_at":"2025-10-26T09:50:14.459Z","repository":{"id":41244254,"uuid":"293298132","full_name":"phryneas/remark-typescript-tools","owner":"phryneas","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-20T22:40:48.000Z","size":1338,"stargazers_count":132,"open_issues_count":3,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-12T17:48:13.021Z","etag":null,"topics":["library"],"latest_commit_sha":null,"homepage":"","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/phryneas.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":"2020-09-06T14:51:21.000Z","updated_at":"2025-01-19T09:49:16.000Z","dependencies_parsed_at":"2025-02-15T01:10:24.327Z","dependency_job_id":"ce7c0b79-667b-4beb-acef-015c547ccc13","html_url":"https://github.com/phryneas/remark-typescript-tools","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phryneas%2Fremark-typescript-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phryneas%2Fremark-typescript-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phryneas%2Fremark-typescript-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phryneas%2Fremark-typescript-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phryneas","download_url":"https://codeload.github.com/phryneas/remark-typescript-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582907,"owners_count":22095518,"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":["library"],"created_at":"2024-08-03T01:03:39.068Z","updated_at":"2025-10-26T09:50:09.439Z","avatar_url":"https://github.com/phryneas.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# remark-typescript-tools\n\n## What is it?\n\n`remark-typescript-tools` contains two remark plugins to use TypeScript code with remark, to generate better documentation.\n\nCurrently it is aimed at docusaurus, but already pretty configurable. And it's open source, pull requests for more configuration options are always welcome ;)\n\n### transpileCodeblocks\n\nThe `transpileCodeblocks` plugin will transpile all your `ts`-typed codeblocks to JavaScript and displays them side-by-side in tabs.\n\nSo\n\n````md\n```ts\nimport { createAction, createReducer } from '@reduxjs/toolkit';\n\nconst increment = createAction\u003cnumber\u003e('counter/increment');\nconst decrement = createAction\u003cnumber\u003e('counter/decrement');\n\nconst counterReducer = createReducer(0, (builder) =\u003e {\n  builder.addCase(increment, (state, action) =\u003e state + action.payload);\n  builder.addCase(decrement, (state, action) =\u003e state - action.payload);\n});\n```\n````\n\nwill be rendered to this:\n\n![an animations of tabs switching from TypeScript to JavaScript and back](./assets/tabs.gif)\n\nIt will _validate the TypeScript on compilation_, so your docs will be guaranteed to actually be runnable.\nIt can even work _against your library source code_, which means that any PR that requires an update to your documentation will already get noticed in CI.\n\n![an image of a compilation error](./assets/compileError.png)\n\nAlso, your examples can contain virtual files, importing from each other and you can even hide some of these virtual files, if they are not relevant for the example, but necessary for you to have valid code.\n\n````md\n```ts\n// file: reducers.ts noEmit\nimport { Reducer } from '@reduxjs/toolkit';\ndeclare const rootReducer: Reducer\u003c{}\u003e;\nexport default rootReducer;\n\n// file: store.ts\nimport { configureStore } from '@reduxjs/toolkit';\n\nimport rootReducer from './reducers';\n\nconst store = configureStore({ reducer: rootReducer });\n```\n````\n\n### linkDocblocks\n\nThis plugin allows you to link to sections of your source code's Docblocks, making sure that your documentation is up-to-date with your code.\n\nSo assuming this source code:\n\n````ts\n/**\n * Interface Test!\n * @remarks\n * Some more infos.\n */\nexport interface Test {\n  /**\n     * This is a function\n     * @remarks\n     * And it is nested!\n     * @overloadSummary\n     * Also, this is a special overload\n     * @overloadRemarks\n     * With some more description\n     * @param foo - some info about the first parameter\n     * @example\n```ts\nconsole.log(\"test\")\n```\n     */\n  nestedFunction(foo: string): void;\n  /**\n     * This is a function\n     * @remarks\n     * And it is nested!\n     * @overloadSummary\n     * Also, this is a special overload that takes a second parameter\n     * @overloadRemarks\n     * With some more extra description\n     * @param foo - some info about the first parameter\n     * @param bar - and some info about the second parameter\n     * @example\n```ts\nconsole.log(\"test\")\n```\n     */\n  nestedFunction(foo: string, bar: number): void;\n}\n````\n\nthe markdown code\n\n```md\n# Infos about Test\n\n[summary](docblock://test/linkDocblocks.test.ts?token=Test)\n\n## Some more remarks\n\n[remarks](docblock://test/linkDocblocks.test.ts?token=Test)\n```\n\nwould result in\n\n```md\n# Infos about Test\n\nInterface Test!\n\n## Some more remarks\n\nSome more infos.\n```\n\nAnd you can also link to nested identifiers or function overloads:\n\n```md\n# Infos about Test.nestedFunction\n\n[summary,remarks](docblock://test/linkDocblocks.test.ts?token=Test.nestedFunction)\n\n# Overload 0\n\n[overloadSummary,params,overloadRemarks,examples](docblock://test/linkDocblocks.test.ts?token=Test.nestedFunction\u0026overload=0)\n\n# Overload 1\n\n[overloadSummary,params,overloadRemarks,examples](docblock://test/linkDocblocks.test.ts?token=Test.nestedFunction\u0026overload=1)\n```\n\nwill result in\n\n```md\n# Infos about Test.nestedFunction\n\nThis is a function\n\nAnd it is nested!\n\n# Overload 0\n\nAlso, this is a special overload\n\n#### Parameters:\n\n- **foo** some info about the first parameter\n\nWith some more description\n\n\\`\\`\\`ts\nconsole.log(\\\\\"test\\\\\")\n\n\\`\\`\\`\n\n# Overload 1\n\nAlso, this is a special overload that takes a second parameter\n\n#### Parameters:\n\n- **foo** some info about the first parameter\n- **bar** and some info about the second parameter\n\nWith some more extra description\n\n\\`\\`\\`ts\nconsole.log(\\\\\"test\\\\\")\n\n\\`\\`\\`\n```\n\nOf course, you can combine this with `transpileCodeblocks`, so your examples from your comments from your source code will be actually type-checked against your source code!\n\n## Usage with Docusaurus:\n\nWe are using the plugins like this over in `reduxjs/toolkit`:\n\n```js\n// site configuration options.\nconst { resolve } = require('path');\nconst {\n  linkDocblocks,\n  transpileCodeblocks,\n} = require('remark-typescript-tools');\n\nmodule.exports = {\n  presets: [\n    [\n      '@docusaurus/preset-classic',\n      {\n        docs: {\n          remarkPlugins: [\n            [\n              linkDocblocks,\n              {\n                extractorSettings: {\n                  tsconfig: resolve(__dirname, '../docs/tsconfig.json'),\n                  basedir: resolve(__dirname, '../src'),\n                  rootFiles: ['index.ts'],\n                },\n              },\n            ],\n            [\n              transpileCodeblocks,\n              {\n                compilerSettings: {\n                  tsconfig: resolve(__dirname, '../docs/tsconfig.json'),\n                  externalResolutions: {\n                    '@reduxjs/toolkit': {\n                      resolvedPath: resolve(__dirname, '../src'),\n                      packageId: {\n                        name: '@reduxjs/toolkit',\n                        subModuleName: 'index.ts',\n                        version: '1.0',\n                      },\n                    },\n                  },\n                },\n              },\n            ],\n          ],\n        },\n      },\n    ],\n  ],\n};\n```\n\nIn addition to that, `transpileCodeblocks` takes these options:\n\n```ts\nimport type { Node } from 'unist';\nimport type { VFile } from 'vfile';\n\nexport interface TranspileCodeblocksSettings {\n  compilerSettings: CompilerSettings;\n  postProcessTranspiledJs?: PostProcessor;\n  postProcessTs?: PostProcessor;\n  assembleReplacementNodes?: (\n    node: CodeNode,\n    file: VFile,\n    virtualFolder: string,\n    virtualFiles: Record\u003cstring, VirtualFile\u003e,\n    transpilationResult: Record\u003cstring, TranspiledFile\u003e,\n    postProcessTs: PostProcessor,\n    postProcessTranspiledJs: PostProcessor\n  ) =\u003e Node[];\n}\n\ninterface CompilerSettings {\n  tsconfig: string;\n  externalResolutions: Record\u003cstring, ExternalResolution\u003e;\n  /**\n   * Allows transforming the virtual filepath for codeblocks.\n   * This allows the files to resolve node modules from a different location\n   * to their own directory.\n   */\n  transformVirtualFilepath?: (filepath: string) =\u003e string;\n}\n\ninterface CodeNode extends Node {\n  lang: string;\n  meta: string;\n  value: string;\n  indent: number[];\n}\n\nexport interface VirtualFile {\n  code: string;\n  skip?: boolean;\n}\n\nexport type VirtualFiles = Record\u003cstring, VirtualFile\u003e;\n\ntype PostProcessor = (\n  files: VirtualFiles,\n  parentFile?: string,\n  defaultProcessor?: PostProcessor\n) =\u003e VirtualFiles;\n\nexport interface TranspiledFile extends VirtualFile {\n  diagnostics: Array\u003cDiagnostic\u003e;\n}\n\nexport type TranspiledFiles = Record\u003cstring, TranspiledFile\u003e;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphryneas%2Fremark-typescript-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphryneas%2Fremark-typescript-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphryneas%2Fremark-typescript-tools/lists"}