Open synbe opened 6 years ago
Gitment is a comment system based on GitHub Issues, which can be used in the frontend without any server-side implementation.
<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'
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.
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())
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.
Type: object
location.href
.document.title
.location.href
.''
.[]
.gitment.defaultTheme
.20
.250
.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.
Same like gitment.render([element])
. But only renders the header.
Same like gitment.render([element])
. But only renders comments list.
Same like gitment.render([element])
. But only renders the editor.
Same like gitment.render([element])
. But only renders the footer.
Initialize a new page. Returns a Promise
and resolves when initialized.
Update data and views. Returns a Promise
and resolves when data updated.
Post comment in the editor. Returns a Promise
and resolves when posted.
Type: string
Returns a Promise
and resolves rendered text.
Jump to GitHub OAuth page to login.
Log out current user.
Type: number
Jump to the target page of comments. Notice that page
starts from 1
. Returns a Promise
and resolves when comments loaded.
Like current page. Returns a Promise
and resolves when liked.
Unlike current page. Returns a Promise
and resolves when unliked.
Type: string
Like a comment. Returns a Promise
and resolves when liked.
Type: string
Unlike a comment. Returns a Promise
and resolves when unliked.
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)
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.
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:
object
. User info returned from GitHub Users API with two more keys.
bool
. Indicates if user is logging in.bool
. Gitment will cache user's information. Its value indicates if current user info is from cache.Error Object
. Will be null if no error occurs.object
. Issue's info returned from GitHub Issues API.array
. Array of comment returned from GitHub Issue Comments API. Will be undefined
when comments not loaded.array
. Array of reactions added to current page, returned from GitHub Issues' Reactions API.object
. Object of reactions added to comments, with comment ID as key, returned from GitHub Issue Comments' Reactions API.number
. Which page of comments is user on. Starts from 1
.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.
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.
本以为自己都二十好几了,早就过了折腾博客系统的年龄,然而万万没想到多说倒闭了。 综合考虑了多家评论系统以后,我最终打算自己写一个。
Gitment 是作者实现的一款基于 GitHub Issues 的评论系统。支持在前端直接引入,不需要任何后端代码。可以在页面进行登录、查看、评论、点赞等操作,同时有完整的 Markdown / GFM 和代码高亮支持。尤为适合各种基于 GitHub Pages 的静态博客或项目页面。
本博客评论系统已迁移至 Gitment。虽然 Gitment 只能使用 GitHub 账号进行评论,但考虑到博客受众,这是可以接受的。
点击此处 来注册一个新的 OAuth Application。其他内容可以随意填写,但要确保填入正确的 callback URL(一般是评论页面对应的域名,如 https://imsun.net)。
你会得到一个 client ID 和一个 client secret,这个将被用于之后的用户登录
将下面的代码添加到你的页面:
<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
页面发布后,你需要访问页面并使用你的 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 邮件沟通的过程中确认了这一行为是侵权的。因此便改成了现在的样式。请其他想要自定义样式的用户也留意版权问题。
<!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>
https://github.com/imsun/gitment