Documentation

Tentacle is a browser extension for GitHub that allows you to customize your GitHub experience to meet your unique needs.

• Inject content at predefined containers on the GitHub UI.
• Markdown-based syntax with variables, functions and custom tags to build just about anything you want.
• Privacy and security are fundamental principles of Tentacle.

How Tentacle Works

Tentacle observes page navigation events on GitHub. When Tentacle identifies a valid route, it injects a container into the DOM. Currently, there are four predefined containers available, with more to come:

• Repository sidebar
• Pull Request sidebar
• Pull Request merge box
• Global header

Tentacle then loads the corresponding content from a specially designed GitHub issue within your repository. Yes, you heard it right – a GitHub issue serves as your database. This design empowers you to maintain full control of your data. While we may introduce additional storage options in the future, this GitHub issue will remains the primary data store for your content.

At its core, Tentacle is a Markdown renderer that uses Markdoc, originally developed at Stripe to meet the requirements of authoring rich documentation pages. Markdoc provides features not found in standard Markdown, such as variables, functions, and custom tags. Depending on the current page, Tentacle offers different variables within the templating process, and the final output is added to the container.

Variables

Variables allow you to access metadata provided by Tentacle for the current page. For example, you can use the repository name in a URL using $repo.name as follows:

- [Docs](https://company.com/docs/{% $repo.name %})

Available Variables

Tentacle provides variables at different pages, allowing you to tailor your content to your needs. Repository variables are available throughout the entire repository context, from the repository page to individual pull requests within that repository.

Example repository variable:

{
  "repo": {
    "owner": "shinycorp",
    "name": "tentacle-playground",
    "full_name": "shinycorp/my-service",
    "html_url": "https://github.com/shinycorp/my-service",
    "private": true,
    "default_branch": "main"
  }
}

On a Pull Request page, you get additional information that can be used to create target content.

Example Pull Request variables:

{
  "repo": {
    …
  },
  "context": "pullrequest",
  "pr": {
    "head": "ABC-123-fix-prod",
    "base": "main",
    "number": 4,
    "jira_prefix": "ABC-123", // only available if the branch starts with a JIRA prefix
    "labels": [
      "bug"
    ],
    "additions": 2,
    "deletions": 2,
    "changed_files": 2,
    "commits": 3,
    "status": "open"
  }
}

Functions

In addition to variables, you can use functions to transform your content at runtime. Tentacle provides eleven built-in functions: equals, and, or, not, default, gt, get, lt, lte, includes, apiCall, and debug.

Variables and functions enable you to build context-aware content. The following example shows a Post Merge Checklist if the pull request status is merged.

{% if equals($pr.status, "merged")  %}
 - [] Post merge checklist
{% /if %}

Visit the Markdocs Functions docs for more information about functions.

Custom Tags

Custom tags are extensions of standard Markdown that allow you to choose visually appealing UI elements for your content. Tentacle uses components from GitHub's Design System to ensure a native look and feel for your content.

{% flash variant="warning" %}
Upstream service is degraded
{% /flash %}

{% label %}Some label{% /label %}

{% avatar username="stefanbuck" /%}

{% debugState %} This will print the current context {% /debugState %}

Tentacle also integrates GitHub's Repository Custom Properties (currently in beta) into your repository as a custom tag.

{% repositoryCustomProperties /%}

Additional Markdown Features

Tentacle provides additional Markdown features for adding notes, tips, warnings, and important information.

> **note**
> Information the user should notice even if skimming.

> **tip**
> Optional information to help a user be more successful.

> **important**
> Essential information required for user success.

> **attention**
> Negative potential consequences of an action.

> **warning**
> Dangerous certain consequences of an action.

Backstage

If your company uses an internal developer portal like Backstage, you can incorporate that data into your repository.

Example Backstage integration:

{% apiCall url="https://api.github.com/repos/{$repo.full_name}/contents/catalog-info.yaml" as="catalog" /%}

{% backstage data=$catalog /%}

Arbitrary GitHub API Calls

The API function allows you to fetch any content from your repository, unlocking various use cases. Here are a few examples:

# Renders content of checklist.md

{% partial file="tentacle-app/demo/checklist.md" /%}

Partials support variables, allowing you to substitute values at runtime. Learn more about partials support in Markdoc.

{% apiCall url="https://api.github.com/repos/{$repo.full_name}/commits" as="commits" /%}

{% jmesPath json=$commits path='[].commit.message' as="commit_messages" /%}

# Renders recent commit messages
{% $commit_messages /%}

Available Locations

Tentacle provides four predefined locations where you can inject custom content alongside the GitHub UI:

• Repository sidebar
• Pull Request sidebar
• Pull Request merge box
• Global header

Debugging

When working on content, you may need to get a list of all available variables. Use the custom tag {% debugState %} to obtain a list of all available variables on the current page.

Custom React Component

In case the built-in custom tags don't fit your needs, you can create your custom components. Tentacle uses the same API internally.

Example custom React component:

function HelloTentacle() {
  const metadata = useContext(MetadataContext);

  return <div>Hello {metadata.repo.name}</div>;
}

createReactExtension("repo-sidebar", () => {
  return <HelloTentacle />;
});

This is just the beginning, and we have millions of ideas how to enhance Tentacle.