[FEAT] Link to API docs from markdown guides

[griest024]

💡 Feature request

Feature Name

Link to API docs from markdown

The Desired Behavior

@daffodil/tools-dgeni replaces exported symbol links in markdown with daff.io links.

Your Use Case

As a daffodil dev, I want to be able to write API symbols in markdown files and have these replaced by the appropriate daff.io link to the symbol.

Prior Work

dgeni will currently correctly transform links of the form /libs/<package>/<symbol> but this is rather cumbersome. Ideally any public API symbol written in code blocks would be transformed to the appropraite link.

[griest024]

@hanmangokiwi is this something you're interested in tackling?

[shadow0500]

@griest024 you can use this approach

import { Dgeni, Plugin } from '@daffodil/tools-dgeni';

export class LinkToApiDocsPlugin implements Plugin {

  constructor(dgeni: Dgeni) {
    super(dgeni);

    // Register a processor that will replace links to symbols with links to daff.io.
    const linkToApiDocsProcessor = (doc: Document, node: Node) => {
      if (node.type === 'link' && node.attributes['href'].startsWith('daffodil')) {
        // Replace the link with the daff.io link for the symbol.
        node.attributes['href'] = `https://daff.io/docs/${node.attributes['href']}`;
      }
    };

    dgeni.addProcessor('linkToApiDocs', linkToApiDocsProcessor);
  }
}

[xelaint]

@griest024 is this still relevant?

[griest024]

Yes. Many times we will need to link to API symbols in docs (guides and other API docs). These links should be clickable and navigate to the relevant page of the API docs

[griest024]

this can be supported with a slightly goofy /libs/<package>/<symbol> syntax. It would be cool to have code blocks that match any API symbol to automatically get replaced with the link but that requires some interpackage dgeni deps.