remark-typescript-tools contains two remark plugins to use TypeScript code with remark, to generate better documentation.
Currently it is aimed at docusaurus, but already pretty configurable. And it's open source, pull requests for more configuration options are always welcome ;)
ThetranspileCodeblocks plugin will transpile all yourts-typed codeblocks to JavaScript and displays them side-by-side in tabs.
So
```tsimport {createAction,createReducer }from'@reduxjs/toolkit';const increment=createAction<number>('counter/increment');const decrement=createAction<number>('counter/decrement');const counterReducer=createReducer(0, (builder)=> {builder.addCase(increment, (state,action)=>state+action.payload);builder.addCase(decrement, (state,action)=>state-action.payload);});```will be rendered to this:
It willvalidate the TypeScript on compilation, so your docs will be guaranteed to actually be runnable.It can even workagainst your library source code, which means that any PR that requires an update to your documentation will already get noticed in CI.
Also, 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.
```ts// file: reducers.ts noEmitimport {Reducer }from'@reduxjs/toolkit';declareconst rootReducer:Reducer<{}>;exportdefaultrootReducer;// file: store.tsimport {configureStore }from'@reduxjs/toolkit';importrootReducerfrom'./reducers';const store=configureStore({ reducer:rootReducer });```This 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.
So assuming this source code:
/** * Interface Test! *@remarks * Some more infos. */exportinterfaceTest{/** * This is a function *@remarks * And it is nested! *@overloadSummary * Also, this is a special overload *@overloadRemarks * With some more description *@param foo - some info about the first parameter *@example```tsconsole.log("test")``` */nestedFunction(foo:string):void;/** * This is a function *@remarks * And it is nested! *@overloadSummary * Also, this is a special overload that takes a second parameter *@overloadRemarks * With some more extra description *@param foo - some info about the first parameter *@param bar - and some info about the second parameter *@example```tsconsole.log("test")``` */nestedFunction(foo:string,bar:number):void;}the markdown code
#Infos about Test[summary](docblock://test/linkDocblocks.test.ts?token=Test)##Some more remarks[remarks](docblock://test/linkDocblocks.test.ts?token=Test)
would result in
#Infos about TestInterface Test!##Some more remarksSome more infos.
And you can also link to nested identifiers or function overloads:
#Infos about Test.nestedFunction[summary,remarks](docblock://test/linkDocblocks.test.ts?token=Test.nestedFunction)#Overload 0[overloadSummary,params,overloadRemarks,examples](docblock://test/linkDocblocks.test.ts?token=Test.nestedFunction&overload=0)#Overload 1[overloadSummary,params,overloadRemarks,examples](docblock://test/linkDocblocks.test.ts?token=Test.nestedFunction&overload=1)
will result in
#Infos about Test.nestedFunctionThis is a functionAnd it is nested!#Overload 0Also, this is a special overload####Parameters:-**foo** some info about the first parameterWith some more description\`\`\`tsconsole.log(\\"test\\")\`\`\`#Overload 1Also, this is a special overload that takes a second parameter####Parameters:-**foo** some info about the first parameter-**bar** and some info about the second parameterWith some more extra description\`\`\`tsconsole.log(\\"test\\")\`\`\`
Of course, you can combine this withtranspileCodeblocks, so your examples from your comments from your source code will be actually type-checked against your source code!
We are using the plugins like this over inreduxjs/toolkit:
// site configuration options.const{ resolve}=require('path');const{ linkDocblocks, transpileCodeblocks,}=require('remark-typescript-tools');module.exports={presets:[['@docusaurus/preset-classic',{docs:{remarkPlugins:[[linkDocblocks,{extractorSettings:{tsconfig:resolve(__dirname,'../docs/tsconfig.json'),basedir:resolve(__dirname,'../src'),rootFiles:['index.ts'],},},],[transpileCodeblocks,{compilerSettings:{tsconfig:resolve(__dirname,'../docs/tsconfig.json'),externalResolutions:{'@reduxjs/toolkit':{resolvedPath:resolve(__dirname,'../src'),packageId:{name:'@reduxjs/toolkit',subModuleName:'index.ts',version:'1.0',},},},},},],],},},],],};In addition to that,transpileCodeblocks takes these options:
importtype{Node}from'unist';importtype{VFile}from'vfile';exportinterfaceTranspileCodeblocksSettings{compilerSettings:CompilerSettings;postProcessTranspiledJs?:PostProcessor;postProcessTs?:PostProcessor;assembleReplacementNodes?:(node:CodeNode,file:VFile,virtualFolder:string,virtualFiles:Record<string,VirtualFile>,transpilationResult:Record<string,TranspiledFile>,postProcessTs:PostProcessor,postProcessTranspiledJs:PostProcessor)=>Node[];}interfaceCompilerSettings{tsconfig:string;externalResolutions:Record<string,ExternalResolution>;/** * Allows transforming the virtual filepath for codeblocks. * This allows the files to resolve node modules from a different location * to their own directory. */transformVirtualFilepath?:(filepath:string)=>string;}interfaceCodeNodeextendsNode{lang:string;meta:string;value:string;indent:number[];}exportinterfaceVirtualFile{code:string;skip?:boolean;}exporttypeVirtualFiles=Record<string,VirtualFile>;typePostProcessor=(files:VirtualFiles,parentFile?:string,defaultProcessor?:PostProcessor)=>VirtualFiles;exportinterfaceTranspiledFileextendsVirtualFile{diagnostics:Array<Diagnostic>;}exporttypeTranspiledFiles=Record<string,TranspiledFile>;
