How to parse additional markdown files?

[Sayan751]

Search terms

• additional markdown
• parsing
• lexing
• tokenization
• reflection
• plugin

Question

I have written a plugin that reads all the non-root/non-readme markdown files and creates HTML files out of those. Additionally it also supports some custom inline-tags. This process looks roughly as follows:

// The plugin code is abbreviated for the purpose of discussing the root issue.
function load(app) {
  app.renderer.on({
    [Renderer.EVENT_END_PAGE]: renderMarkdownPage.bind(app),
  });
}

function renderMarkdownPage(pageEvent) {
  if (!(model instanceof MarkdownReflection)) return; // <- MarkdownReflection: my custom reflection class

  pageEvent.contents = /** @type {DefaultTheme} */ (this.renderer.theme)
    .getRenderContext(pageEvent)
    .markdown(model.content) // <-- Markdown content
}

This works as expected except one problem. If the additional markdown files contain inline tags like {@link} those remain untouched and are not converted. So I thought to perform the same stuffs that is done for the project readme. However, I see that the relevant components are not exported from the package and additional exports are blocked via the exports in the package.json.

Is there any work around for this? Or am I looking at the wrong places, and there is a easier way to achieve this?

[Gerrit0]

I tend to not expose new functions unless I have a request or it's immediately obvious to me when implementing that it will be useful in the same form as used by TypeDoc to plugin devs, in this case, I hadn't thought about this use case yet. Sounds like this is something that should be exposed.

[Gerrit0]

Converter.parseRawComment should do what you're after :)

[Sayan751]

@Gerrit0 Thank you for this. I still think that this part of the API is still not optimal for my purpose. With your exposed API I have tried this:

const converter = app.converter;

// parse the markdown content
const parsed = converter.parseRawComment(new MinimalSourceFile(model.content, model.filePath));
const programs = /** @type {DocumentationEntryPoint[]} */(app.getEntryPoints()).map(ep => ep.program);

// create a new project so that the link resolver can resolve the links in readme.
const project = new ProjectReflection(converter.name);
project.readme = parsed.summary;

// lastly raise an event so that all listners can do their magic
converter.trigger(Converter.EVENT_RESOLVE_END, new Context(converter, programs, project));

However, ultimately it did not help as the target of the @link can still not be resolved (I guess because of the empty reflections in the new package). Is there any workaround for this? I also see that the Converter does not cache the program it creates in the convert(), otherwise that could have been reused to create a new project here in this case.

Additionally, I think it is better to expose the displayPartsToMarkdown as well, so that following usages can be supported, without essentially duplicating code from the TypeDoc source:

const theme = /** @type {DefaultTheme} */ (app.renderer.theme).getRenderContext(pageEvent);
theme.markdown(displayPartsToMarkdown(project.readme, theme.urlTo))

Either that or better encapsulation for the markdown conversion.

[Sayan751]

@Gerrit0 Please consider reopening this.

[Gerrit0]

Hmm... resolving links is something I haven't thought about exposing. I should probably expose a parseDeclarationReference(s: string): DeclarationReference | undefined and a reflection.resolveDeclarationReference(x: DeclarationReference).

I don't want to expose displayPartsToMarkdown as is, without resolving the todo comment in it... haven't figured out a good design for that yet. Short term, should probably just change the markdown helper on DefaultThemeRenderContext to also accept a CommentDisplayPart[]

[Sayan751]

Short term, should probably just change the markdown helper on DefaultThemeRenderContext to also accept a CommentDisplayPart[]

That sounds good as well.

[Sayan751]

@Gerrit0 Thanks for the changes. It seems to work pretty well.