Icarus User Guide - Comment Plugins
This article covers comment plugins supported by Icarus.
Artalk
Artalk is a self-hosted comment system. Like Isso and Twikoo, it requires you to run the Artalk server yourself before Icarus can use it.
Installation Guide
Follow the Artalk documentation to deploy the Artalk server, and add your site to it.
Fill in the URL of your Artalk server and the name of your site on the server in the theme configurations:
_config.icarus.yml 1
2
3
4
5
6
7comment:
type: artalk
server: https://artalk.example.com # Required. URL of your Artalk server
site: My Blog # Optional. Name of the site on the Artalk server
locale: en # Optional. Language of Artalk, e.g., en, zh-CN, or auto
prefer_remote_conf: false # Optional. Prefer the settings on the Artalk server when true
# dark_mode: auto # Optional. true, false, or auto. Follows the appearance of the page if not setNotes:
- Without
dark_mode, Artalk follows the appearance of the page: it looks dark withappearance: dark, and follows the color scheme of the visitor’s system withappearance: auto. Setdark_modetotrue,false, orauto(follow the color scheme of the system) to override it. - Artalk identifies the comments of a page by its path.
You can set
page_keyto another unique identifier of a page in its front-matter, for example to keep the comments when you move the page. Since the front-matter replaces the wholecommentsetting, copy the other comment settings there as well. - Use an Artalk server compatible with client 2.10.0.
- See the Artalk client configuration for more details on these settings.
- Without
Beaudar
Beaudar is a Chinese fork of utterances that keeps the comments in GitHub issues. Its setup is similar to that of utterances.
Installation Guide
Prepare a public GitHub repository, and install the Beaudar GitHub App on it by following the Beaudar documentation.
Fill in the repository and other settings in the theme configurations:
_config.icarus.yml 1
2
3
4
5
6
7
8
9comment:
type: beaudar
repo: Your-GitHub-Username/Your-Public-Repo-Name
issue_term: pathname # Required if issue_number is not set
# issue_number: 100 # Required if issue_term is not set
branch: main # Optional. Branch of the repository that has beaudar.json
label: some-issue-label # Optional
theme: github-light # Optional, default: github-light. Used when the page looks light
dark_theme: github-dark # Optional, default: github-dark. Used when the page looks darkNotes:
- Set exactly one of
issue_term(e.g.,pathname,url, ortitle) andissue_number. Setting both fails the configuration check. themeis used when the page looks light, e.g.,github-light,github-dark, orpreferred-color-scheme.dark_themeis used when the page looks dark, i.e., withappearance: dark, or withappearance: autowhile the visitor’s system uses a dark color scheme. Its values includegithub-dark,github-dark-orange,classic-dark,dark-blue,icy-dark, andphoton-dark.
- Set exactly one of
Changyan
Installation Guide
First, log into Changyan. Get the comment HTML code by following this article.
Copy the value of
appidandconfto the corresponding settings in the theme configurations. For example, the following HTML codeChangyan Installation Code >folded 1
2
3
4
5
6
7
8
9<!--PC版-->
<div id="SOHUCS" sid="..."></div>
<script charset="utf-8" type="text/javascript" src="https://cy-cdn.kuaizhan.com/upload/changyan.js" ></script>
<script type="text/javascript">
window.changyan.api.config({
appid: '????appid????',
conf: 'prod_xxxxxxxxxxxxxxxxxxxxxxx'
});
</script>maps to the following theme configuration:
_config.icarus.yml 1
2
3
4comment:
type: changyan
app_id: ????appid????
conf: prod_xxxxxxxxxxxxxxxxxxxxxxx
Disqus
First, log into Disqus. Click the “GET STARTED” button on the front page or visit here and click “I want to install Disqus on my site” to create a new Disqus comment service.
On the create new site page, fill in the “Website Name” and “Category”, then click the “Create Site” button.
Select a subscription plan if you want to. You can also skip this by clicking “Install Disqus” on the left.
Next, choose the platform where Disqus is to be installed. Select the “I don’t see my platform listed, install manually with Universal Code” on the bottom of the page.
Click the “Configuration” button on the bottom of the page to skip the “Universal Code install instructions”.
Make customizations to your Disqus service on the “Configure Disqus” page. Then, click the “Complete Setup” and “Dismiss Setup” buttons to finish the setup.
Next, click the “Edit Settings” button on the top right corner of the comment service home page.
Find the value of “Shortname” on the “Configure Disqus for Your Site” page, and copy it to the comment settings in the theme configurations. For example, the “Shortname” in the following screenshot is
my-hexo-blog-1:
which maps to the following theme configuration:
_config.icarus.yml 1
2
3comment:
type: disqus
shortname: my-hexo-blog-1(Optional) You can add
disqusIdin the front-matter of the post as the unique Disqus ID. Thereby, you can change the location of the post in the future without losing all your comments:source/_posts/some-post.md 1
2
3
4
5title: My first post
date: 2015-01-01 00:00:01
disqusId: some-disqus-id
---
# Hello world
DisqusJS
DisqusJS is an alternative for Disqus in areas where Disqus is restricted. You can refer to https://github.com/SukkaW/DisqusJS for the detailed configuration process of DisqusJS.
Log into Disqus and visit here. Click the “Register new application” button or “registering an application” to create a new Disqus application.
Fill in the “Label”, “Description”, and “Website” on the next page. Then, click “Register my application”.
After creating the application, go to the “Settings” tab of the application, fill in the domain name of your Hexo site, e.g., ppoffice.github.io, in the “Domains” field. Then, click the “Save Changes” button on the bottom of the page.
Click the “Details” link on the current page to go to the home page of the current application. Copy the “API Key” in the “OAuth Settings” section to the corresponding setting in the theme configurations.
For example, the “API Key” in the following screenshot:
maps to the following theme configuration:
_config.icarus.yml 1
2
3
4
5
6
7
8comment:
type: disqusjs
shortname: my-hexo-blog-1
api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
api: https://disqus.skk.moe/disqus/ # Optional
admin: ppoffice # Optional
admin_label: Admin # Optional
nesting: 4 # OptionalTo learn more about DisqusJS and its configuration, visit SukkaW/DisqusJS documentation or hexo-component-inferno.
Giscus
A comments system powered by GitHub Discussions.
Prepare a public GitHub repository.
Go to GitHub Apps - giscus and click “Install”.
(Optional) Select the user to install giscus to on the next page if you also have organizations under your account.
On the next page, you can choose to install giscus to “All repositories” or “Only select repositories”. Then, click the “Install” button.
You will be redirected to the giscus official site if the installation completes. You can review each configuration option and customize your giscus setup.
When finished, move to the “Enable giscus” and copy the attribute values from the giscus HTML code to the corresponding settings in your theme configurations.
For example, the giscus code below:
giscus Installation Code >folded 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16<script src="https://giscus.app/client.js"
data-repo="usr/repo"
data-repo-id="X_xxxxxxxxxx"
data-category="Announcements"
data-category-id="XXX_xxxxxxxxxxxxxxxx"
data-mapping="pathname"
data-strict="0"
data-reactions-enabled="0"
data-emit-metadata="0"
data-input-position="top"
data-theme="noborder_light"
data-lang="en"
data-loading="lazy"
crossorigin="anonymous"
async>
</script>maps to the following theme configuration:
_config.icarus.yml 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15comment:
type: giscus
repo: usr/repo # Required
repoId: X_xxxxxxxxxx # Required
category: Announcements # Optional, default: Announcements
categoryId: XXX_xxxxxxxxxxxxxxxx # Required
mapping: pathname # Optional, default: pathname
strict: false # Optional
reactionsEnabled: false # Optional
emitMetadata: false # Optional
inputPosition: top # Optional, default: top
theme: noborder_light # Optional, default: noborder_light. Used when the page looks light
darkTheme: noborder_dark # Optional, default: noborder_dark. Used when the page looks dark
lang: en # Optional, default: en
lazy: true # Optional, default: falseNotes:
themeis used when the page looks light, anddarkThemeis used when the page looks dark, i.e., withappearance: dark, or withappearance: autowhile the visitor’s system uses a dark color scheme. If you copydata-themefrom the giscus code, put a light theme inthemeand a dark one indarkTheme.- To use your own giscus theme, set
themetocustomandcustomThemeCssto the URL of the theme’s CSS file. The custom theme is used whether the page looks light or dark, anddarkThemeis ignored. - If
mappingisspecificornumber, also settermto the search term or the number of the discussion, e.g.,mapping: numberwithterm: 1. Otherwise, a notice asking you to settermis shown in place of the comments.
Gitalk
Gitalk keeps the comments in the issues or discussions of a GitHub repository. Visitors sign in through a GitHub App and a Gitalk proxy that you deploy yourself.
Log into GitHub and click here to create a new GitHub App. To create the App under an organization, go to “Developer settings” in the settings of the organization instead. Fill in the “GitHub App name” and “Homepage URL”. Leave the “Callback URL” empty for now, and uncheck “Active” under “Webhook”. Under “Repository permissions”, set “Issues” to “Read and write” if you keep the comments in issues, or “Discussions” to “Read and write” if you keep them in discussions. Then, click the “Create GitHub App” button.
On the App settings page, write down the “App ID” and “Client ID”. Click “Generate a new client secret” and “Generate a private key” to get the client secret and the private key.
Deploy the Gitalk proxy to Cloudflare Workers or Tencent CloudBase by following the Gitalk proxy guide. Fill in the App ID, Client ID, client secret, and private key from the last step in its
.envfile. SetGITALK_ALLOWED_ORIGINSto the origin of your Hexo site, e.g.,https://ppoffice.github.io. Write down the proxy URL printed after the deployment, e.g.,https://my-gitalk.octocat.workers.dev.Go back to the App settings page. Set the “Callback URL” to the proxy URL followed by
/oauth/callback, e.g.,https://my-gitalk.octocat.workers.dev/oauth/callback, and save the changes.Prepare a public GitHub repository for the comments. If you keep the comments in discussions, turn on “Discussions” in the settings of the repository and make sure it has at least one discussion category.
Open
https://github.com/apps/<app-slug>/installations/new, where<app-slug>is the last part of the public URL of your App. Choose “Only select repositories”, select the repository from the last step, and click the “Install” button.Copy the Client ID and the proxy URL to the corresponding settings in the theme configurations. For example, the following Client ID and proxy URL:
GitHub App and Gitalk Proxy 1
2
3
4Client ID
Iv23lixxxxxxxxxxxxxx
Proxy URL
https://my-gitalk.octocat.workers.devmaps to the following theme configuration:
_config.icarus.yml 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16comment:
type: gitalk
client_id: Iv23lixxxxxxxxxxxxxx
proxy: https://my-gitalk.octocat.workers.dev
repo: Some-of-Your-GitHub-Repo # Name of the repository, without the owner
owner: you_github_name
admin:
- you_github_name
backend: issues # Optional, default: issues. Set to discussions to keep the comments in discussions
category: General # Optional. Name or slug of the discussion category for new discussions
per_page: 10 # Optional, default: 10. At most 100
distraction_free_mode: false # Optional
pager_direction: last # Optional, default: last. last or first
create_issue_manually: true # Optional, default: true
enable_hotkey: true # Optional, default: true. Submit a comment with Cmd or Ctrl + Enter
language: zh-CN # OptionalNotes:
- Gitalk follows the appearance of the page: it looks dark with
appearance: dark, and follows the color scheme of the visitor’s system withappearance: auto. - The client secret and the private key belong to the proxy. Do not put them in the theme configurations.
- With
create_issue_manually: true, an admin creates the issue or discussion of each page by signing in on that page and clicking the button that Gitalk shows. - To use an existing issue or discussion for the comments of a page, set
numberto its number in the front-matter of the page. Since the front-matter replaces the wholecommentsetting, copy the other comment settings there as well. - You can review the description and possible values of the above configuration at Gitalk documentation or hexo-component-inferno.
- Gitalk follows the appearance of the page: it looks dark with
Isso
Isso is a valid choice if you wish to set up a self-hosted social comment system instead of relying on third-party ones. However, unlike the other services, Isso requires a web host for running the Isso server.
Installation Guide
Follow the Isso documentation to install and run the Isso server.
Fill in the HTTP URL of Isso server to the corresponding setting in the theme configurations. For example, if your service URL is
https://posativ.org/isso/api/, you will have the following comment configuration:_config.icarus.yml 1
2
3comment:
type: isso
url: posativ.org/isso/api
LiveRe
Sign in to LiveRe Admin and add your site. Fill in the name and the URL of your site, and verify your email address.
Copy the installation code of your site from LiveRe Admin.
Copy the value of
client-idin the code to the corresponding setting in the theme configurations. For example, the LiveRe code below:LiveRe Installation Code 1
2<livere-comment client-id="AbCdEfGhIjKlMnOpQrSt"></livere-comment>
<script type="module" src="https://www.livere.org/livere-widget.js"></script>maps to the following theme configuration:
_config.icarus.yml 1
2
3comment:
type: livere
client_id: AbCdEfGhIjKlMnOpQrStIf you use the legacy LiveRe City code, set
uidto the value of itsdata-uidattribute instead.
Twikoo
Twikoo is a self-hosted comment system based on cloud functions. Unlike other third-party comment services, the Twikoo backend needs to be deployed to a cloud environment before being configured and used by Icarus.
Follow the Twikoo documentation to deploy the Twikoo cloud function to a cloud service provider of your choice. Icarus loads version 2.0.17 of the Twikoo client, so deploy a Twikoo backend of the same version.
Fill in the
env_idof your deployment to the corresponding setting in the theme configurations. It is the environment ID if you deploy Twikoo to Tencent CloudBase, or the URL of your deployment if you deploy it to Vercel or host it yourself, e.g.,https://your-twikoo.vercel.app._config.icarus.yml 1
2
3
4
5comment:
type: twikoo
env_id: xxxxxxxx # Required. Environment ID, or the URL of your deployment
region: ap-guangzhou # Optional. Region of Tencent CloudBase
lang: zh-CN # Optional. Defaults to the language of the page or the site
utterances
Prepare a public GitHub repository.
Go to GitHub Apps - utterances and click “Install”.
(Optional) Select the user to install utterances to on the next page if you also have organizations under your account.
On the next page, you can choose to install utterances to “All repositories” or “Only select repositories”. Then, click the “Install” button.
You will be redirected to the utterances official site if the installation completes. You can review each configuration option and customize your utterances setup.
When finished, move to the “Enable utterances” and copy the attribute values from the utterances HTML code to the corresponding settings in your theme configurations.
For example, the utterances code below:
utterances Installation Code >folded 1
2
3
4
5
6
7<script src="https://utteranc.es/client.js"
repo="Your-GitHub-Username/Your-Public-Repo-Name"
issue-term="pathname"
theme="github-light"
crossorigin="anonymous"
async>
</script>maps to the following theme configuration:
_config.icarus.yml 1
2
3
4
5
6
7
8comment:
type: utterances
repo: Your-GitHub-Username/Your-Public-Repo-Name
issue_term: pathname # Required if issue_number is not set
# issue_number: 100 # Required if issue_term is not set. Maps the page to a GitHub issue you create yourself
label: some-issue-label # Optional
theme: github-light # Optional, default: github-light. Used when the page looks light
dark_theme: github-dark # Optional, default: github-dark. Used when the page looks darkNotes:
- Set exactly one of
issue_termandissue_number. Setting both fails the configuration check. To map each post to its own issue by number, setissue_numberin the front-matter of the post, together with the other comment settings, since the front-matter replaces the wholecommentsetting. themeis used when the page looks light, anddark_themeis used when the page looks dark, i.e., withappearance: dark, or withappearance: autowhile the visitor’s system uses a dark color scheme. Both can begithub-light,github-dark,github-dark-orange,icy-dark,dark-blue, orphoton-dark.
- Set exactly one of
Valine
record_ip: true
(ppoffice/hexo-theme-icarus#788).
Please use Waline, Twikoo, or another comment system instead.
Create a LeanCloud application following the Quickstart guide.
Copy the “App ID” and “App Key” of your LeanCloud application to the corresponding settings in the theme configurations. In addition, you can refer to the Config Reference to find out the details and possible values of the optional settings. Here is an example configuration:
_config.icarus.yml 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18comment:
type: valine
app_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
app_key: xxxxxxxxxxxxxxxxxxxxxx
placeholder: "" # Optional
avatar: mm # Optional
avatar_force: false # Optional
meta: ["nick", "mail", "link"] # Optional
page_size: 10 # Optional
lang: zh-CN # Optional
visitor: false # Optional
highlight: true # Optional
record_ip: false # Optional
server_urls: # Optional
emoji_cdn: # Optional
emoji_maps: # Optional
enable_qq: false # Optional
required_fields: [] # Optional
Waline
Deploy the Waline server to Vercel following the Get Started guide. Note that LeanCloud shuts down on January 12, 2027 (see Valine), so if you set up Waline now, store the comments in another database supported by Waline.
Copy the “Server URL” of your Vercel project to the corresponding setting in the theme configurations. It is usually something like
https://your-domain.vercel.app. In addition, you can refer to the Client Configuration to find out more details and possible values of the optional settings. Here is an example configuration:_config.icarus.yml 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22comment:
type: waline
server_url: https://your-domain.vercel.app
path: window.location.pathname # Optional. A path like /posts/hello/, or a JavaScript expression
lang: en-US # Optional
locale: # Optional
placeholder: 'Comment here...'
emoji: # Optional. Set to false to disable emoji
- '//unpkg.com/@waline/emojis@1.0.1/weibo'
# dark: auto # Optional. Follows the appearance of the page if not set
meta: ["nick", "mail", "link"] # Optional
required_meta: [] # Optional
login: enable # Optional
word_limit: 0 # Optional
page_size: 10 # Optional
image_uploader: false # Optional. Set to true to disable image uploading
highlighter: false # Optional. Set to true to disable code highlighting
tex_renderer: false # Optional. Set to true to disable TeX rendering
search: false # Optional. Set to true to disable image search
pageview: false # Optional. Do not enable it with the waline_pageview plugin
comment: false # Optional
copyright: true # OptionalThe
image_uploader,highlighter,tex_renderer, andsearchsettings turn off Waline features: setting one of them totruedisables the feature (Icarus passesfalsefor it to Waline), while leaving it empty or setting it tofalsekeeps Waline’s default behavior for that feature.pathcan be a fixed path starting with/, such as/posts/hello/. Any other value is used as a JavaScript expression, and it defaults towindow.location.pathname.Without
dark, Waline follows the appearance of the page: it looks dark withappearance: dark, and follows the color scheme of the visitor’s system withappearance: auto. Setdarktotrue,false,auto(follow the color scheme of the system), or a CSS selector that turns on the dark mode when it matches an ancestor of Waline to override it.The
pageviewsetting counts and shows the page views with the Waline comments. Icarus also provides awaline_pageviewplugin, which counts the page views with the Waline server and shows them in the post header (see Web Analytics Plugins). Enable only one of them: with both, each view is counted twice, and a warning is printed when you generate your site.
Icarus User Guide - Comment Plugins
https://ppoffice.github.io/hexo-theme-icarus/Plugins/Comment/icarus-user-guide-comment-plugins/