search

synbe / issue

0 stars 0 forks source link

About Gitment #10

Open synbe opened 6 years ago

synbe commented 6 years ago

https://github.com/imsun/gitment

synbe commented 6 years ago

https://github.com/imsun/gitment

https://imsun.net/posts/gitment-introduction/

synbe commented 6 years ago

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

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

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:

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.

synbe commented 6 years ago

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 使用协议。但我还是想提醒使用本项目的用户，请保持克制，切勿滥用。

样式版权

在项目开源前作者曾实现了一个像素级抄袭 GitHub Issues 样式的界面，但在阅读 ToS 时发现违反了 Section F，并在和 GitHub 邮件沟通的过程中确认了这一行为是侵权的。因此便改成了现在的样式。请其他想要自定义样式的用户也留意版权问题。

synbe commented 6 years ago

Gitment Demo

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Gitment Demo Page</title>
  <meta name="viewport" content="width=640, user-scalable=no">
  <link rel="stylesheet" href="./test/style.css">
  <link rel="stylesheet" href="./style/default.css">
</head>
<body>
  <div>
    <h1>Gitment Demo</h1>
    <p>This is the demo page for <a href="https://github.com/imsun/gitment" target="_blank">Gitment</a>.</p>
    <p>You can login with GitHub and leave your comments below.</p>
  </div>
  <div id="container"></div>

  <script src="./dist/gitment.browser.js"></script>
  <script>
    var clientId = '82c800a8b9db1cb2a145'
    var clientSecret = 'abcb4790d98c686e7656d28c756ebbaac5b89d3a'
    var gitment = new Gitment({
      id: 'demo page',
      owner: 'imsun',
      repo: 'gitment',
      oauth: {
        client_id: clientId,
        client_secret: clientSecret,
      },
    })

    gitment.render('container')
  </script>
</body>
</html>