{"id":20074029,"url":"https://github.com/ezforever/gitment-mod","last_synced_at":"2025-03-02T12:22:45.118Z","repository":{"id":114511213,"uuid":"175636683","full_name":"EZForever/gitment-mod","owner":"EZForever","description":"A comment system based on GitHub Issues. (Fork of https://github.com/imsun/Gitment)","archived":false,"fork":false,"pushed_at":"2019-03-19T04:15:17.000Z","size":24,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-13T00:33:24.828Z","etag":null,"topics":["comments","github-blog","github-issues","github-pages"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EZForever.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-14T14:19:36.000Z","updated_at":"2019-04-20T13:42:28.000Z","dependencies_parsed_at":"2023-05-17T14:15:11.651Z","dependency_job_id":null,"html_url":"https://github.com/EZForever/gitment-mod","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EZForever%2Fgitment-mod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EZForever%2Fgitment-mod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EZForever%2Fgitment-mod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EZForever%2Fgitment-mod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EZForever","download_url":"https://codeload.github.com/EZForever/gitment-mod/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241504321,"owners_count":19973219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comments","github-blog","github-issues","github-pages"],"created_at":"2024-11-13T14:49:07.409Z","updated_at":"2025-03-02T12:22:45.091Z","avatar_url":"https://github.com/EZForever.png","language":"JavaScript","readme":"# Gitment-mod\n\n[Gitment](https://github.com/imsun/Gitment) is a comment system based on GitHub Issues,\nwhich can be used in the frontend without any server-side implementation.\n\nGitment-mod is a third-party fork of Gitment v0.0.3 (latest official version), which shrinks code size and fixes serveral issues.\n\n[Demo Page](https://imsun.github.io/gitment/)\n\n[中文简介](https://imsun.net/posts/gitment-introduction/)\n\n- [Features](#features)\n- [Get Started](#get-started)\n- [Methods](#methods)\n- [Customize](#customize)\n- [About Security](#about-security)\n\n## Features\n\n- GitHub Login\n- Markdown / GFM support\n- Syntax highlighting\n- Notifications from GitHub\n- Easy to customize\n- No server-side implementation\n\n## Get Started\n\n### 1. Install\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://ezforever.github.io/gitment-mod/theme/default.css\"\u003e\n\u003cscript src=\"https://ezforever.github.io/gitment-mod/gitment.browser.js\" type=\"module\"\u003e\u003c/script\u003e\n```\n\n\u003cdel\u003e\nor via npm:\n\n```sh\n$ npm i --save gitment\n```\n\n```javascript\nimport 'gitment/style/default.css'\nimport Gitment from 'gitment'\n```\n\u003c/del\u003e\n\n### 2. Register An OAuth Application\n\n[Click here](https://github.com/settings/applications/new) to register an OAuth application, and you will get a client ID and a client secret.\n\nMake sure the callback URL is right. Generally it's the origin of your site, like [https://imsun.net](https://imsun.net).\n\n### 3. Render Gitment\n\n```javascript\nconst gitment = new Gitment({\n  id: 'Your page ID', // optional\n  owner: 'Your GitHub ID',\n  repo: 'The repo to store comments',\n  oauth: {\n    client_id: 'Your client ID',\n    client_secret: 'Your client secret',\n  },\n  // ...\n  // For more available options, check out the documentation below\n})\n\ngitment.render('comments')\n// or\n// gitment.render(document.getElementById('comments'))\n// or\n// document.body.appendChild(gitment.render())\n```\n\n### 4. Initialize Your Comments\n\nAfter 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.\nAfter that, others can leave their comments.\n   \n## Methods\n\n### constructor(options)\n\n#### options:\n\nType: `object` \n\n- owner: Your GitHub ID. Required.\n- repo: The repository to store your comments. Make sure you're repo's owner. Required.\n- oauth: An object contains your client ID and client secret. Required.\n    - client_id: GitHub client ID. Required.\n    - client_secret: GitHub client secret. Required.\n- id: An optional string to identify your page. Default `location.href`.\n- title: An optional title for your page, used as issue's title. Default `document.title`.\n- link: An optional link for your page, used in issue's body. Default `location.href`.\n- desc: An optional description for your page, used in issue's body. Default `''`.\n- labels: An optional array of labels your want to add when creating the issue. Default `[]`.\n- theme: An optional Gitment theme object. Default `gitment.defaultTheme`.\n- perPage: An optional number to which comments will be paginated. Default `20`.\n- maxCommentHeight: An optional number to limit comments' max height, over which comments will be folded. Default `250`.\n\n### gitment.render([element])\n\n#### element\n\nType: `HTMLElement` or `string`\n\nThe 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.\n\nThis function returns the element to which comments be rendered.\n\n### gitment.renderHeader([element])\n\nSame like `gitment.render([element])`. But only renders the header.\n\n### gitment.renderComments([element])\n\nSame like `gitment.render([element])`. But only renders comments list.\n\n\n### gitment.renderEditor([element])\n\nSame like `gitment.render([element])`. But only renders the editor.\n\n\n### gitment.renderFooter([element])\n\nSame like `gitment.render([element])`. But only renders the footer.\n\n### gitment.init()\n\nInitialize a new page. Returns a `Promise` and resolves when initialized.\n\n### gitment.update()\n\nUpdate data and views. Returns a `Promise` and resolves when data updated. \n\n### gitment.post()\n\nPost comment in the editor. Returns a `Promise` and resolves when posted.\n\n### gitment.markdown(text)\n\n#### text\n\nType: `string`\n\nReturns a `Promise` and resolves rendered text.\n\n### gitment.login()\n\nJump to GitHub OAuth page to login.\n\n### gitment.logout()\n\nLog out current user.\n\n### goto(page)\n\n#### page\n\nType: `number`\n\nJump to the target page of comments. Notice that `page` starts from `1`. Returns a `Promise` and resolves when comments loaded.\n\n### gitment.like()\n\nLike current page. Returns a `Promise` and resolves when liked.\n\n### gitment.unlike()\n\nUnlike current page. Returns a `Promise` and resolves when unliked.\n\n### gitment.likeAComment(commentId)\n\n#### commentId\n\nType: `string`\n\nLike a comment. Returns a `Promise` and resolves when liked.\n\n### gitment.unlikeAComment(commentId)\n\n#### commentId\n\nType: `string`\n\nUnlike a comment. Returns a `Promise` and resolves when unliked.\n\n## Customize\n\nGitment is easy to customize. You can use your own CSS or write a theme.\n(The difference is that customized CSS can't modify DOM structure)\n\n### Use Customized CSS\n\nGitment does't use any atomic CSS, making it easier and more flexible to customize.\nYou can inspect the DOM structure in the browser and write your own styles.\n\n### Write A Theme\n\nA Gitment theme is an object contains several render functions.\n \nBy default Gitment has five render functions: `render`, `renderHeader`, `renderComments`, `renderEditor`, `renderFooter`.\nThe last four render independent components and `render` functions render them together.\nAll of them can be used independently.\n\nYou can override any render function above or write your own render function.\n\nFor example, you can override the `render` function to put an editor before the comment list, and render a new component.\n\n```javascript\nconst myTheme = {\n  render(state, instance) {\n    const container = document.createElement('div')\n    container.lang = \"en-US\"\n    container.className = 'gitment-container gitment-root-container'\n    \n     // your custom component\n    container.appendChild(instance.renderSomething(state, instance))\n    \n    container.appendChild(instance.renderHeader(state, instance))\n    container.appendChild(instance.renderEditor(state, instance))\n    container.appendChild(instance.renderComments(state, instance))\n    container.appendChild(instance.renderFooter(state, instance))\n    return container\n  },\n  renderSomething(state, instance) {\n    const container = document.createElement('div')\n    container.lang = \"en-US\"\n    if (state.user.login) {\n      container.innerText = `Hello, ${state.user.login}`\n    }\n    return container\n  }\n}\n\nconst gitment = new Gitment({\n  // ...\n  theme: myTheme,\n})\n\ngitment.render(document.body)\n// or\n// gitment.renderSomthing(document.body)\n```\n\nEach render function should receive a state object and a gitment instance, and return an HTML element.\nIt will be wrapped attached to the Gitment instance with the same name.\n\n~~Gitment uses [MobX](https://github.com/mobxjs/mobx) to detect states used in render functions.\nOnce used states change, Gitment will call the render function to get a new element and render it.\nUnused states' changing won't affect rendered elements.~~\n\nGitment-mod no longer uses MobX, but [a much smaller alternative](https://davidwalsh.name/watch-object-changes).\nIt should work just as fine as before, but further testings are needed.\n\nAvailable states:\n\n- user: `object`. User info returned from [GitHub Users API](https://developer.github.com/v3/users/#get-the-authenticated-user) with two more keys.\n    - isLoggingIn: `bool`. Indicates if user is logging in.\n    - fromCache: `bool`. Gitment will cache user's information. Its value indicates if current user info is from cache.\n- error: `Error Object`. Will be null if no error occurs.\n- meta: `object`. Issue's info returned from [GitHub Issues API](https://developer.github.com/v3/issues/#list-issues).\n- comments: `array`. Array of comment returned from [GitHub Issue Comments API](/repos/:owner/:repo/issues/:number/comments). Will be `undefined` when comments not loaded.\n- reactions: `array`. Array of reactions added to current page, returned from [GitHub Issues' Reactions API](https://developer.github.com/v3/reactions/#list-reactions-for-an-issue).\n- commentReactions: `object`. Object of reactions added to comments, with comment ID as key, returned from [GitHub Issue Comments' Reactions API](/repos/:owner/:repo/issues/comments/:id/reactions).\n- currentPage: `number`. Which page of comments is user on. Starts from `1`.\n\n## About Security\n\n### Is it safe to make my client secret public?\n\nClient secret is necessary for OAuth, without which users can't login or comment with their GitHub accounts.\nAlthough GitHub does't recommend to hard code client secret in the frontend, you can still do that because GitHub will verify your callback URL. \nIn theory, no one else can use your secret except your site.\n\nIf you find a way to hack it, please [open an issue](https://github.com/imsun/gitment/issues/new).\n\n### Why does Gitment send a request to ~~gh-oauth.imsun.net~~ wherever other than GitHub?\n\n[https://gh-oauth.imsun.net](https://gh-oauth.imsun.net) (or any other URL Gitment is requesting) is an simple open-source service to proxy [one request](https://developer.github.com/v3/oauth/#2-github-redirects-back-to-your-site) during users logging in.\nBecause GitHub doesn't attach a CORS header to it.\n\nThis service won't record or store anything. It only attaches a CORS header to that request and provides proxy.\nSo that users can login in the frontend without any server-side implementation.\n\nFor more details, checkout [this project](https://github.com/imsun/gh-oauth-server).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezforever%2Fgitment-mod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fezforever%2Fgitment-mod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fezforever%2Fgitment-mod/lists"}