fix: use explicit id to merge meta head tags

__tests__/unit/shared/shared.test.ts

@@ -0,0 +1,33 @@
+import { mergeHead } from 'shared/shared'
+
+describe('shared/shared', () => {
+  test('mergeHead uses id as the key regardless of attribute order', () => {
+    const result = mergeHead(
+      [['meta', { id: 'description', name: 'description', content: 'site' }]],
+      [['meta', { content: 'page', name: 'description', id: 'description' }]]
+    )
+
+    expect(result).toEqual([
+      ['meta', { content: 'page', name: 'description', id: 'description' }]
+    ])
+  })
+
+  test('mergeHead keeps meta tags with unique ids', () => {
+    const result = mergeHead([
+      [
+        'meta',
+        { content: '/preview.png', property: 'og:image', id: 'og-image' }
+      ],
+      [
+        'meta',
+        {
+          content: '/preview.png',
+          property: 'og:image:url',
+          id: 'og-image-url'
+        }
+      ]
+    ])
+
+    expect(result).toHaveLength(2)
+  })
+})

docs/en/reference/site-config.md

@@ -248,6 +248,24 @@ type HeadConfig =
   | [string, Record<string, string>, string]
 ```
 
+VitePress uses the first attribute of each `meta` element as its key when merging `head` entries. To keep entries with identical first attributes, or to make the key independent of attribute order, give each entry a unique `id`. When present, `id` is used as the key regardless of its position in the attributes object.
+
+```ts
+export default {
+  head: [
+    ['meta', { content: '/preview.png', property: 'og:image', id: 'og-image' }],
+    [
+      'meta',
+      {
+        content: '/preview.png',
+        property: 'og:image:url',
+        id: 'og-image-url'
+      }
+    ]
+  ]
+}
+```
+
 #### Example: Adding a favicon
 
 ```ts

src/shared/shared.ts

@@ -203,7 +203,8 @@ export function mergeHead(...headArrays: HeadConfig[][]): HeadConfig[] {
   for (const current of headArrays) {
     for (const tag of current) {
       const [type, attrs] = tag
-      const keyAttr = Object.entries(attrs)[0]
+      const entries = Object.entries(attrs)
+      const keyAttr = entries.find(([name]) => name === 'id') ?? entries[0]
 
       if (type !== 'meta' || !keyAttr) {
         merged.push(tag)