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: 

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:  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: 

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: .

To facilitate theme adaptation, you can customize the attribute name as needed, for example, replacing it with data-path, the HTML tag would be .

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/
Loli: https://gravatar.loli.net/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.

Contributors

qwqcode

Lime

Changelog

Last edited almost 2 years ago

View full history

UI Configuration ​

Configuring the Interface via Artalk.init ​

Basic Configuration (Required) ​

el ​

pageKey ​

pageTitle ​

server ​

site ​

preferRemoteConf ​

Internationalization (i18n) ​

locale ​

dateFormatter ​

Requests ​

reqTimeout ​

Emoticons ​

emoticons ​

Interface ​

placeholder ​

noComment ​

sendBtn ​

editorTravel ​

darkMode ​

flatMode ​

nestMax ​

nestSort ​

Features ​

pvEl ​

countEl ​

statPageKeyAttr ​

pageVote ​

vote ​

voteDown ​

uaBadge ​

listSort ​

imgUpload ​

imgUploader ​

imgLazyLoad ​

preview ​

Avatars ​

gravatar.mirror ​

gravatar.params ​

avatarURLBuilder ​

Comment Pagination ​

pagination.readMore ​

pagination.autoLoad ​

pagination.pageSize ​

Content Height Limit ​

heightLimit.content ​

heightLimit.children ​

heightLimit.scrollable ​

Version Check ​

versionCheck ​