DOCSEARCHbyAlgolia
Submit Docs

utterances

repository·master·Indexed 27 days ago

https://github.com/utterance/utterances

A lightweight, open-source comments widget that uses GitHub issues as a backend for storing and managing comments on websites, blogs, or wikis. Built with vanilla TypeScript and GitHub's Primer CSS, it provides a privacy-focused alternative to traditional comment systems by storing all data in the user's GitHub repository.

Tokens
2.5K
Snippets
3
Records
26
Agent score
94%

What's inside utterances

  1. Overview of Utterances

    master
    Utterances is a lightweight comments widget that uses GitHub issues to store comment data. It is designed to be privacy-focused (no tracking or ads), free, and avoids vendor lock-in because all data resides in your GitHub repository. It uses GitHub's Primer CSS toolkit for styling and supports a dark theme. The widget is built with vanilla TypeScript and is optimized for performance by avoiding heavy JavaScript frameworks or font downloads.

  2. How Utterances works

    master

    Utterances identifies the correct GitHub issue for a page by searching the GitHub issue search API using the page's url, pathname, or title.

    • Issue Creation: If no matching issue is found, the utterances-bot will automatically create a new issue the first time a user attempts to comment.
    • Commenting: Users can comment by authorizing the utterances app via the GitHub OAuth flow, which allows the app to post on their behalf. Alternatively, users can navigate to GitHub and comment directly on the associated issue.

  3. Embed the utterances widget via script tag

    master

    To use the utterances widget, embed the client script into your HTML. The script automatically gathers configuration from its own data-* attributes and from page metadata (like <link rel='canonical'> and <meta name='description'>).

    Supported configuration attributes (passed via data-*):

    • theme: The visual theme for the widget. You can also use data-theme.
    • Other attributes are automatically extracted from the script tag and passed to the iframe.

    Note: The widget will automatically attempt to use the user's preferred theme if data-theme is not explicitly set.

  4. Load a JSON file from the repository

    master
    Use loadJsonFile<T>(path, html) to fetch and parse a file from the repository. If html is set to true, it returns the raw text instead of parsing JSON. The file is fetched from the master branch by default. If the file is a JSON file, it automatically handles Base64 decoding.

  6. Create a new issue

    master
    Use createIssue to create a new issue in the current repository context. This is typically used to initialize a discussion container for a specific topic. The function constructs a body containing the title, description, and a link to the document URL.

  7. Search for an issue by a specific term

    master
    Use loadIssueByTerm(term) to find an issue where the term appears in the title. The function performs a GitHub search for issues in the current repository context. It returns the first issue that matches the term (case-insensitive) or null if no issues are found.

  10. Generate the reactions selection menu with `getReactionsMenuHtml`

    master

    Use getReactionsMenuHtml to generate the HTML for a popover menu that allows users to select a reaction.

    Parameters:

    • url: The endpoint URL for the reaction action.
    • align: The alignment of the menu, either 'center' or 'right'.

    If align is set to 'center', the menu is positioned using left: 50%; transform: translateX(-50%) and the summary element is given tabindex="-1".

  12. Generate the sign-in prompt menu with `getSignInToReactMenuHtml`

    master

    Use getSignInToReactMenuHtml to generate the HTML for a popover menu that prompts unauthenticated users to sign in to add a reaction.

    Parameters:

    • align: The alignment of the menu, either 'center' or 'right'.