npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

rengar-gitment2

v0.0.3

Published

A comment system based on GitHub Issues

Downloads

2

Readme

Gitment

NPM version

Gitment is a comment system based on GitHub Issues, which can be used in the frontend without any server-side implementation.

Demo Page

中文简介

Features

  • GitHub Login
  • Markdown / GFM support
  • Syntax highlighting
  • Notifications from GitHub
  • Easy to customize
  • No server-side implementation

Get Started

1. Install

<link rel="stylesheet" href="https://imsun.github.io/gitment/style/default.css">
<script src="https://imsun.github.io/gitment/dist/gitment.browser.js"></script>

or via npm:

$ npm i --save gitment
import 'gitment/style/default.css'
import Gitment from 'gitment'

2. Register An OAuth Application

Click here to register an OAuth application, and you will get a client ID and a client secret.

Make sure the callback URL is right. Generally it's the origin of your site, like https://imsun.net.

3. Render Gitment

const gitment = new Gitment({
  id: 'Your page ID', // optional
  owner: 'Your GitHub ID',
  repo: 'The repo to store comments',
  oauth: {
    client_id: 'Your client ID',
    client_secret: 'Your client secret',
  },
  // ...
  // For more available options, check out the documentation below
})

gitment.render('comments')
// or
// gitment.render(document.getElementById('comments'))
// or
// document.body.appendChild(gitment.render())

4. Initialize Your Comments

After the page is published, you should visit your page, login with your GitHub account(make sure you're repo's owner), and click the initialize button, to create a related issue in your repo. After that, others can leave their comments.

Methods

constructor(options)

options:

Type: object

  • owner: Your GitHub ID. Required.
  • repo: The repository to store your comments. Make sure you're repo's owner. Required.
  • oauth: An object contains your client ID and client secret. Required.
    • client_id: GitHub client ID. Required.
    • client_secret: GitHub client secret. Required.
  • id: An optional string to identify your page. Default location.href.
  • title: An optional title for your page, used as issue's title. Default document.title.
  • link: An optional link for your page, used in issue's body. Default location.href.
  • desc: An optional description for your page, used in issue's body. Default ''.
  • labels: An optional array of labels your want to add when creating the issue. Default [].
  • theme: An optional Gitment theme object. Default gitment.defaultTheme.
  • perPage: An optional number to which comments will be paginated. Default 20.
  • maxCommentHeight: An optional number to limit comments' max height, over which comments will be folded. Default 250.

gitment.render([element])

element

Type: HTMLElement or string

The DOM element to which comments will be rendered. Can be an HTML element or element's id. When omitted, this function will create a new div element.

This function returns the element to which comments be rendered.

gitment.renderHeader([element])

Same like gitment.render([element]). But only renders the header.

gitment.renderComments([element])

Same like gitment.render([element]). But only renders comments list.

gitment.renderEditor([element])

Same like gitment.render([element]). But only renders the editor.

gitment.renderFooter([element])

Same like gitment.render([element]). But only renders the footer.

gitment.init()

Initialize a new page. Returns a Promise and resolves when initialized.

gitment.update()

Update data and views. Returns a Promise and resolves when data updated.

gitment.post()

Post comment in the editor. Returns a Promise and resolves when posted.

gitment.markdown(text)

text

Type: string

Returns a Promise and resolves rendered text.

gitment.login()

Jump to GitHub OAuth page to login.

gitment.logout()

Log out current user.

goto(page)

page

Type: number

Jump to the target page of comments. Notice that page starts from 1. Returns a Promise and resolves when comments loaded.

gitment.like()

Like current page. Returns a Promise and resolves when liked.

gitment.unlike()

Unlike current page. Returns a Promise and resolves when unliked.

gitment.likeAComment(commentId)

commentId

Type: string

Like a comment. Returns a Promise and resolves when liked.

gitment.unlikeAComment(commentId)

commentId

Type: string

Unlike a comment. Returns a Promise and resolves when unliked.

Customize

Gitment is easy to customize. You can use your own CSS or write a theme. (The difference is that customized CSS can't modify DOM structure)

Use Customized CSS

Gitment does't use any atomic CSS, making it easier and more flexible to customize. You can inspect the DOM structure in the browser and write your own styles.

Write A Theme

A Gitment theme is an object contains several render functions.

By default Gitment has five render functions: render, renderHeader, renderComments, renderEditor, renderFooter. The last four render independent components and render functions render them together. All of them can be used independently.

You can override any render function above or write your own render function.

For example, you can override the render function to put an editor before the comment list, and render a new component.

const myTheme = {
  render(state, instance) {
    const container = document.createElement('div')
    container.lang = "en-US"
    container.className = 'gitment-container gitment-root-container'
    
     // your custom component
    container.appendChild(instance.renderSomething(state, instance))
    
    container.appendChild(instance.renderHeader(state, instance))
    container.appendChild(instance.renderEditor(state, instance))
    container.appendChild(instance.renderComments(state, instance))
    container.appendChild(instance.renderFooter(state, instance))
    return container
  },
  renderSomething(state, instance) {
    const container = document.createElement('div')
    container.lang = "en-US"
    if (state.user.login) {
      container.innerText = `Hello, ${state.user.login}`
    }
    return container
  }
}

const gitment = new Gitment({
  // ...
  theme: myTheme,
})

gitment.render(document.body)
// or
// gitment.renderSomthing(document.body)

Each render function should receive a state object and a gitment instance, and return an HTML element. It will be wrapped attached to the Gitment instance with the same name.

Gitment uses MobX to detect states used in render functions. Once used states change, Gitment will call the render function to get a new element and render it. Unused states' changing won't affect rendered elements.

Available states:

  • user: object. User info returned from GitHub Users API with two more keys.
    • isLoggingIn: bool. Indicates if user is logging in.
    • fromCache: bool. Gitment will cache user's information. Its value indicates if current user info is from cache.
  • error: Error Object. Will be null if no error occurs.
  • meta: object. Issue's info returned from GitHub Issues API.
  • comments: array. Array of comment returned from GitHub Issue Comments API. Will be undefined when comments not loaded.
  • reactions: array. Array of reactions added to current page, returned from GitHub Issues' Reactions API.
  • commentReactions: object. Object of reactions added to comments, with comment ID as key, returned from GitHub Issue Comments' Reactions API.
  • currentPage: number. Which page of comments is user on. Starts from 1.

About Security

Is it safe to make my client secret public?

Client secret is necessary for OAuth, without which users can't login or comment with their GitHub accounts. Although GitHub does't recommend to hard code client secret in the frontend, you can still do that because GitHub will verify your callback URL. In theory, no one else can use your secret except your site.

If you find a way to hack it, please open an issue.

Why does Gitment send a request to gh-oauth.imsun.net?

https://gh-oauth.imsun.net is an simple open-source service to proxy one request during users logging in. Because GitHub doesn't attach a CORS header to it.

This service won't record or store anything. It only attaches a CORS header to that request and provides proxy. So that users can login in the frontend without any server-side implementation.

For more details, checkout this project.