From 34d793697c759f3d066a8b16a1d8b6181a9f17a6 Mon Sep 17 00:00:00 2001 From: qwqcode Date: Thu, 19 Sep 2024 18:27:24 +0800 Subject: [PATCH] chore(docs): refine deployment documentation --- docs/docs/.vitepress/config/en.ts | 10 +- docs/docs/.vitepress/config/shared.ts | 19 +-- docs/docs/.vitepress/theme/Artalk.vue | 2 +- docs/docs/en/develop/import-framework.md | 12 +- docs/docs/en/guide/deploy.md | 131 ++++++++++++++++----- docs/docs/en/guide/frontend/artalk-lite.md | 10 +- docs/docs/package.json | 1 - docs/docs/zh/develop/import-framework.md | 12 +- docs/docs/zh/guide/deploy.md | 102 +++++++++++++--- docs/docs/zh/guide/frontend/artalk-lite.md | 10 +- pnpm-lock.yaml | 8 -- test/vue-test/src/components/Artalk.vue | 2 +- ui/artalk-sidebar/src/main.ts | 2 +- ui/plugin-auth/index.html | 2 +- 14 files changed, 235 insertions(+), 88 deletions(-) diff --git a/docs/docs/.vitepress/config/en.ts b/docs/docs/.vitepress/config/en.ts index 336a216c2..3d65123ea 100644 --- a/docs/docs/.vitepress/config/en.ts +++ b/docs/docs/.vitepress/config/en.ts @@ -17,7 +17,7 @@ export const en = defineConfig({ ], }, { - text: 'Core Guide', + text: 'Basic Usage', collapsed: false, items: [ { text: 'Sidebar', link: '/en/guide/frontend/sidebar.md' }, @@ -32,7 +32,7 @@ export const en = defineConfig({ ], }, { - text: 'Advanced Guide', + text: 'Extensions', collapsed: false, items: [ { text: 'Emoticons', link: '/en/guide/frontend/emoticons.md' }, @@ -46,7 +46,7 @@ export const en = defineConfig({ ], }, { - text: 'Configuration Documentation', + text: 'Configurations', collapsed: false, items: [ { text: 'Environment Variables', link: '/en/guide/env.md' }, @@ -55,7 +55,7 @@ export const en = defineConfig({ ], }, { - text: 'Deployment Instructions', + text: 'Deployment details', collapsed: false, items: [ { text: 'Daemon Process', link: '/en/guide/backend/daemon.md' }, @@ -100,7 +100,7 @@ export const en = defineConfig({ link: '/en/guide/intro', }, { - text: 'Deployment', + text: 'Installation', link: '/en/guide/deploy', }, { diff --git a/docs/docs/.vitepress/config/shared.ts b/docs/docs/.vitepress/config/shared.ts index e8c5e2e71..fe6c52643 100644 --- a/docs/docs/.vitepress/config/shared.ts +++ b/docs/docs/.vitepress/config/shared.ts @@ -1,5 +1,4 @@ import { defineConfig } from 'vitepress' -import iterator from 'markdown-it-for-inline' import * as Version from '../../code/ArtalkVersion.json' export const shared = defineConfig({ @@ -24,12 +23,18 @@ export const shared = defineConfig({ dark: 'github-dark', }, config: (md) => { - md.use(iterator, 'artalk_version', 'text', function (tokens, idx) { - tokens[idx].content = tokens[idx].content.replace(/:ArtalkVersion:/g, Version.latest) - }) - md.use(iterator, 'artalk_version_link', 'link_open', (tokens, idx) => { - const href = tokens[idx].attrGet('href') - tokens[idx].attrSet('href', href.replace(/:ArtalkVersion:/g, Version.latest)) + const renderVersion = (c: string) => String(c).replace(/:ArtalkVersion:/g, Version.latest) + md.core.ruler.push('artalk_version', (state) => { + state.tokens?.forEach((token) => { + if (token.type === 'inline') { + token.children?.forEach((child) => { + if (['text', 'link_open', 'code_inline'].includes(child.type)) + child.content = renderVersion(child.content) + }) + } else if (token.type === 'fence') { + token.content = renderVersion(token.content) + } + }) }) }, }, diff --git a/docs/docs/.vitepress/theme/Artalk.vue b/docs/docs/.vitepress/theme/Artalk.vue index fc02af205..65c34eca9 100644 --- a/docs/docs/.vitepress/theme/Artalk.vue +++ b/docs/docs/.vitepress/theme/Artalk.vue @@ -10,7 +10,7 @@ import { ArtalkKatexPlugin } from '@artalk/plugin-katex' import { ArtalkLightboxPlugin } from '@artalk/plugin-lightbox' import 'lightgallery/css/lightgallery.css' import 'katex/dist/katex.min.css' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const el = ref(null) diff --git a/docs/docs/en/develop/import-framework.md b/docs/docs/en/develop/import-framework.md index 01013a68e..48ed04f84 100644 --- a/docs/docs/en/develop/import-framework.md +++ b/docs/docs/en/develop/import-framework.md @@ -17,7 +17,7 @@ pnpm add artalk import Artalk from 'artalk' import { onMounted, onBeforeUnmount, ref } from 'vue' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const el = ref() @@ -50,7 +50,7 @@ import Artalk from 'artalk' import { onMounted, onBeforeUnmount, ref, watch, nextTick } from 'vue' import { useRouter } from 'vue-router' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const el = ref() const router = useRouter() @@ -100,7 +100,7 @@ onBeforeUnmount(() => { ```tsx [React Hooks] import React, { useEffect, useRef } from 'react' import { useLocation } from 'react-router-dom' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import Artalk from 'artalk' const ArtalkComment = () => { @@ -131,7 +131,7 @@ export default ArtalkComment ```jsx [React Class] import React, { createRef } from 'react' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import Artalk from 'artalk' export default class ArtalkComponent extends React.Component { @@ -166,7 +166,7 @@ export default class ArtalkComponent extends React.Component { ```tsx import { onCleanup, onMount } from 'solid-js' import Artalk from 'artalk' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const ArtalkComment = () => { let el: HTMLDivElement @@ -198,7 +198,7 @@ const ArtalkComment = () => { import Artalk from 'artalk' import { onMount, onDestroy } from 'svelte' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' let el let artalk diff --git a/docs/docs/en/guide/deploy.md b/docs/docs/en/guide/deploy.md index 17fed12ff..3ba0ad2ea 100644 --- a/docs/docs/en/guide/deploy.md +++ b/docs/docs/en/guide/deploy.md @@ -47,11 +47,11 @@ Import the embedded client JS and CSS resources from the Artalk server to your w
``` @@ -161,26 +161,50 @@ docker-compose exec artalk bash # Enter the container More information: [Docker](./backend/docker.md) / [Environment Variables](./env.md) -## Client Projects (Node.js) +## Client -Install Artalk via npm: +If you have a frontend or Node.js web project, this following guide will help you integrate the Artalk **Client** into your web project. -```bash +### Client Installation + +Install via npm: + +::: code-group + +```sh [npm] npm install artalk ``` +```sh [yarn] +yarn add artalk +``` + +```sh [pnpm] +pnpm add artalk +``` + +```sh [bun] +bun add artalk +``` + +::: + +(or see [CDN Resources](#client-cdn-resources)). + +### Client Usage + Import Artalk in your web project: ```js -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import Artalk from 'artalk' const artalk = Artalk.init({ - el: '#Comments', // Selector of the bound element - pageKey: '/post/1', // Permalink - pageTitle: 'About Introducing Artalk', // Page title (leave blank to auto-fetch) - server: 'http://artalk.example.com:8080', // Artalk server address - site: 'Artalk Blog', // Your site name + el: document.querySelector('#Comments'), // DOM element where you want to mount + pageKey: '/post/1', // Permalink + pageTitle: 'About Introducing Artalk', // Page title + server: 'http://artalk.example.com:8080', // Artalk server address + site: 'Artalk Blog', // Site name }) ``` @@ -191,36 +215,87 @@ For more references: - [Client API Reference](../develop/fe-api.md) - [Client Configuration](./frontend/config.md) -## Client CDN Resources +### Client CDN Resources + +To use Artalk in the browser via CDN, for modern browsers (which support [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)), you can use [esm.sh](https://esm.sh) or [esm.run](https://esm.run): + +::: code-group + +```html [ES Module] + +
+ + + +``` + +```html [Legacy] + +
+ + + + +``` + +::: + +Don't forget to include the CSS file: + +```html + +``` ::: tip Latest Version of Artalk -The current latest version number of the Artalk client is: **:ArtalkVersion:** +The latest Artalk client version is: `:ArtalkVersion:` To upgrade the client, replace the numeric part of the version number in the URL. ::: -The Artalk server had embedded the client resources. Ensure version compatibility when using public CDN resources. +Note: The Artalk server had embedded the client resources. Ensure version compatibility when using public CDN resources. + +::: details Alternative CDNs **CDNJS** -> -> -> +``` +https://cdnjs.cloudflare.com/ajax/libs/artalk/:ArtalkVersion:/Artalk.js +``` -::: details View More +``` +https://cdnjs.cloudflare.com/ajax/libs/artalk/:ArtalkVersion:/Artalk.css +``` -**UNPKG** +**JSDELIVR** -> -> -> +``` +https://cdn.jsdelivr.net/npm/artalk@:ArtalkVersion:/dist/Artalk.js +``` -**JSDELIVR** +``` +https://cdn.jsdelivr.net/npm/artalk@:ArtalkVersion:/dist/Artalk.css +``` + +**UNPKG** + +``` +https://unpkg.com/artalk@:ArtalkVersion:/dist/Artalk.js +``` -> -> -> +``` +https://unpkg.com/artalk@:ArtalkVersion:/dist/Artalk.css +``` ::: diff --git a/docs/docs/en/guide/frontend/artalk-lite.md b/docs/docs/en/guide/frontend/artalk-lite.md index 4e0e5a2ce..fdd32c849 100644 --- a/docs/docs/en/guide/frontend/artalk-lite.md +++ b/docs/docs/en/guide/frontend/artalk-lite.md @@ -8,6 +8,10 @@ ArtalkLite is a simplified version of Artalk, with the following differences com ArtalkLite is released alongside the standard version. You can obtain it by modifying the file name in the CDN address to ArtalkLite: -> https://unpkg.com/artalk@2/dist/ArtalkLite.js -> -> https://unpkg.com/artalk@2/dist/ArtalkLite.css +``` +https://unpkg.com/artalk@:ArtalkVersion:/dist/ArtalkLite.js +``` + +``` +https://unpkg.com/artalk@:ArtalkVersion:/dist/ArtalkLite.css +``` diff --git a/docs/docs/package.json b/docs/docs/package.json index deacbe5c5..c2c73361f 100644 --- a/docs/docs/package.json +++ b/docs/docs/package.json @@ -16,7 +16,6 @@ }, "devDependencies": { "artalk": "workspace:^", - "markdown-it-for-inline": "^2.0.1", "vitepress": "1.3.4" }, "dependencies": { diff --git a/docs/docs/zh/develop/import-framework.md b/docs/docs/zh/develop/import-framework.md index 302d56c31..f85e3412a 100644 --- a/docs/docs/zh/develop/import-framework.md +++ b/docs/docs/zh/develop/import-framework.md @@ -17,7 +17,7 @@ pnpm add artalk import Artalk from 'artalk' import { onMounted, onBeforeUnmount, ref } from 'vue' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const el = ref() @@ -50,7 +50,7 @@ import Artalk from 'artalk' import { onMounted, onBeforeUnmount, ref, watch, nextTick } from 'vue' import { useRouter } from 'vue-router' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const el = ref() const router = useRouter() @@ -100,7 +100,7 @@ onBeforeUnmount(() => { ```tsx [React Hooks] import React, { useEffect, useRef } from 'react' import { useLocation } from 'react-router-dom' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import Artalk from 'artalk' const ArtalkComment = () => { @@ -133,7 +133,7 @@ export default ArtalkComment ```jsx [React Class] import React, { createRef } from 'react' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import Artalk from 'artalk' export default class Artalk extends React.Component { @@ -168,7 +168,7 @@ export default class Artalk extends React.Component { ```tsx import { onCleanup, onMount } from 'solid-js' import Artalk from 'artalk' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const ArtalkComment = () => { let el: HTMLDivElement @@ -200,7 +200,7 @@ const ArtalkComment = () => { import Artalk from 'artalk' import { onMount, onDestroy } from 'svelte' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' let el let artalk diff --git a/docs/docs/zh/guide/deploy.md b/docs/docs/zh/guide/deploy.md index 40d097e99..8a1ab56d4 100644 --- a/docs/docs/zh/guide/deploy.md +++ b/docs/docs/zh/guide/deploy.md @@ -49,11 +49,11 @@ docker exec -it artalk artalk admin
``` @@ -164,22 +164,50 @@ docker-compose exec artalk bash # 进入容器 更多信息：[Docker](./backend/docker.md) / [环境变量](./env.md) -## 前端项目 (Node.js) +## 客户端 + +如果你有前端或 Node.js Web 项目，以下指南将帮助你将 Artalk **客户端** 集成到你的 Web 项目中。 + +### 客户端安装 通过 NPM 安装 Artalk： -```bash +::: code-group + +```sh [npm] npm install artalk ``` +```sh [yarn] +yarn add artalk +``` + +```sh [pnpm] +pnpm add artalk +``` + +```sh [bun] +bun add artalk +``` + +::: + +(你也可以选择通过 [CDN 资源](#客户端-cdn-资源) 引入). + +### 客户端集成 + 在你的 Web 项目中引入 Artalk： ```js -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import Artalk from 'artalk' Artalk.init({ - // ... + el: document.querySelector('#Comments'), // 挂载的 DOM 元素 + pageKey: '/post/1', // 固定链接 + pageTitle: '关于引入 Artalk 的这档子事', // 页面标题 + server: 'http://artalk.example.com:8080', // 后端地址 + site: 'Artalk 的博客', // 站点名 }) ``` @@ -190,30 +218,70 @@ Artalk.init({ - [前端 API](../develop/fe-api.md) - [前端配置](./frontend/config.md) -## 前端 CDN 资源 +### 客户端 CDN 资源 + +要通过 CDN 在浏览器中使用 Artalk，对于现代浏览器 (支持 [ES 模块](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules))，可以使用 [esm.sh](https://esm.sh) 或 [esm.run](https://esm.run): + +::: code-group + +```html [ES 模块] + +
+ + + +``` + +```html [传统方式] + +
+ + + + +``` + +::: + +记得引入 CSS 文件： + +```html + +``` ::: tip Artalk 最新版本 -当前 Artalk 前端最新版本号为： **:ArtalkVersion:** +Artalk 客户端的最新版本为：`:ArtalkVersion:` 若需升级前端将 URL 中的版本号数字部分替换即可。 ::: -Artalk 后端程序内嵌了前端 JS、CSS 文件，使用公共 CDN 资源请注意版本兼容性。 +注：Artalk 后端程序内嵌了前端 JS、CSS 文件，使用公共 CDN 资源请注意版本兼容性。 -**CDNJS** +::: details 其他可选的 CDN 资源 -> -> -> - -::: details 查看更多 **SUSTech Mirrors (境内)** > > > +**CDNJS** + +> +> +> + **UNPKG** > diff --git a/docs/docs/zh/guide/frontend/artalk-lite.md b/docs/docs/zh/guide/frontend/artalk-lite.md index 468603e73..83553740a 100644 --- a/docs/docs/zh/guide/frontend/artalk-lite.md +++ b/docs/docs/zh/guide/frontend/artalk-lite.md @@ -8,6 +8,10 @@ ArtalkLite 是 Artalk 的精简版本，相较于普通版，有以下区别： ArtalkLite 随普通版一起发布，你可以将 CDN 地址文件名修改为 ArtalkLite 获取： -> https://unpkg.com/artalk@2/dist/ArtalkLite.js -> -> https://unpkg.com/artalk@2/dist/ArtalkLite.css +``` +https://unpkg.com/artalk@:ArtalkVersion:/dist/ArtalkLite.js +``` + +``` +https://unpkg.com/artalk@:ArtalkVersion:/dist/ArtalkLite.css +``` diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4cd613753..fb684f64a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -129,9 +129,6 @@ importers: artalk: specifier: workspace:^ version: link:../../ui/artalk - markdown-it-for-inline: - specifier: ^2.0.1 - version: 2.0.1 vitepress: specifier: 1.3.4 version: 1.3.4(@algolia/client-search@5.4.3)(@types/node@22.5.5)(@types/react@18.3.7)(postcss@8.4.47)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(sass@1.79.1)(search-insights@2.17.2)(terser@5.33.0)(typescript@5.6.2) @@ -3233,9 +3230,6 @@ packages: mark.js@8.11.1: resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} - markdown-it-for-inline@2.0.1: - resolution: {integrity: sha512-JGOi3/Ohhzehs+1qSA4CkDydmVBtiYi2q2BD//YtTbSK+75InrGJX2MtPq1AdMeC4BV7rwEhq1+3pLnwGbsgzA==} - marked@14.1.2: resolution: {integrity: sha512-f3r0yqpz31VXiDB/wj9GaOB0a2PRLQl6vJmXiFrniNwjkKdvakqJRULhjFKJpxOchlCRiG5fcacoUZY5Xa6PEQ==} engines: {node: '>= 18'} @@ -8048,8 +8042,6 @@ snapshots: mark.js@8.11.1: {} - markdown-it-for-inline@2.0.1: {} - marked@14.1.2: {} marked@4.3.0: {} diff --git a/test/vue-test/src/components/Artalk.vue b/test/vue-test/src/components/Artalk.vue index d47303add..3c15fff3e 100644 --- a/test/vue-test/src/components/Artalk.vue +++ b/test/vue-test/src/components/Artalk.vue @@ -2,7 +2,7 @@ import { onMounted, onUnmounted, ref } from 'vue' import { useRoute } from 'vue-router' import Artalk from 'artalk' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' const el = ref() const route = useRoute() diff --git a/ui/artalk-sidebar/src/main.ts b/ui/artalk-sidebar/src/main.ts index 3de7f5918..7800945aa 100644 --- a/ui/artalk-sidebar/src/main.ts +++ b/ui/artalk-sidebar/src/main.ts @@ -4,7 +4,7 @@ import Artalk from 'artalk' import { createRouter, createWebHashHistory } from 'vue-router' import { routes } from 'vue-router/auto-routes' import { setupI18n } from './i18n' -import 'artalk/dist/Artalk.css' +import 'artalk/Artalk.css' import './style.scss' import App from './App.vue' import { setArtalk } from './global' diff --git a/ui/plugin-auth/index.html b/ui/plugin-auth/index.html index a03f57e6e..3b2f36de1 100644 --- a/ui/plugin-auth/index.html +++ b/ui/plugin-auth/index.html @@ -12,7 +12,7 @@