Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support regions and line numbers within @includeCode tag reference #2814

Open
shawninder opened this issue Dec 17, 2024 · 4 comments · May be fixed by #2816
Open

Support regions and line numbers within @includeCode tag reference #2814

shawninder opened this issue Dec 17, 2024 · 4 comments · May be fixed by #2816
Labels
enhancement Improved functionality help wanted Contributions are especially encouraged

Comments

@shawninder
Copy link

Search terms

@knodes/typedoc-plugin-code-blocks, [email protected], [email protected], @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.

@shawninder shawninder added the question Question about functionality label Dec 17, 2024
Gerrit0 added a commit that referenced this issue Dec 18, 2024
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Dec 18, 2024

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
Copy link
Author

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:

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
Copy link
Collaborator

Gerrit0 commented Dec 20, 2024

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
Copy link
Contributor

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

Maybe this helps you.

@shawninder shawninder linked a pull request Dec 22, 2024 that will close this issue
13 tasks
@Gerrit0 Gerrit0 added enhancement Improved functionality help wanted Contributions are especially encouraged and removed question Question about functionality labels Dec 23, 2024
@Gerrit0 Gerrit0 changed the title How can I include code from another file in my README? Support regions and line numbers within @includeCode tag reference Dec 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality help wanted Contributions are especially encouraged
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants