What is srcref?

Line-specific GitHub permalinks look like this:


They are typically embedded in documentation, and the resulting page looks like this.

The problem is: what happens when the underlying content changes? All relevant URLs referencing specific lines will need to be checked, and sometimes adjusted. This is obviously problematic and discourages people from embedding line-specific GitHub permalinks in their docs.

srcref attempts to help this problem by using regular expressions to define the beginning and end of the range of lines to be highlighted. In addition, you can specify the occurrence of each match, an offset, above or below a final match, and whether to search top-down or bottom-up, to define the desired range.

When a srcref URL is clicked, the srcref.com server dynamically computes a GitHub permalink with the appropriate line numbers based on the current content of the file.

For example, these values produce a srcref URL that, when clicked, will highlight the lines between the first occurrence of "install\(CallLogging\)" and 6 lines beyond the first occurrence of "install\(Compression\)" in the specified file. Notice that the "()" characters are escaped because we want their literal value, not their regex interpretation.The regex values use this syntax. As mentioned, characters like "()", "[]" and "{}" may require escaping. Use regex101.com to assist in creating regex values.