UI Configuration
UI configuration also known as Client (Frontend) configuration, is the configuration of the Artalk interface.
You can modify the UI configuration in the "Dashboard" without changing the frontend code. Additionally, Configuration files and Environment variables are also supported.
The priority of UI configuration is as follows:
Frontend Code > Environment Variables > Dashboard = Configuration File
If you have modified the UI configuration through environment variables, configuration files, or the Dashboard, but the changes are not taking effect, please consider the issue of UI configuration priority.
Configuring the Interface via Artalk.init
When initializing with Artalk.init
on the frontend page, pass parameters to configure the interface. Below are all the available configuration options.
const artalk = Artalk.init({
el: '#Comments',
pageKey: '/post/1',
pageTitle: 'Page Title',
server: 'http://your_domain:8080',
site: 'Artalk Blog',
})
// Update configuration
artalk.update({ ... })
- Default Configuration: defaults.ts
- Declaration File: config.ts
Basic Configuration (Required)
el
Mount Element (Specify the element selector to bind)
- Type:
String|HTMLElement
- Default:
undefined
Example:
#Comments
corresponds to the element<div id="Comments"></div>
pageKey
Page Address (Relative path / full URL)
- Type:
String
- Default:
location.pathname
Leave empty to automatically get the relative path of the page.
You can fill in the permalink
generated by the blog system, but it is recommended to use the relative path for easier domain switching in the future.
Reference: Using Relative / Absolute Paths
pageTitle
Page Title (Used for management list display, email notifications, etc.)
- Type:
String
- Default:
document.title
Leave empty to automatically get the value of the <title>
tag of the page.
server
Backend Program API Address
- Type:
String
- Default:
undefined
Deploy the backend and ensure that the backend address is accessible from the front end.
Example: http://yourdomain.xxx
site
Site Name
- Type:
String
- Default:
undefined
Artalk supports unified management of multiple sites, this item is used for site isolation.
preferRemoteConf
Prefer Remote Configuration
- Type:
Boolean
- Default:
false
(disabled by default)
This config option is disabled by default, meaning Artalk will prioritize using local config. Local config refers to the settings passed through Artalk.init
in the frontend code.
When enabled, Artalk will prioritize using remote config. If the remote config does not exist, it will resort to using the local config. Remote config refers to the settings returned by the backend server program, allowing for dynamic config of the Artalk client. You can modify the user interface config in the "Dashboard".
Update Notice
As of version v2.10.0, the useBackendConf
configuration option has been deprecated and is always true
. Please use preferRemoteConf
instead.
Internationalization (i18n)
locale
Language
- Type:
String|Object|"auto"
- Default:
"zh-CN"
Following the Unicode BCP 47 standard, the default is "zh-CN" (Simplified Chinese).
Feel free to submit a PR to help translate Artalk into multiple languages and contribute to the community!
For details, see: Localization
dateFormatter
Date Formatting Function
- Type:
(date: Date) => string
- Default:
undefined
By default, it shows a few seconds ago, a few minutes ago, a few hours ago, a few days ago, and if it exceeds 7 days, it shows the specific date in the format YYYY-MM-DD
.
You can also customize the date formatting function. Below is an example using toLocaleString and dayjs to format dates.
import dayjs from 'dayjs'
Artalk.init({
dateFormatter: (date) => {
// return date.toLocaleString() // '2024/8/28 17:51:31'
return dayjs(date).fromNow("MMMM D, YYYY h:mm A") // 'August 28, 2024 5:51 PM'
},
})
Requests
reqTimeout
Request Timeout
- Type:
Number
- Default:
15000
Automatically disconnects the request and reports an error if the request time exceeds this value (unit: milliseconds).
Emoticons
emoticons
Emoticons
- Type:
Object|Array|String|Boolean
- Default: "https://cdn.jsdelivr.net/gh/ArtalkJS/Emoticons/grps/default.json"
For details: Frontend · Emoticons
Now compatible with OwO format, supports dynamic loading by URL.
Set to false
to disable the emoticon feature.
Interface
placeholder
Comment Box Placeholder Text
- Type:
String
- Default:
"Type something..."
noComment
Text Displayed When There Are No Comments
- Type:
String
- Default:
"「Silence is golden」"
sendBtn
Send Button Text
- Type:
String
- Default:
"Post Comment"
editorTravel
Comment Box Travel
- Type:
Boolean
- Default:
true
Set to true
to move the comment box to the position of the comment being replied to, instead of keeping it fixed.
darkMode
Dark Mode
- Type:
Boolean|"auto"
- Default:
false
When Artalk is instantiated, it reads this value and chooses whether to enable dark mode (can be used with the blog theme).
To dynamically modify darkMode:
artalk.setDarkMode(true)
Reference code: “index.html”
Set to "auto"
, Artalk will listen to (prefers-color-scheme: dark)
and automatically switch to dark mode based on the user's operating system settings.
flatMode
Flat Mode
- Type:
Boolean|"auto"
- Default:
"auto"
By default, "auto"
automatically enables "flat mode" on small screen devices (screen width < 768px).
Set to true
to display comments in "flat mode".
Set to false
to display comments in "nested mode".
nestMax
Maximum Nested Levels
- Type:
Number
- Default:
2
Maximum nested levels for comments in "nested mode".
nestSort
Sorting Rules for Nested Comments
- Type:
"DATE_ASC"|"DATE_DESC"|"VOTE_UP_DESC"
- Default:
"DATE_ASC"
By default, nested comments are sorted in ascending order by date (new comments at the end).
Features
pvEl
Page Views (PV) Binding Element
- Type:
String
- Default:
".artalk-pv-count"
You can place an HTML tag anywhere on the page: <span class="artalk-pv-count"></span>
When Artalk finishes loading, it displays the page views.
This item specifies the selector of the binding element, defaulting to .artalk-pv-count
.
countEl
Comment Count Binding Element
- Type:
String
- Default:
".artalk-comment-count"
You can place an HTML tag anywhere on the page: <span class="artalk-comment-count"></span>
to display the current page's comment count.
TIP
Both pvEl and countEl element tags can set the data-page-key
attribute to specify the statistics of a particular page, for example: <span class="artalk-comment-count" data-page-key="/t/1.html"></span>
For details, see: [PV Statistics](./pv.md#Loading statistics for multiple pages simultaneously)
statPageKeyAttr
Statistical Component PageKey Attribute Name
- Type:
String
- Default:
"data-page-key"
When querying comment counts and page views, Artalk's statistical component uses this attribute name to query the specified page, for example: <span data-page-key="/t/1.html"></span>
.
To facilitate theme adaptation, you can customize the attribute name as needed, for example, replacing it with data-path
, the HTML tag would be <span data-path="/t/1.html"></span>
.
pageVote
Page Voting Buttons
- Type:
Boolean | { upBtnEl: string; downBtnEl: string; upCountEl: string; downCountEl: string; activeClass: string }
- Default:
true
Enable the page voting feature (upvote / downvote).
For details, see: Page Voting
vote
Voting Buttons
- Type:
Boolean
- Default:
true
Enable the comment voting feature (upvote / downvote).
voteDown
Downvote Button
- Type:
Boolean
- Default:
false
Downvote button (hidden by default).
uaBadge
Display User's UserAgent Information Badge
- Type:
Boolean
- Default:
false
listSort
Comment Sorting Feature
- Type:
Boolean
- Default:
true
Hover over the "n comments" in the top left of the comment list to display a floating dropdown, allowing the comment list to be sorted and filtered according to "latest / hottest / earliest / author".
imgUpload
Image Upload Feature
- Type:
Boolean
- Default:
true
This configuration item automatically follows the backend. When the backend image upload feature is disabled, only administrators will see the image upload button.
imgUploader
Image Uploader
- Type:
(file: File) => Promise<string>
- Default:
undefined
Custom image uploader, for example:
Artalk.init({
imgUploader: async (file) => {
const form = new FormData()
form.set('file', file)
const imgUrl = await fetch('https://api.example.org/upload', {
method: 'POST',
body: form,
})
return imgUrl
},
})
imgLazyLoad
Lazy Load Images
- Type:
"native"|"data-src"|Boolean
- Default:
false
Enable lazy loading of images in comments.
For details, see: Lazy Load Images
preview
Editor Real-Time Preview Feature
- Type:
Boolean
- Default:
true
Display the "Preview" button in the editor.
Avatars
gravatar: {
mirror: '<Gravatar Mirror URL>',
default: 'mp',
}
gravatar.mirror
Gravatar Mirror URL
- Type:
String
- Default:
"https://www.gravatar.com/avatar/"
If you find Gravatar avatar loading speed unsatisfactory, you can try replacing it.
For example:
WeAvatar: https://weavatar.com/avatar/
Cravatar: https://cravatar.cn/avatar/
V2EX: https://cdn.v2ex.com/gravatar/
Geekzu: https://sdn.geekzu.org/avatar/
gravatar.params
Gravatar API Parameters
- Type:
String
- Default:
"sha256=1&d=mp&s=240"
For example, you can set the default avatar (d=mp
) and avatar size (s=240
) through this configuration item.
Reference: Gravatar API Documentation
This configuration item is in HTTP Query format.
Update Notice
v2.8.7 supports generating Gravatar avatar links using the SHA256 encryption algorithm to enhance user privacy protection. Please include sha256=1
in params
to enable this encryption (#874).
v2.5.5 deprecated the gravatar.default
configuration item; please use gravatar.params
instead.
avatarURLBuilder
Avatar URL Builder
- Type:
(comment: CommentData) => string
- Default:
undefined
Custom user avatar image URL generator, for example:
Artalk.init({
avatarURLBuilder: (comment) => {
return `/api/avatar?email=${comment.email_encrypted}`
},
})
Comment Pagination
pagination: {
pageSize: 20, // Number of comments per page
readMore: true, // Load more or pagination
autoLoad: true, // Auto-load (load more)
}
pagination.readMore
Load More Mode
- Type:
Boolean
- Default:
true
Set to true
for "Load More" mode.
Set to false
for "Pagination" mode.
pagination.autoLoad
Auto-Load on Scroll
- Type:
Boolean
- Default:
true
(Must enable "Load More" mode by setting readMore
to true
)
pagination.pageSize
Number of Comments Per Request
- Type:
Number
- Default:
20
Content Height Limit
Content exceeding the set height will be hidden, and a "Read More" button will be displayed.
heightLimit: {
content: 300, // Comment content height limit
children: 400, // Child comment area height limit
scrollable: false, // Height limit scrolling
}
heightLimit.content
Comment Content Height Limit
- Type:
Number
- Default:
300
Set to 0 to disable height limit.
heightLimit.children
Child Comment Area Height Limit
- Type:
Number
- Default:
400
heightLimit.scrollable
Scrollable Height Limit Area
- Type:
Boolean
- Default:
false
Allow height limit area to scroll.
Version Check
versionCheck
Version Check
- Type:
Boolean
- Default:
true
Display a warning prompt when the frontend and backend versions are incompatible.