Skip to content

Getting Started

There are two ways to create srcref URLs: through the web interface or using the programmatic API.

Using the Web Interface

Step 1: Open the Editor

Visit www.srcref.com to open the srcref editor form.

Step 2: Fill in Repository Details

Enter your GitHub repository information:

Field Example Description
Account pambrose GitHub username or org
Repo srcref Repository name
Branch master Branch name (default: master)
Path src/main/.../Main.kt File path within the repo

Step 3: Define Begin Pattern

The Begin Regex determines which line to highlight. For example, to find a function declaration:

fun main

For patterns containing regex metacharacters like parentheses, escape them:

install\(CallLogging\)

Step 4: Optionally Define End Pattern

Leave the End Regex empty to highlight a single line. Fill it in to highlight a range of lines from the begin match to the end match.

Step 5: Generate and Use

  1. Click Generate URL to create the srcref URL
  2. Click View GitHub Permalink to verify it points to the right lines
  3. Click Copy URL to copy the srcref URL to your clipboard
  4. Paste it into your documentation

Editing an Existing URL

Add &edit to any srcref URL to open it in the editor with all fields pre-filled:

# Add &edit to any srcref URL to open it in the editor:
https://www.srcref.com/github?account=pambrose&repo=srcref&branch=master&path=src/main/kotlin/com/pambrose/srcref/Main.kt&bregex=fun+main&boccur=1&boffset=0&btopd=true&edit

Using the Programmatic API

Add the Dependency

dependencies {
    implementation("com.pambrose:srcref:2.0.7")
}

dependencies {
    implementation 'com.pambrose:srcref:2.0.7'
}

<dependency>
    <groupId>com.pambrose</groupId>
    <artifactId>srcref</artifactId>
    <version>2.0.7</version>
</dependency>

  val singleLine =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "fun main",
    )
  // Use the URL in documentation:
  // <a href="$singleLine">View the main function</a>

  val lineRange =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(CallLogging\\)",
      endRegex = "install\\(Compression\\)",
      endOffset = 3,
    )

Example Walkthrough

Let's create a srcref URL that highlights the middleware setup in srcref's own Main.kt — from install(CallLogging) to 3 lines past install(Compression).

Using the Web Form

Enter these values:

Field Value
Account pambrose
Repo srcref
Branch master
Path src/main/kotlin/com/pambrose/srcref/Main.kt
Begin Regex install\(CallLogging\)
Begin Occur 1
Begin Offset 0
Begin Top-Down true
End Regex install\(Compression\)
End Occur 1
End Offset 3
End Top-Down false

Using the API

  val lineRange =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "install\\(CallLogging\\)",
      endRegex = "install\\(Compression\\)",
      endOffset = 3,
    )

Both approaches produce a URL that, when clicked, redirects to the exact GitHub lines showing the middleware configuration — no matter how the surrounding code changes.

Common Patterns

Here are some patterns you'll use frequently:

Highlight a Function

  val functionLink =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Urls.kt",
      beginRegex = "internal fun calcLineNumber",
      endRegex = "^\\ \\ \\}",
      endTopDown = false,
    )

Highlight a Class

  val classLink =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/ContentCache.kt",
      beginRegex = "internal class ContentCache",
      endRegex = "^\\}",
      endTopDown = false,
    )

Highlight All Imports

  val importLink =
    srcrefUrl(
      account = "pambrose",
      repo = "srcref",
      path = "src/main/kotlin/com/pambrose/srcref/Main.kt",
      beginRegex = "^import",
      beginOccurrence = 1,
      endRegex = "^import",
      endTopDown = false,
    )

What's Next?