Gitment-基于GitHub Issues的评论系统

A comment system based on GitHub Issues. https://imsun.github.io/gitment/


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

• Features
• Get Started
• Methods
• Customize
• About Security

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 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 function renders 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 editor before comments 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 does't attach a CORS header to it.
This service won't record or store anything, only proxy and attach a CORS header to that request. So that users can login in the frontend without any server-side implementation.
For more details, checkout this project.

from https://github.com/imsun/gitment 

---------

Gitment：使用GitHub Issues搭建评论系统 

 

Gitment 是作者实现的一款基于 GitHub Issues 的评论系统。支持在前端直接引入，不需要任何后端代码。可以在页面进行登录、查看、评论、点赞等操作，同时有完整的 Markdown / GFM 和代码高亮支持。尤为适合各种基于 GitHub Pages 的静态博客或项目页面。

本博客评论系统已迁移至 Gitment。虽然 Gitment 只能使用 GitHub 账号进行评论，但考虑到博客受众，这是可以接受的。

• 项目地址
• 示例页面

基础使用

1. 注册 OAuth Application

点击此处 来注册一个新的 OAuth Application。其他内容可以随意填写，但要确保填入正确的 callback URL（一般是评论页面对应的域名，如 https://imsun.net）。

你会得到一个 client ID 和一个 client secret，这个将被用于之后的用户登录。

2. 引入 Gitment

将下面的代码添加到你的页面：

<div id="container"></div> <link rel="stylesheet" href="https://imsun.github.io/gitment/style/default.css"> <script src="https://imsun.github.io/gitment/dist/gitment.browser.js"></script> <script> var gitment = new Gitment({ id: '页面 ID', // 可选。默认为 location.href owner: '你的 GitHub ID', repo: '存储评论的 repo', oauth: { client_id: '你的 client ID', client_secret: '你的 client secret', }, }) gitment.render('container') </script>

注意，上述代码引用的 Gitment 将会随着开发变动。如果你希望始终使用最新的界面与特性即可引入上述代码。

如果你希望引用确定版本的 Gitment，则应该使用 npm 进行安装。

$ npm install --save gitment

关于构造函数中的更多可用参数请查看 Gitment Options

3. 初始化评论

页面发布后，你需要访问页面并使用你的 GitHub 账号登录（请确保你的账号是第二步所填 repo 的 owner），点击初始化按钮。

之后其他用户即可在该页面发表评论。

自定义

Gitment 很容易进行自定义，你可以写一份自定义的 CSS 或者使用一个新的主题。（主题可以改变 DOM 结构而自定义 CSS 不能）

比如你可以通过自定义主题将评论框放在评论列表前面：

const myTheme = { render(state, instance) { const container = document.createElement('div') container.lang = "en-US" container.className = 'gitment-container gitment-root-container' 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 }, } const gitment = new Gitment({ // ... theme: myTheme, }) gitment.render('container')

更多自定义内容请查看文档。

其他问题

语言问题

考虑到 GitHub 本身使用英文，而本项目面向用户均为 GitHub 用户，所以作者没有提供中文支持的打算。实在有需求的可以通过自定义主题支持中文。

请勿滥用

在开发这个项目时我就一直有一个疑虑：我这样做有没有滥用 GitHub？为此我仔细读了 GitHub Terms of Service 中 API Terms 的部分，认为自己并没有违反协议。之后我向 GitHub 发邮件询问了这一问题。GitHub 给出的回复是：

We’re pleased to see you making use of the tools and resources available on GitHub.

因此本项目的确没有违反 GitHub 使用协议。但我还是想提醒使用本项目的用户，请保持克制，切勿滥用。