src-link generator

[onmax]

Describe the feature

I'd like to propose a new generator for AutoMD that helps automate the process of linking to specific lines in GitHub files by looking for patterns. The goal is to reduce the manual effort of maintaining line numbers in the documentation when linking to GitHub files.

We currently use links like this:

Check the [schema source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts#L83) for all available hooks.

This works, but requires us to manually enter and maintain line numbers, which can change over time as the source code evolves.

Proposed solution

Introduce a new automd:link generator that automatically fetches a file from a GitHub repository, searches for a specified pattern, and generates a link with the correct line highlighting based on the location of the pattern.

Proposed syntax:

<!-- automd:link url="gh:nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts" pattern="export interface NuxtHooks {" label="schema source code" -->
<!-- /automd -->

Parameters:

• url: The GitHub URL where the file is located.
• pattern: The pattern (e.g. function name, method, etc.) to search for in the file. This can be also a JS Regex.
• label: The text for the link to appear in the markdown output.

Instead of writing:

Check the [schema source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts#L53) for all available hooks.

We could simplify it like this:

Check the <!-- automd:link url="gh:nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts" pattern="export interface NuxtHooks" label="schema source code" --> for all available hooks.

AutoMD would fetch the file, search for the pattern export interface NuxtHooks, and generate the appropriate link with the correct line number.

Advantages

• Automatic line highlighting: The line number is automatically generated based on the search pattern, ensuring it's always accurate, even if the source code changes.
  Reduced manual updates: No need to manually update line numbers in the documentation as the code evolves.
• Improved documentation consistency: Ensures that all links in the documentation point to the correct line number without human error.

Implementation notes

• The generator would work similarly to automd:fetch, but instead of fetching the full file contents, it would search for the specified pattern and return a markdown link with the GitHub file and the correct line number.
• For more flexibility, additional parameters could be added, such as highlightLines, to specify whether only one line or a range of lines should be highlighted.
• In case of no pattern found or multiple matches found, a warning will be printed and the code will not reference any lines.

PS: This is a problem I was facing few weeks ago

Additional information

• Would you be willing to help implement this feature?

[pi0]

I like this idea. I think it can also support local files like <automd:coderef src="../src/mod.ts">

---

A completely alternative way btw is to use a browser (chromium only: chrome, edge, opera, brave) feature using #:~:text= pattern matcher.

Docs: https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments

Try this: https://github.com/nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts#:~:text=export%20interface%20NuxtHooks (open in external tab)

[onmax]

Using #:~:text=export%20interface%20NuxtHooks does not work for me neither in Brave nor Chrome. GitHub is cleaning the url. It removes eveything after the #. Nonetheless, I will try to hack something and submit a PR :)

[pi0]

It works if you open above link as an external link on chrome.

https://github.com/nuxt/nuxt/blob/main/packages/schema/src/types/hooks.ts#:~:text=export%20interface%20NuxtHooks

PR is welcome thanks 👍🏼