srcref - Dynamic Line-Specific GitHub Permalinks

It is problematic to embed line-specific GitHub permalinks in documentation because changes to the target file can invalidate the permalink line references.

srcref is a simple utility that allows you to embed GitHub permalinks into your docs without worrying about the line numbers of the code changing.

A public instance of srcref is available at www.srcref.com, but you can run your own server as well.

Usage

1. Enter the srcref information in the form here. The regex values use this syntax. Remember to protect regex characters like (), [] and {} by prefixing them with a \. Use regex101.com to assist in creating regex values.
2. If the End Regex field is empty, the srcref URL will highlight a single line on GitHub.
3. Click the "Generate URL" button to generate the srcref URL.
4. Click the "View GitHub Permalink" button to verify the line-specific GitHub permalink.
5. Click the "Copy URL" button to copy the srcref URL to your clipboard.
6. Paste the srcref URL into your documentation.

Example

To highlight all the lines from the first occurrence of install(CallLogging) to 3 lines beyond the first occurrence of install(Compression) in src/main/kotlin/Main.kt, create a srcref URL using these values .

The corresponding srcref URL generates this GitHub permalink .

Query Parameters

Parameter	Default	Required	Description
account		Yes	GitHub account or organization name
repo		Yes	Repo name
branch	"master"	Yes	Branch name
path		Yes	File path in repo
bregex		Yes	The regex used to determine the beginning match
boccur	1	Yes	The number of matches for the beginning match
boffset	0	Yes	The number of lines above or below the beginning match
btopd	true	Yes	The direction to evaluate the file for the beginning match
eregex		No	The regex used to determine the ending match
eoccur	1	No	The number of matches for the ending match
eoffset	0	No	The number of lines above or below the ending match
etopd	true	No	The direction to evaluate the file for the ending match

Editing a srcref URL

Add &edit to a srcref URL to edit it.

Programmatic Usage

srcref URLs can be generated programmatically with the srcrefUrl() call. An example can be seen here .

Gradle:

allprojects {
   repositories {
      maven { url 'https://jitpack.io' }
   }
}

dependencies {
  implementation 'com.github.pambrose:srcref:1.8.0'
}

Maven:

<repositories>
   <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
   </repository>
</repositories>

<dependency>
   <groupId>com.github.pambrose</groupId>
   <artifactId>srcref</artifactId>
  <version>1.8.0</version>
</dependency>

Deploying a srcref server

Environment variables available with a srcref server:

Env Var	Default	Description
PORT	8080	HTTP port to listen on
PREFIX	"https://www.srcref.com"	Prefix for URLs
MAX_LENGTH	5MB	Maximum allowed file size
MAX_CACHE_SIZE	2048	Maximum cache size before evictions
DEFAULT_BRANCH	"master"	Default branch name to use if branch parameter is missing