Artalk Documentation

Artalk is a lightweight, feature-rich comment system. Key capabilities include:

• Frontend: ~40KB Vanilla JS, sidebar management, social login, Markdown support, emoticons (OwO compatible), LaTeX support, night mode, and image lightbox.
• Backend: High-performance Golang server, email/push notifications, captcha, comment moderation (spam/content detection), image uploading (custom/image bed support), and multi-site management.
• Management: Admin dashboard, comment voting, sorting, pinning, search, and data migration/backup.
• Extensibility: Plugin system and OpenAPI-formatted API documentation.

Artalk provides several entry points for developers depending on whether you are integrating the comment system, building plugins, or working on the backend.

• Frontend Integration: Guides for embedding Artalk in blogs or frameworks, using the Frontend API, listening to Frontend Events, and configuring the frontend.
• Plugin Development: Documentation for building plugins and integrating them with Vite.
• Backend Development: Access to HTTP API documentation, environment variable configuration, and backend configuration files.
• Contribution: For setting up a local development environment to contribute to the core project, refer to the Developer Contribution Guide.

Artalk is an intuitive and feature-rich comment system designed for immediate integration into any blog, website, or web application. It consists of a lightweight Vanilla JS client (~40KB) and a high-performance Golang server.

Key characteristics:

• Client: Framework-agnostic, pure Vanilla JS.
• Server: Efficient, lightweight, and cross-platform via Golang.
• Deployment: Supports one-click deployment via Docker.
• Privacy: Open-source and self-hostable, prioritizing user privacy.

The official Docker images currently only support the following architectures:

• x86
• arm64

If you require a different architecture, you must use the Binary Deployment method instead of Docker.

Artalk supports nested imports, allowing a remote emoticon JSON file to point to other emoticon resources. This is useful for managing large or modular emoticon sets.

A remote file (e.g., emoticons.json) can contain an array that mixes URLs and data objects:

Artalk supports two primary formats for emoticon data files:

1. OwO Format: An open-source format compatible with the OwO JS plugin. You can use existing OwO JSON resources directly by providing their URL.
2. Artalk Standard Format: A native JSON/JS array format that allows you to define groups of emoticons. Each group must specify a name, a type ('emoticon' for text or 'image' for images), and an items array containing key and val pairs.

[
  {
    name: 'Emoji',
    type: 'emoticon', // Text type
    items: [
      { key: 'Hi', val: '|´・ω・)ノ' },
      { key: 'Happy', val: 'ヾ(≧∇≦*)ゝ' },
    ],
  },
  {
    name: 'Funny',
    type: 'image', // Image type
    items: [
      {
        key: 'Original Funny',
        val: '<Image URL>',
      },
    ],
  },
]

You can display statistics anywhere on your page by using specific CSS selectors and the data-page-key attribute.

• pvEl: The selector for the element that displays Page Views (Default: '.artalk-pv-count').
• countEl: The selector for the element that displays Comment Counts (Default: '.artalk-comment-count').
• statPageKeyAttr: The attribute name used to specify the page key (Default: 'data-page-key').

Usage Example: To show the comment count for a specific page, use: <span class="artalk-comment-count" data-page-key="/t/1.html"></span>

If a user logs in and Artalk detects multiple accounts with different usernames but the same email address, an Account Merging Tool will appear.

Users can choose to keep one specific username. Once selected, all comments and data associated with that email address are merged into the retained account. The original duplicate accounts are deleted, and the username on all associated comments is updated to the retained username.

When a relative path is provided in pageKey, Artalk resolves it by combining the site URL (configured in the Artalk Dashboard) with the relative path.

For example, if the site URL is https://set-example-site-url.xxx and the pageKey is /relative-path/xx.html, the resolved URL will be https://set-example-site-url.xxx/relative-path/xx.html.

These resolved URLs are used for:

• Email notifications (links to reply to comments)
• Sidebar (quick jumps to specific comments)
• Dashboard (page management and opening pages)
• Fetching page titles and other metadata