Support regions and line numbers within `@includeCode` tag reference

[shawninder]

Search terms

@knodes/typedoc-plugin-code-blocks, typedoc@v0.23, typedoc@v0.27, @codeblock

Question

Back in typedoc 0.23, I could use the @knodes/typedoc-plugin-code-blocks plugin to include bits of code from other files into markdown files which would end up as doc pages thanks to typedoc-plugin-pages.

For example, consider a source file examples/basic-usage.ts:

// #region import
import sum from '../src/sum'
// #endregion import

console.log(
  // #region functionCall
  sum(3, 4)
  // #endregion functionCall
)

and a markdown file pages/basic-usage.md:

# Sum

## Basic usage
### import the function
{@codeblock examples/basic-usage.ts#import}

### call the function
{@codeblock examples/basic-usage.ts#functionCall}

Then, in typedoc.json, I would have:

{
  "pluginPages": {
    "pages": [{
      "name": "Docs",
      "children": [{
        "name": "Basic Usage",
        "source": "basic-usage.md"
      }]
    }]
  }
}

Well, it seems the @knodes/typedoc-plugin-code-blocks plugin isn't compatible with more recent versions of typedoc…

Is it still possible do achieve something like this, perhaps using a different plugin? I tried using typedoc-plugin-include-example, but that seems only to work in typescript files and not in markdown files.

The reason I want this is because I want to include thoughtfully composed guides in my docs (hence the markdown) which include code samples that are taken directly from example files which I actually run in my tests. This ensures that the code samples in the docs never fall out of sync with the actual code and are all tested.

[Gerrit0]

You can almost completely do this with just TypeDoc today.

TypeDoc supports including additional markdown documents as of 0.27: https://typedoc.org/documents/External_Documents.html

This can be combined with the @includeCode tag to include a code block from another file: https://typedoc.org/documents/Tags.__include_.html The one place where this doesn't work today is within the root README file, which is an oversight I just corrected with 4f518a6.

[shawninder]

Thanks for such a quick response :)

This is great, but I was hoping to find a way to include only parts of a file, not the full file. I tried:

• {@includeCode ../examples/basic.ts#regionName} with regions defined between // #region regionName and // #endregion regionName à la @knodes/typedoc-plugin-code-blocks
• {@includeCode ../examples/basic.ts:1-5} à la typedoc-plugin-include-example

but neither works.

If this is something that Typedoc can't currently do but which you'd be open about, I could try my hand at a PR, although I would appreciate being pointed in the right direction…

[Gerrit0]

Oh, ew... I can see why you want that, but that's a really unfortunate thing to need.... The #regionName is definitely better from the standpoint of maintaining the includes. With line numbers adding an additional test anywhere but the end of the file could easily break includes.

The #regionName syntax is unfortunate as we really should probably recognize regions like VSCode does, which varies by file type: VSCode folding

All the logic for the include plugin is in src/lib/converter/plugins/IncludePlugin.ts, PR welcome!

[krisztianb]

Sounds a bit like a feature request somebody once had for my plugin: krisztianb/typedoc-plugin-replace-text#4

Maybe this helps you.