chore(docs): refine deployment documentation

ArtalkJS · Sep 19, 2024 · 34d7936 · 34d7936
1 parent b9c3b2a
commit 34d7936
Show file tree

Hide file tree

Showing 14 changed files with 235 additions and 88 deletions.
diff --git 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
@@ -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
@@ -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<HTMLElement | null>(null)
 

diff --git 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<HTMLElement>()
 
@@ -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<HTMLElement>()
 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
@@ -47,11 +47,11 @@ Import the embedded client JS and CSS resources from the Artalk server to your w
 <div id="Comments"></div>
 <script>
 Artalk.init({
-  el:        '#Comments',                // Selector of the bound element
-  pageKey:   '/post/1',                  // Permalink
-  pageTitle: 'About Introducing Artalk', // Page title (leave blank to auto-fetch)
+  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
+  site:      'Artalk Blog',                     // Your site name
 })
 </script>
 ```
@@ -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]
+<body>
+  <div id="Comments"></div>
+
+  <script type="module">
+    import Artalk from 'https://esm.sh/artalk@:ArtalkVersion:'
+
+    Artalk.init({
+      el: '#Comments',
+    })
+  </script>
+</body>
+```
+
+```html [Legacy]
+<body>
+  <div id="Comments"></div>
+
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/artalk/:ArtalkVersion:/Artalk.js"></script>
+  <script>
+    Artalk.init({
+      el: '#Comments',
+    })
+  </script>
+</body>
+```
+
+:::
+
+Don't forget to include the CSS file:
+
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/artalk/:ArtalkVersion:/Artalk.css">
+```
 
 ::: 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>
->
-> <https://cdnjs.cloudflare.com/ajax/libs/artalk/:ArtalkVersion:/Artalk.css>
+```
+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://unpkg.com/artalk@:ArtalkVersion:/dist/Artalk.js>
->
-> <https://unpkg.com/artalk@:ArtalkVersion:/dist/Artalk.css>
+```
+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://cdn.jsdelivr.net/npm/artalk@:ArtalkVersion:/dist/Artalk.js>
->
-> <https://cdn.jsdelivr.net/npm/artalk@:ArtalkVersion:/dist/Artalk.css>
+```
+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
@@ -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
@@ -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
@@ -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<HTMLElement>()
 
@@ -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<HTMLElement>()
 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