DOCSEARCHbyAlgolia
Submit Docs

Glade Documentation

website·Indexed 31 days ago

https://docs.glade.app

A JavaScript library and set of web components for adding annotations to web content. Glade allows users to create annotations using markdown or plain text on content wrapped with its specific tags.

Tokens
946
Snippets
4
Records
9
Agent score
49%

What's inside Glade

  1. Overview of Glade's web annotation system

    Glade enables users to create annotations on webpages, treating them as first-class citizens of the web platform. Annotations allow users to highlight portions of a page and add commentary using Markdown. These annotations support various HTML5+ media and can render embeds from all known oEmbed providers.

  2. Integrate Glade annotatable library into a web page

    To enable user annotations on a web page, include the Glade JavaScript library as a module and wrap the target content within the <glade-annotatable> custom element. Any DOM node inside this element becomes clickable for users to sign in and add annotations.
    <!-- 1. Include the library -->
<script
  type="module"
  src="https://unpkg.com/@glade-software/glade-annotatable?module"
></script>

<!-- 2. Wrap content to make it annotatable -->
<glade-annotatable>
  <p>This content can be whatever you want!</p>
  <p>Users will be able to click on it, sign in, and add annotations!</p>
</glade-annotatable>

  3. Format Glade annotations using Markdown and media embeds

    Annotations in Glade support plain text and Markdown, which are rendered via the remark library. To include embedded web media (such as videos), place the media URL on a new line within the annotation. Glade uses the oembed protocol and remark-embedder to automatically render these URLs as embedded content.
    ### Sample Annotation Title

Annotations can include [links](https://developer.mozilla.org/en-US/docs/Glossary/Hyperlink) or embedded media!

For example, here is a video about markdown:

https://www.youtube.com/watch?v=f49LJV1i-_w

  4. Enable web content for Glade annotations

    To make content on a website annotatable using Glade, wrap the desired content with the <glade-annotatable> HTML tag. This allows users to create annotations on the page, which are identified by a blue shimmer on the elements. Glade automatically loads these annotations whenever the document is detected elsewhere.
    <glade-annotatable>
  <!-- Your content here -->
</glade-annotatable>

  5. Understand Glade Document and Referent concepts

    In Glade, a document is not an HTML document, but rather an entire DOM structure contained within a glade-annotatable tag. A referent is the specific portion of the DOM (a DOM node) inside that glade-annotatable tag that an annotation refers to. Currently, referents are not nested deeper than the glade-annotatable tag level.

  6. Understand Glade Annotations

    An annotation is a piece of content created by a user via the Glade GUI. Each annotation is attached to a specific referent and can be authored using either plain text or markdown.

  7. Style nodes that contain Glade annotations

    Glade automatically identifies nodes (referents) that have associated annotations and applies the CSS class glade-has-annotations to those specific DOM nodes. Developers can use this class to apply custom styles to annotated content.

  8. Understand the Glade component lifecycle and DOM hashing

    When the <glade-annotatable> component is rendered, it executes startGlade(), which performs the following sequence:

    1. Node Hashing: Generates a unique identifier (gladeDOMNodeHash) for each node based on its textContent. This hash is added to the DOM node as the data-glade-node-hash attribute.
    2. Document Hashing: Concatenates all node hashes and hashes them again to create a gladeDocumentHash, which serves as the unique identifier for the entire Glade document.
    3. Annotation Retrieval: Fetches annotations from Firestore using the gladeDocumentHash. It matches annotations to DOM nodes by comparing the annotation's gladeDomNodeHash property with the data-glade-node-hash attributes in the DOM.
    4. Styling Application: Applies the glade-has-annotations class to any node that has associated annotations.

  9. Make content annotatable using the glade-annotatable custom element

    Glade provides a web component that augments content to make it annotatable by users. To enable annotations, wrap the target HTML content with the <glade-annotatable> custom element.
    <glade-annotatable>
  <p>Lorem Ipsum</p>
  <p>I don't know latin</p>
</glade-annotatable>