Feature Request: Replace with contents from a file

[rasmus-kirk]

I have a folder of examples in my project and I would like to use this plugin to replace references to these example files with the actual code, fx: ::--example: someExample.ts, 15, 32--:: Would become a code block containing lines 15-32 of the someExample.ts file.

The thing that is preventing me from accomplishing it with the current version of this plugin, is that it doesn't seem to support replacing snippets with the contents of other files.

Would you consider supporting this usecase with this plugin? Do you know other non-hacky ways of doing this?

[krisztianb]

Hi. Yes, you are right that the plugin currently doesn't support this. It only supports replacing text (matched by a Regex) with another text.

As far as I know you can include markdown files in comments like this:

/**
 * My test class.
 *
 * [[include ./test.md]]
 */
class Test {}

Does that help you?

To be honest this seems like a rather big change to the plugin. Maybe one should write a new one specifically for this task.

[rasmus-kirk]

All right, thanks for the response. I'll either fork/create a new plugin or just link to the examples using hyperlinks instead.

[krisztianb]

Another solution came to my mind: One could define a function instead of the text that should be used as the replacement. Then the function could do the work (reading things from a file etc.). But I'm not sure if TypeDoc can be configured using a .js instead of a .json file. I will have to investigate this further.

[rasmus-kirk]

That would be a lot more powerful and still pretty clean.

Maybe you could define it in a .json and provide a path to a ts/js file? Something like:

"replaceText": {
    ...
    "includeFunctions": "/some/path/to/functions.ts",
    "replacements": [
        {
            "pattern": "somePattern",
            "replace": "functionDefinedInIncludedFile"
        },
    ]
}

I still do think configuring in js is the better solution, but if its not possible

[krisztianb]

TypeDoc does allow JavaScript configuration files so this should be doable. I will fiddle around with it and let you know.

[krisztianb]

I got this working and you can install it as 2.3.0-beta from NPM.

The replacer function is simply forwarded as an argument to the String.replace method. Here is the information on how that works: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_function_as_the_replacement

There is also a very basic example in the updated README of the beta package.

See how it works for you and please give me feedback.

[rasmus-kirk]

Hello, I installed it and played around with it. It was actually able to do the things I wanted (inlining code examples and linking to specific git commits) and it worked pretty well. I did however later find a repo that provided me with what I needed in a neater way.

I will post my config in a codesnippet in this issue as an example of how the replacer function can be used, either today or tomorrow. After that I will go ahead and close the issue. Thank you.

[krisztianb]

Thanks for reporting back. Glad to hear that you found a solution.

[krisztianb]

Released in 3.0.0