pambrose/srcref repository overview

⁠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

⁠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⁠ .

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

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

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

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

⁠Deploying a srcref server

Environment variables available with a srcref server: