@brillout/docpress 0.16.7 → 0.16.8

package/Layout.tsx

@@ -27,6 +27,7 @@ import {
 } from './MenuModal/toggleMenuModal'
 import { MenuModal } from './MenuModal'
 import { autoScrollNav_SSR } from './autoScrollNav'
+import { initializeChoiceGroup_SSR } from './code-blocks/hooks/useSelectedChoice'
 import { initializeJsToggle_SSR } from './code-blocks/hooks/useSelectCodeLang'
 import { SearchLink } from './docsearch/SearchLink'
 import { navigate } from 'vike/client/router'
@@ -100,7 +101,7 @@ function Layout({ children }: { children: React.ReactNode }) {
         {content}
       </div>
       {/* Early toggling, to avoid layout jumps */}
-      <script dangerouslySetInnerHTML={{ __html: initializeJsToggle_SSR }}></script>
+      <script dangerouslySetInnerHTML={{ __html: `${initializeChoiceGroup_SSR}\n${initializeJsToggle_SSR}` }}></script>
       <Style>{getStyleLayout()}</Style>
     </div>
   )
@@ -589,7 +590,10 @@ function NavHeadLogo({ isNavLeft }: { isNavLeft?: true }) {
               paddingLeft: 'var(--main-view-padding)',
               paddingRight: 'var(--padding-side)',
             }
-          : {}),
+          : {
+              paddingLeft: 15,
+              marginLeft: -10,
+            }),
       }}
       href="/"
       onContextMenu={!navLogo ? undefined : onContextMenu}

package/code-blocks/components/ChoiceGroup.css

@@ -0,0 +1,48 @@
+.choice-group {
+  position: relative;
+
+  &:hover {
+    .select-choice,
+    .copy-button,
+    .code-lang-toggle {
+      opacity: 1;
+    }
+  }
+
+  --select-width: 100px;
+  --select-top-position: 10px;
+  --select-right-position: 42px;
+  --has-toggle: calc(var(--select-right-position) + 61px);
+
+  .select-choice {
+    position: absolute;
+    z-index: 3;
+    height: 25px;
+    top: var(--select-top-position);
+    right: var(--select-right-position);
+    width: var(--select-width);
+
+    opacity: 0;
+    transition: opacity 0.5s ease-in-out, background-color 0.4s ease-in-out;
+
+    &.has-toggle {
+      --select-right-position: var(--has-toggle);
+    }
+
+    &:has(+ .choice .choice-group) {
+      right: calc(var(--select-width) + var(--select-right-position) + 2px);
+    }
+  }
+
+  .hidden {
+    display: none !important;
+  }
+
+  select:has(option:nth-of-type(1):not(:checked)) ~ .choice:nth-of-type(1),
+  select:has(option:nth-of-type(2):not(:checked)) ~ .choice:nth-of-type(2),
+  select:has(option:nth-of-type(3):not(:checked)) ~ .choice:nth-of-type(3),
+  select:has(option:nth-of-type(4):not(:checked)) ~ .choice:nth-of-type(4),
+  select:has(option:nth-of-type(5):not(:checked)) ~ .choice:nth-of-type(5) {
+    display: none;
+  }
+}

package/code-blocks/components/ChoiceGroup.tsx

@@ -0,0 +1,85 @@
+export { ChoiceGroup }
+
+import React, { useEffect, useRef, useState } from 'react'
+import { usePageContext } from '../../renderer/usePageContext'
+import { useSelectedChoice } from '../hooks/useSelectedChoice'
+import { useRestoreScroll } from '../hooks/useRestoreScroll'
+import { assertUsage } from '../../utils/assert'
+import { cls } from '../../utils/cls'
+import type { PageContext } from 'vike/types'
+import './ChoiceGroup.css'
+
+function ChoiceGroup({ children, choices }: { children: React.ReactNode; choices: string[] }) {
+  const pageContext = usePageContext()
+  const group = findGroup(pageContext, choices)
+  const [selectedChoice, setSelectedChoice] = useSelectedChoice(group.name, group.default)
+  const [hasJsToggle, setHasJsToggle] = useState(false)
+  const choiceGroupRef = useRef<HTMLDivElement>(null)
+  const prevPositionRef = useRestoreScroll([selectedChoice])
+  const isHidden = choices.length === 1 || !choices.includes(selectedChoice)
+
+  useEffect(() => {
+    if (!choiceGroupRef.current) return
+    const selectedChoiceEl = choiceGroupRef.current.querySelector<HTMLDivElement>(`div[id="${selectedChoice}"]`)
+    setHasJsToggle(!!selectedChoiceEl?.classList.contains('has-toggle'))
+  }, [selectedChoice])
+
+  return (
+    <div ref={choiceGroupRef} data-group-name={group.name} className="choice-group">
+      <select
+        name={`${group.name}-choices`}
+        value={selectedChoice}
+        onChange={onChange}
+        className={cls(['select-choice', hasJsToggle && 'has-toggle', isHidden && 'hidden'])}
+      >
+        {group.choices.map((choice, i) => (
+          <option key={i} value={choice} disabled={!choices.includes(choice)}>
+            {choice}
+          </option>
+        ))}
+      </select>
+      {children}
+    </div>
+  )
+
+  function onChange(e: React.ChangeEvent<HTMLSelectElement>) {
+    const el = e.target
+    prevPositionRef.current = { top: el.getBoundingClientRect().top, el }
+    setSelectedChoice(el.value)
+  }
+}
+
+function findGroup(pageContext: PageContext, choices: string[]) {
+  const { choices: choicesGroup } = pageContext.globalContext.config.docpress
+  assertUsage(choicesGroup, `+docpress.choices is not defined.`)
+
+  const groupName = Object.keys(choicesGroup).find((key) => {
+    // get only the values that exist in both choices and choicesGroup[key].choices
+    const relevantChoices = choicesGroup[key].choices.filter((choice) => choices.includes(choice))
+    // if nothing exists, skip this key
+    if (relevantChoices.length === 0) return false
+
+    // check order
+    let i = 0
+    for (const choice of choices) {
+      if (choice === relevantChoices[i]) i++
+    }
+    assertUsage(
+      i === relevantChoices.length,
+      `Choices exist for key "${key}" but NOT in order. Expected order: [${relevantChoices}], got: [${choices}]`,
+    )
+
+    return true
+  })
+  assertUsage(groupName, `the group name for [${choices}] was not found.`)
+
+  const mergedChoices = [...new Set([...choices, ...choicesGroup[groupName].choices])]
+
+  const group = {
+    name: groupName,
+    ...choicesGroup[groupName],
+    choices: mergedChoices,
+  }
+
+  return group
+}

package/code-blocks/components/CodeSnippets.tsx

@@ -4,8 +4,9 @@ export { TypescriptOnly }
 // Internal
 export { CodeSnippets }
 
-import React, { useEffect, useRef } from 'react'
+import React from 'react'
 import { useSelectCodeLang } from '../hooks/useSelectCodeLang'
+import { useRestoreScroll } from '../hooks/useRestoreScroll'
 import './CodeSnippets.css'
 
 /** Only show if TypeScript is selected */
@@ -16,18 +17,7 @@ function TypescriptOnly({ children }: { children: React.ReactNode }) {
 
 function CodeSnippets({ children, hideToggle = false }: { children: React.ReactNode; hideToggle: boolean }) {
   const [codeLangSelected, selectCodeLang] = useSelectCodeLang()
-  const prevPositionRef = useRef<null | { top: number; el: Element }>(null)
-
-  // Restores the scroll position of the toggle element after toggling languages.
-  useEffect(() => {
-    if (!prevPositionRef.current) return
-    const { top, el } = prevPositionRef.current
-    const delta = el.getBoundingClientRect().top - top
-    if (delta !== 0) {
-      window.scrollBy(0, delta)
-    }
-    prevPositionRef.current = null
-  }, [codeLangSelected])
+  const prevPositionRef = useRestoreScroll([codeLangSelected])
 
   return (
     <div className="code-snippets">

package/code-blocks/components/Pre.tsx

@@ -1,11 +1,35 @@
 export { Pre }
 
-import React, { ComponentPropsWithoutRef, useState } from 'react'
+import React, { useState } from 'react'
+import { cls } from '../../utils/cls'
 import './Pre.css'
 
-function Pre({ children, ...props }: ComponentPropsWithoutRef<'pre'> & { 'hide-menu'?: string }) {
+// Styling defined in src/css/code/diff.css
+const classRemoved = [
+  //
+  'diff-entire-file',
+  'diff-entire-file-removed',
+].join(' ')
+const classAdded = [
+  //
+  'diff-entire-file',
+  'diff-entire-file-added',
+].join(' ')
+
+type AdditionalProps = {
+  'hide-menu'?: string
+  'file-added'?: string
+  'file-removed'?: string
+}
+
+function Pre({ children, ...props }: React.ComponentPropsWithoutRef<'pre'> & AdditionalProps) {
+  const { className, ...rest } = props
+
   return (
-    <pre {...props}>
+    <pre
+      className={cls([className, props['file-added'] && classAdded, props['file-removed'] && classRemoved])}
+      {...rest}
+    >
       {!props['hide-menu'] && <CopyButton />}
       {children}
     </pre>

package/code-blocks/hooks/useLocalStorage.ts

@@ -0,0 +1,39 @@
+export { useLocalStorage }
+
+import { useCallback, useSyncExternalStore } from 'react'
+
+/**
+ * A simple, generic `useLocalStorage` hook with SSR and cross-tab support.
+ *
+ * @param storageKey The key used in localStorage.
+ * @param clientValue Default value for the client.
+ * @param ssrValue Optional fallback for server-side rendering.
+ * @returns A tuple `[value, setValue]`.
+ */
+function useLocalStorage(storageKey: string, clientValue: string, ssrValue?: string) {
+  const subscribe = useCallback(
+    (callback: () => void) => {
+      const listener = (e: StorageEvent) => {
+        if (e.key === storageKey) callback()
+      }
+      window.addEventListener('storage', listener)
+      return () => window.removeEventListener('storage', listener)
+    },
+    [storageKey],
+  )
+
+  const getSnapshot = useCallback(() => {
+    const storedValue = localStorage.getItem(storageKey)
+    return storedValue || clientValue
+  }, [storageKey, clientValue])
+
+  const setValue = (value: string) => {
+    localStorage.setItem(storageKey, value)
+    // Manually dispatch a storage event to force update in the current tab
+    window.dispatchEvent(new StorageEvent('storage', { key: storageKey }))
+  }
+
+  const value = useSyncExternalStore(subscribe, getSnapshot, () => ssrValue || clientValue)
+
+  return [value, setValue] as const
+}

package/code-blocks/hooks/useMDXComponents.tsx

@@ -4,9 +4,11 @@ import React from 'react'
 import type { UseMdxComponents } from '@mdx-js/mdx'
 import { Pre } from '../components/Pre.js'
 import { CodeSnippets } from '../components/CodeSnippets.js'
+import { ChoiceGroup } from '../components/ChoiceGroup.js'
 
 const useMDXComponents: UseMdxComponents = () => {
   return {
+    ChoiceGroup,
     CodeSnippets,
     pre: (props) => <Pre {...props} />,
   }

package/code-blocks/hooks/useRestoreScroll.ts

@@ -0,0 +1,31 @@
+export { useRestoreScroll }
+
+import React, { useEffect, useRef } from 'react'
+
+type ScrollPosition = { top: number; el: Element }
+
+/**
+ * useRestoreScroll
+ *
+ * Keeps the page from jumping when content changes,
+ * preserving the user’s scroll position.
+ *
+ * @param deps Dependencies that trigger scroll restoration
+ * @returns Ref holding the tracked element and its previous top position
+ */
+function useRestoreScroll(deps: React.DependencyList) {
+  const prevPositionRef = useRef<ScrollPosition | null>(null)
+
+  useEffect(() => {
+    if (!prevPositionRef.current) return
+
+    const { top, el } = prevPositionRef.current
+    const delta = el.getBoundingClientRect().top - top
+
+    if (delta !== 0) window.scrollBy(0, delta)
+
+    prevPositionRef.current = null
+  }, deps)
+
+  return prevPositionRef
+}

package/code-blocks/hooks/useSelectCodeLang.ts

@@ -1,57 +1,14 @@
 export { useSelectCodeLang }
 export { initializeJsToggle_SSR }
 
-import { useState, useEffect, useCallback } from 'react'
-import { assertWarning } from '../../utils/assert'
+import { useLocalStorage } from './useLocalStorage'
 
 const storageKey = 'docpress:code-lang'
 const codeLangDefaultSsr = 'ts'
 const codeLangDefaultClient = 'js'
 
 function useSelectCodeLang() {
-  const [codeLangSelected, setCodeLangSelected] = useState(codeLangDefaultSsr)
-  const updateState = () => {
-    setCodeLangSelected(getCodeLangStorage())
-  }
-  const updateStateOnStorageEvent = (event: StorageEvent) => {
-    if (event.key === storageKey) updateState()
-  }
-
-  const getCodeLangStorage = () => {
-    try {
-      return window.localStorage.getItem(storageKey) ?? codeLangDefaultClient
-    } catch (error) {
-      console.error(error)
-      assertWarning(false, 'Error reading from localStorage')
-      return codeLangDefaultClient
-    }
-  }
-
-  const selectCodeLang = useCallback((value: string) => {
-    try {
-      window.localStorage.setItem(storageKey, value)
-      setCodeLangSelected(value)
-      window.dispatchEvent(new CustomEvent('code-lang-storage'))
-    } catch (error) {
-      console.error(error)
-      assertWarning(false, 'Error setting localStorage')
-    }
-  }, [])
-
-  useEffect(() => {
-    // Initial load from localStorage
-    updateState()
-    // Update code lang in current tab
-    window.addEventListener('code-lang-storage', updateState)
-    // Update code lang if changed in another tab
-    window.addEventListener('storage', updateStateOnStorageEvent)
-    return () => {
-      window.removeEventListener('code-lang-storage', updateState)
-      window.removeEventListener('storage', updateStateOnStorageEvent)
-    }
-  }, [])
-
-  return [codeLangSelected, selectCodeLang] as const
+  return useLocalStorage(storageKey, codeLangDefaultClient, codeLangDefaultSsr)
 }
 
 // WARNING: We cannot use the variables storageKey nor codeLangDefaultClient here: closures
@@ -66,9 +23,3 @@ function initializeJsToggle() {
     for (const input of inputs) input.checked = false
   }
 }
-
-declare global {
-  interface WindowEventMap {
-    'code-lang-storage': CustomEvent
-  }
-}

package/code-blocks/hooks/useSelectedChoice.ts

@@ -0,0 +1,34 @@
+export { useSelectedChoice }
+export { initializeChoiceGroup_SSR }
+
+import { useState } from 'react'
+import { useLocalStorage } from './useLocalStorage'
+
+const keyPrefix = 'docpress'
+
+/**
+ * Tracks the selected choice.
+ * Uses `useLocalStorage` if `persistId` is provided, otherwise regular state.
+ *
+ * @param persistId Optional ID to persist selection.
+ * @param defaultValue Default choice value.
+ * @returns `[selectedChoice, setSelectedChoice]`.
+ */
+function useSelectedChoice(persistId: string | null, defaultValue: string) {
+  if (!persistId) return useState(defaultValue)
+
+  return useLocalStorage(`${keyPrefix}:${persistId}`, defaultValue)
+}
+
+// WARNING: We cannot use the keyPrefix variable here: closures don't work because we serialize the function.
+const initializeChoiceGroup_SSR = `initializeChoiceGroup();${initializeChoiceGroup.toString()};`
+function initializeChoiceGroup() {
+  const groupsElements = document.querySelectorAll<HTMLDivElement>('[data-group-name]')
+  for (const groupEl of groupsElements) {
+    const groupName = groupEl.getAttribute('data-group-name')!
+    const selectedChoice = localStorage.getItem(`docpress:${groupName}`)
+    if (!selectedChoice) continue
+    const selectEl = groupEl.querySelector<HTMLSelectElement>(`.select-choice`)
+    if (selectEl) selectEl.value = selectedChoice
+  }
+}

package/code-blocks/rehypeMetaToProps.ts

@@ -23,41 +23,47 @@ function rehypeMetaToProps() {
   return (tree: Root) => {
     visit(tree, 'element', (node, _index, parent) => {
       if (node.tagName === 'code' && parent?.type === 'element' && parent.tagName === 'pre') {
-        const props = parseMetaString(node.data?.meta)
+        const meta = parseMetaString(node.data?.meta)
         parent.properties ??= {}
-        parent.properties = { ...parent.properties, ...props }
+        parent.properties = { ...parent.properties, ...meta.props }
       }
     })
   }
 }
 
 /**
- * Minimal parser for a metadata string into key-value pairs.
+ * Simple parser for a metadata string into key-value pairs and a remaining unparsed string.
  *
- * Supports simple patterns: key or key="value".
+ * Supports simple patterns: key or key=value.
  *
- * Keys must contain only letters, dashes, or underscores (no digits).
- * Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys must contain only letters, dashes, or underscores (no digits).
+ * - Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys and values are stored in `props`.
+ * - If `propNames` is provided, only keys included in that list are extracted.
+ * - Unextracted tokens remain in `rest`.
  *
- * Example:
- *   parseMetaString('foo fooBar="value"')
- *   => { foo: 'true', foo_bar: 'value' }
- *
- * @param metaString - The input metadata string.
- * @returns A plain object of parsed key-value pairs.
+ * @param meta - The input metadata string.
+ * @param propNames - Optional whitelist of property names to extract.
+ * @returns An object containing:
+ *   - `props`: a map of extracted properties
+ *   - `rest`: the remaining metadata string after extraction
  */
-function parseMetaString(metaString: ElementData['meta']): Record<string, string> {
-  if (!metaString) return {}
+function parseMetaString<Name extends string = string>(meta: ElementData['meta'], propNames?: Name[]): PropsType<Name> {
+  if (!meta) return { props: {}, rest: '' }
 
-  const props: Record<string, string> = {}
+  let str = meta
 
-  const keyValuePairRE = /([a-zA-Z_-]+)(?:=([^"'\s]+))?(?=\s|$)/g
-  for (const match of metaString.matchAll(keyValuePairRE)) {
-    let [_, key, value] = match
-    props[kebabCase(key)] = value || 'true'
-  }
+  const keyValuePairRE = /(?<name>[a-zA-Z_-]+)(?:=([^"'\s]+))?/g
+  const props: PropsType['props'] = {}
+
+  str = str.replaceAll(keyValuePairRE, (match, name, value) => {
+    if (propNames && !propNames.includes(name)) return match
 
-  return props
+    props[kebabCase(name)] = value || 'true'
+    return ''
+  })
+
+  return { props, rest: str.trim() }
 }
 
 // Simple function to convert a camelCase or PascalCase string to kebab-case.
@@ -67,3 +73,8 @@ function kebabCase(str: string) {
     .replace('_', '-')
     .toLowerCase()
 }
+
+interface PropsType<Name extends string = string> {
+  props: Partial<Record<Name, string>>
+  rest: string
+}

package/code-blocks/remarkChoiceGroup.ts

@@ -0,0 +1,112 @@
+export { remarkChoiceGroup }
+
+import type { Code, Root } from 'mdast'
+import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx'
+import type { ContainerDirective } from 'mdast-util-directive'
+import { visit } from 'unist-util-visit'
+import { parseMetaString } from './rehypeMetaToProps.js'
+import { generateChoiceGroup } from './utils/generateChoiceGroup.js'
+
+type Node = Code | MdxJsxFlowElement | ContainerDirective
+
+function remarkChoiceGroup() {
+  return function (tree: Root) {
+    visit(tree, (node) => {
+      if (node.type === 'code') {
+        if (!node.meta) return
+        const meta = parseMetaString(node.meta, ['choice'])
+        const { choice } = meta.props
+        node.meta = meta.rest
+
+        if (choice) node.data ??= { choice }
+      }
+      if (node.type === 'containerDirective' && node.name === 'Choice') {
+        if (!node.attributes) return
+        const { id: choice } = node.attributes
+        if (choice) {
+          node.data ??= { choice }
+          node.attributes = {}
+        }
+      }
+    })
+
+    const replaced = new WeakSet()
+    visit(tree, (node) => {
+      if (!('children' in node) || replaced.has(node)) return 'skip'
+      if (node.type === 'mdxJsxFlowElement') return 'skip'
+
+      let start = -1
+      let end = 0
+
+      const process = () => {
+        if (start === -1 || start === end) return
+        const nodes = node.children.slice(start, end) as Node[]
+        const groupedNodes = groupByNodeType(nodes)
+        const replacements: MdxJsxFlowElement[] = []
+
+        for (const groupedNode of groupedNodes) {
+          const replacement = generateChoiceGroup(groupedNode)
+
+          replacements.push(replacement)
+          replaced.add(replacement)
+        }
+
+        node.children.splice(start, end - start, ...replacements)
+
+        end = start
+        start = -1
+      }
+
+      for (; end < node.children.length; end++) {
+        const child = node.children[end]
+
+        if (!['code', 'mdxJsxFlowElement', 'containerDirective'].includes(child.type)) {
+          process()
+          continue
+        }
+
+        if (!child.data?.choice) {
+          process()
+          continue
+        }
+
+        if (start === -1) start = end
+      }
+
+      process()
+    })
+  }
+}
+
+type NodeGroup = {
+  value: string
+  children: Node[]
+}
+
+function groupByNodeType(nodes: Node[]) {
+  const groupedNodes = new Set<NodeGroup[]>()
+  const filters = [...new Set(nodes.flat().map((node) => (node.type === 'code' ? node.lang! : node.name)))]
+
+  filters.map((filter) => {
+    const nodesByChoice = new Map<string, Node[]>()
+    nodes
+      .filter((node) => (node.type === 'code' ? node.lang! : node.name) === filter)
+      .map((node) => {
+        const choice = node.data!.choice!
+        const nodes = nodesByChoice.get(choice) ?? []
+        nodes.push(node)
+        node.data = {}
+        nodesByChoice.set(choice, nodes)
+      })
+
+    groupedNodes.add([...nodesByChoice].map(([name, nodes]) => ({ value: name, children: nodes })))
+  })
+
+  return [...groupedNodes]
+}
+
+declare module 'mdast' {
+  export interface Data {
+    choice?: string
+  }
+}

package/code-blocks/remarkDetype.ts

@@ -82,7 +82,11 @@ function transformYaml(node: CodeNode) {
 
 async function transformTsToJs(node: CodeNode, file: VFile) {
   const { codeBlock, index, parent } = node
-  const maxWidth = Number(parseMetaString(codeBlock.meta)['max-width'])
+  const meta = parseMetaString(codeBlock.meta, ['max-width', 'choice'])
+  const maxWidth = Number(meta.props['max-width'])
+  const { choice } = meta.props
+  codeBlock.meta = meta.rest
+
   let codeBlockReplacedJs = replaceFileNameSuffixes(codeBlock.value)
   let codeBlockContentJs = ''
 
@@ -136,8 +140,8 @@ async function transformTsToJs(node: CodeNode, file: VFile) {
   // Add `hideToggle` attribute (prop) to `CodeSnippets` if the only change was replacing `.ts` with `.js`
   if (codeBlockReplacedJs === codeBlockContentJs) {
     attributes.push({
-      name: 'hideToggle',
       type: 'mdxJsxAttribute',
+      name: 'hideToggle',
     })
   }
 
@@ -148,6 +152,9 @@ async function transformTsToJs(node: CodeNode, file: VFile) {
     children: [jsCode, codeBlock],
     attributes,
   }
+
+  if (choice) container.data ??= { choice }
+
   parent.children.splice(index, 1, container)
 }
 

package/code-blocks/remarkPkgManager.ts

@@ -0,0 +1,45 @@
+export { remarkPkgManager }
+
+import type { Code, Root } from 'mdast'
+import { visit } from 'unist-util-visit'
+import convert from 'npm-to-yarn'
+import { parseMetaString } from './rehypeMetaToProps.js'
+import { generateChoiceGroup } from './utils/generateChoiceGroup.js'
+
+const PKG_MANAGERS = ['pnpm', 'yarn', 'bun'] as const
+
+function remarkPkgManager() {
+  return function (tree: Root) {
+    visit(tree, 'code', (node, index, parent) => {
+      if (!parent || typeof index === 'undefined') return
+      if (!['sh', 'shell'].includes(node.lang || '')) return
+      if (node.value.indexOf('npm') === -1 && node.value.indexOf('npx') === -1) return
+
+      let choice: string | undefined = undefined
+      const nodes = new Map<string, Code>()
+
+      if (node.meta) {
+        const meta = parseMetaString(node.meta, ['choice'])
+        choice = meta.props['choice']
+        node.meta = meta.rest
+      }
+
+      nodes.set('npm', node)
+
+      for (const pm of PKG_MANAGERS) {
+        nodes.set(pm, {
+          type: node.type,
+          lang: node.lang,
+          meta: node.meta,
+          value: convert(node.value, pm),
+        })
+      }
+
+      const groupedNodes = [...nodes].map(([name, node]) => ({ value: name, children: [node] }))
+      const replacement = generateChoiceGroup(groupedNodes)
+
+      replacement.data ??= { choice }
+      parent.children.splice(index, 1, replacement)
+    })
+  }
+}

package/code-blocks/utils/generateChoiceGroup.ts

@@ -0,0 +1,87 @@
+export { generateChoiceGroup }
+export type { CodeChoice }
+
+import type { BlockContent, DefinitionContent } from 'mdast'
+import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx-jsx'
+
+type CodeChoice = {
+  value: string
+  children: (BlockContent | DefinitionContent)[]
+}
+
+function generateChoiceGroup(codeChoices: CodeChoice[]): MdxJsxFlowElement {
+  const attributes: MdxJsxAttribute[] = []
+  const children: MdxJsxFlowElement[] = []
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'choices',
+    value: {
+      type: 'mdxJsxAttributeValueExpression',
+      value: '',
+      data: {
+        estree: {
+          type: 'Program',
+          sourceType: 'module',
+          comments: [],
+          body: [
+            {
+              type: 'ExpressionStatement',
+              expression: {
+                type: 'ArrayExpression',
+                // @ts-ignore: Missing properties in type definition
+                elements: codeChoices.map((choice) => ({
+                  type: 'Literal',
+                  value: choice.value,
+                })),
+              },
+            },
+          ],
+        },
+      },
+    },
+  })
+
+  for (const codeChoice of codeChoices) {
+    const classNames = ['choice']
+    if (findHasJsToggle(codeChoice.children[0])) {
+      classNames.push('has-toggle')
+    }
+
+    children.push({
+      type: 'mdxJsxFlowElement',
+      name: 'div',
+      attributes: [
+        { type: 'mdxJsxAttribute', name: 'id', value: codeChoice.value },
+        { type: 'mdxJsxAttribute', name: 'className', value: classNames.join(' ') },
+      ],
+      children: codeChoice.children.every((node) => node.type === 'containerDirective')
+        ? codeChoice.children.flatMap((node) => [...node.children])
+        : codeChoice.children,
+    })
+  }
+
+  return {
+    type: 'mdxJsxFlowElement',
+    name: 'ChoiceGroup',
+    attributes,
+    children,
+  }
+}
+
+function findHasJsToggle(node: BlockContent | DefinitionContent) {
+  if (node.type === 'containerDirective' && node.name === 'Choice') {
+    return (
+      node.children[0].type === 'mdxJsxFlowElement' &&
+      node.children[0].name === 'CodeSnippets' &&
+      node.children[0].attributes.every(
+        (attribute) => attribute.type !== 'mdxJsxAttribute' || attribute.name !== 'hideToggle',
+      )
+    )
+  }
+  return (
+    node.type === 'mdxJsxFlowElement' &&
+    node.name === 'CodeSnippets' &&
+    node.attributes.every((attribute) => attribute.type !== 'mdxJsxAttribute' || attribute.name !== 'hideToggle')
+  )
+}

package/dist/code-blocks/rehypeMetaToProps.d.ts

@@ -18,18 +18,24 @@ import type { ElementData, Root } from 'hast';
  */
 declare function rehypeMetaToProps(): (tree: Root) => void;
 /**
- * Minimal parser for a metadata string into key-value pairs.
+ * Simple parser for a metadata string into key-value pairs and a remaining unparsed string.
  *
- * Supports simple patterns: key or key="value".
+ * Supports simple patterns: key or key=value.
  *
- * Keys must contain only letters, dashes, or underscores (no digits).
- * Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys must contain only letters, dashes, or underscores (no digits).
+ * - Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys and values are stored in `props`.
+ * - If `propNames` is provided, only keys included in that list are extracted.
+ * - Unextracted tokens remain in `rest`.
  *
- * Example:
- *   parseMetaString('foo fooBar="value"')
- *   => { foo: 'true', foo_bar: 'value' }
- *
- * @param metaString - The input metadata string.
- * @returns A plain object of parsed key-value pairs.
+ * @param meta - The input metadata string.
+ * @param propNames - Optional whitelist of property names to extract.
+ * @returns An object containing:
+ *   - `props`: a map of extracted properties
+ *   - `rest`: the remaining metadata string after extraction
  */
-declare function parseMetaString(metaString: ElementData['meta']): Record<string, string>;
+declare function parseMetaString<Name extends string = string>(meta: ElementData['meta'], propNames?: Name[]): PropsType<Name>;
+interface PropsType<Name extends string = string> {
+    props: Partial<Record<Name, string>>;
+    rest: string;
+}

package/dist/code-blocks/rehypeMetaToProps.js

@@ -20,38 +20,43 @@ function rehypeMetaToProps() {
     return (tree) => {
         visit(tree, 'element', (node, _index, parent) => {
             if (node.tagName === 'code' && parent?.type === 'element' && parent.tagName === 'pre') {
-                const props = parseMetaString(node.data?.meta);
+                const meta = parseMetaString(node.data?.meta);
                 parent.properties ??= {};
-                parent.properties = { ...parent.properties, ...props };
+                parent.properties = { ...parent.properties, ...meta.props };
             }
         });
     };
 }
 /**
- * Minimal parser for a metadata string into key-value pairs.
+ * Simple parser for a metadata string into key-value pairs and a remaining unparsed string.
  *
- * Supports simple patterns: key or key="value".
+ * Supports simple patterns: key or key=value.
  *
- * Keys must contain only letters, dashes, or underscores (no digits).
- * Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys must contain only letters, dashes, or underscores (no digits).
+ * - Keys are converted to kebab-case. Values default to "true" if missing.
+ * - Keys and values are stored in `props`.
+ * - If `propNames` is provided, only keys included in that list are extracted.
+ * - Unextracted tokens remain in `rest`.
  *
- * Example:
- *   parseMetaString('foo fooBar="value"')
- *   => { foo: 'true', foo_bar: 'value' }
- *
- * @param metaString - The input metadata string.
- * @returns A plain object of parsed key-value pairs.
+ * @param meta - The input metadata string.
+ * @param propNames - Optional whitelist of property names to extract.
+ * @returns An object containing:
+ *   - `props`: a map of extracted properties
+ *   - `rest`: the remaining metadata string after extraction
  */
-function parseMetaString(metaString) {
-    if (!metaString)
-        return {};
+function parseMetaString(meta, propNames) {
+    if (!meta)
+        return { props: {}, rest: '' };
+    let str = meta;
+    const keyValuePairRE = /(?<name>[a-zA-Z_-]+)(?:=([^"'\s]+))?/g;
     const props = {};
-    const keyValuePairRE = /([a-zA-Z_-]+)(?:=([^"'\s]+))?(?=\s|$)/g;
-    for (const match of metaString.matchAll(keyValuePairRE)) {
-        let [_, key, value] = match;
-        props[kebabCase(key)] = value || 'true';
-    }
-    return props;
+    str = str.replaceAll(keyValuePairRE, (match, name, value) => {
+        if (propNames && !propNames.includes(name))
+            return match;
+        props[kebabCase(name)] = value || 'true';
+        return '';
+    });
+    return { props, rest: str.trim() };
 }
 // Simple function to convert a camelCase or PascalCase string to kebab-case.
 function kebabCase(str) {

package/dist/code-blocks/remarkChoiceGroup.d.ts

@@ -0,0 +1,8 @@
+export { remarkChoiceGroup };
+import type { Root } from 'mdast';
+declare function remarkChoiceGroup(): (tree: Root) => void;
+declare module 'mdast' {
+    interface Data {
+        choice?: string;
+    }
+}

package/dist/code-blocks/remarkChoiceGroup.js

@@ -0,0 +1,84 @@
+export { remarkChoiceGroup };
+import { visit } from 'unist-util-visit';
+import { parseMetaString } from './rehypeMetaToProps.js';
+import { generateChoiceGroup } from './utils/generateChoiceGroup.js';
+function remarkChoiceGroup() {
+    return function (tree) {
+        visit(tree, (node) => {
+            if (node.type === 'code') {
+                if (!node.meta)
+                    return;
+                const meta = parseMetaString(node.meta, ['choice']);
+                const { choice } = meta.props;
+                node.meta = meta.rest;
+                if (choice)
+                    node.data ??= { choice };
+            }
+            if (node.type === 'containerDirective' && node.name === 'Choice') {
+                if (!node.attributes)
+                    return;
+                const { id: choice } = node.attributes;
+                if (choice) {
+                    node.data ??= { choice };
+                    node.attributes = {};
+                }
+            }
+        });
+        const replaced = new WeakSet();
+        visit(tree, (node) => {
+            if (!('children' in node) || replaced.has(node))
+                return 'skip';
+            if (node.type === 'mdxJsxFlowElement')
+                return 'skip';
+            let start = -1;
+            let end = 0;
+            const process = () => {
+                if (start === -1 || start === end)
+                    return;
+                const nodes = node.children.slice(start, end);
+                const groupedNodes = groupByNodeType(nodes);
+                const replacements = [];
+                for (const groupedNode of groupedNodes) {
+                    const replacement = generateChoiceGroup(groupedNode);
+                    replacements.push(replacement);
+                    replaced.add(replacement);
+                }
+                node.children.splice(start, end - start, ...replacements);
+                end = start;
+                start = -1;
+            };
+            for (; end < node.children.length; end++) {
+                const child = node.children[end];
+                if (!['code', 'mdxJsxFlowElement', 'containerDirective'].includes(child.type)) {
+                    process();
+                    continue;
+                }
+                if (!child.data?.choice) {
+                    process();
+                    continue;
+                }
+                if (start === -1)
+                    start = end;
+            }
+            process();
+        });
+    };
+}
+function groupByNodeType(nodes) {
+    const groupedNodes = new Set();
+    const filters = [...new Set(nodes.flat().map((node) => (node.type === 'code' ? node.lang : node.name)))];
+    filters.map((filter) => {
+        const nodesByChoice = new Map();
+        nodes
+            .filter((node) => (node.type === 'code' ? node.lang : node.name) === filter)
+            .map((node) => {
+            const choice = node.data.choice;
+            const nodes = nodesByChoice.get(choice) ?? [];
+            nodes.push(node);
+            node.data = {};
+            nodesByChoice.set(choice, nodes);
+        });
+        groupedNodes.add([...nodesByChoice].map(([name, nodes]) => ({ value: name, children: nodes })));
+    });
+    return [...groupedNodes];
+}

package/dist/code-blocks/remarkDetype.js

@@ -65,7 +65,10 @@ function transformYaml(node) {
 }
 async function transformTsToJs(node, file) {
     const { codeBlock, index, parent } = node;
-    const maxWidth = Number(parseMetaString(codeBlock.meta)['max-width']);
+    const meta = parseMetaString(codeBlock.meta, ['max-width', 'choice']);
+    const maxWidth = Number(meta.props['max-width']);
+    const { choice } = meta.props;
+    codeBlock.meta = meta.rest;
     let codeBlockReplacedJs = replaceFileNameSuffixes(codeBlock.value);
     let codeBlockContentJs = '';
     // Remove TypeScript from the TS/TSX/Vue code node
@@ -113,8 +116,8 @@ async function transformTsToJs(node, file) {
     // Add `hideToggle` attribute (prop) to `CodeSnippets` if the only change was replacing `.ts` with `.js`
     if (codeBlockReplacedJs === codeBlockContentJs) {
         attributes.push({
-            name: 'hideToggle',
             type: 'mdxJsxAttribute',
+            name: 'hideToggle',
         });
     }
     // Wrap both the original `codeBlock` and `jsCode` with <CodeSnippets>
@@ -124,6 +127,8 @@ async function transformTsToJs(node, file) {
         children: [jsCode, codeBlock],
         attributes,
     };
+    if (choice)
+        container.data ??= { choice };
     parent.children.splice(index, 1, container);
 }
 // Replace all '.ts' extensions with '.js'

package/dist/code-blocks/remarkPkgManager.d.ts

@@ -0,0 +1,3 @@
+export { remarkPkgManager };
+import type { Root } from 'mdast';
+declare function remarkPkgManager(): (tree: Root) => void;

package/dist/code-blocks/remarkPkgManager.js

@@ -0,0 +1,38 @@
+export { remarkPkgManager };
+import { visit } from 'unist-util-visit';
+import convert from 'npm-to-yarn';
+import { parseMetaString } from './rehypeMetaToProps.js';
+import { generateChoiceGroup } from './utils/generateChoiceGroup.js';
+const PKG_MANAGERS = ['pnpm', 'yarn', 'bun'];
+function remarkPkgManager() {
+    return function (tree) {
+        visit(tree, 'code', (node, index, parent) => {
+            if (!parent || typeof index === 'undefined')
+                return;
+            if (!['sh', 'shell'].includes(node.lang || ''))
+                return;
+            if (node.value.indexOf('npm') === -1 && node.value.indexOf('npx') === -1)
+                return;
+            let choice = undefined;
+            const nodes = new Map();
+            if (node.meta) {
+                const meta = parseMetaString(node.meta, ['choice']);
+                choice = meta.props['choice'];
+                node.meta = meta.rest;
+            }
+            nodes.set('npm', node);
+            for (const pm of PKG_MANAGERS) {
+                nodes.set(pm, {
+                    type: node.type,
+                    lang: node.lang,
+                    meta: node.meta,
+                    value: convert(node.value, pm),
+                });
+            }
+            const groupedNodes = [...nodes].map(([name, node]) => ({ value: name, children: [node] }));
+            const replacement = generateChoiceGroup(groupedNodes);
+            replacement.data ??= { choice };
+            parent.children.splice(index, 1, replacement);
+        });
+    };
+}

package/dist/code-blocks/utils/generateChoiceGroup.d.ts

@@ -0,0 +1,9 @@
+export { generateChoiceGroup };
+export type { CodeChoice };
+import type { BlockContent, DefinitionContent } from 'mdast';
+import type { MdxJsxFlowElement } from 'mdast-util-mdx-jsx';
+type CodeChoice = {
+    value: string;
+    children: (BlockContent | DefinitionContent)[];
+};
+declare function generateChoiceGroup(codeChoices: CodeChoice[]): MdxJsxFlowElement;

package/dist/code-blocks/utils/generateChoiceGroup.js

@@ -0,0 +1,66 @@
+export { generateChoiceGroup };
+function generateChoiceGroup(codeChoices) {
+    const attributes = [];
+    const children = [];
+    attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'choices',
+        value: {
+            type: 'mdxJsxAttributeValueExpression',
+            value: '',
+            data: {
+                estree: {
+                    type: 'Program',
+                    sourceType: 'module',
+                    comments: [],
+                    body: [
+                        {
+                            type: 'ExpressionStatement',
+                            expression: {
+                                type: 'ArrayExpression',
+                                // @ts-ignore: Missing properties in type definition
+                                elements: codeChoices.map((choice) => ({
+                                    type: 'Literal',
+                                    value: choice.value,
+                                })),
+                            },
+                        },
+                    ],
+                },
+            },
+        },
+    });
+    for (const codeChoice of codeChoices) {
+        const classNames = ['choice'];
+        if (findHasJsToggle(codeChoice.children[0])) {
+            classNames.push('has-toggle');
+        }
+        children.push({
+            type: 'mdxJsxFlowElement',
+            name: 'div',
+            attributes: [
+                { type: 'mdxJsxAttribute', name: 'id', value: codeChoice.value },
+                { type: 'mdxJsxAttribute', name: 'className', value: classNames.join(' ') },
+            ],
+            children: codeChoice.children.every((node) => node.type === 'containerDirective')
+                ? codeChoice.children.flatMap((node) => [...node.children])
+                : codeChoice.children,
+        });
+    }
+    return {
+        type: 'mdxJsxFlowElement',
+        name: 'ChoiceGroup',
+        attributes,
+        children,
+    };
+}
+function findHasJsToggle(node) {
+    if (node.type === 'containerDirective' && node.name === 'Choice') {
+        return (node.children[0].type === 'mdxJsxFlowElement' &&
+            node.children[0].name === 'CodeSnippets' &&
+            node.children[0].attributes.every((attribute) => attribute.type !== 'mdxJsxAttribute' || attribute.name !== 'hideToggle'));
+    }
+    return (node.type === 'mdxJsxFlowElement' &&
+        node.name === 'CodeSnippets' &&
+        node.attributes.every((attribute) => attribute.type !== 'mdxJsxAttribute' || attribute.name !== 'hideToggle'));
+}

package/dist/types/Config.d.ts

@@ -37,6 +37,7 @@ type Config = {
     navLogoStyle?: React.CSSProperties;
     navLogoTextStyle?: React.CSSProperties;
     globalNote?: React.ReactNode;
+    choices?: Record<string, Choice>;
 };
 /** Order in Algolia search results */
 type Category = string | {
@@ -44,3 +45,7 @@ type Category = string | {
     /** Hide from Algolia search */
     hide?: boolean;
 };
+type Choice = {
+    choices: string[];
+    default: string;
+};

package/dist/vite.config.js

@@ -4,10 +4,13 @@ import react from '@vitejs/plugin-react-swc';
 import { parsePageSections } from './parsePageSections.js';
 import rehypePrettyCode from 'rehype-pretty-code';
 import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
 import { transformerNotationDiff } from '@shikijs/transformers';
 import { rehypeMetaToProps } from './code-blocks/rehypeMetaToProps.js';
 import { remarkDetype } from './code-blocks/remarkDetype.js';
 import { shikiTransformerAutoLinks } from './code-blocks/shikiTransformerAutoLinks.js';
+import { remarkPkgManager } from './code-blocks/remarkPkgManager.js';
+import { remarkChoiceGroup } from './code-blocks/remarkChoiceGroup.js';
 const root = process.cwd();
 const prettyCode = [
     rehypePrettyCode,
@@ -18,7 +21,7 @@ const prettyCode = [
     },
 ];
 const rehypePlugins = [prettyCode, [rehypeMetaToProps]];
-const remarkPlugins = [remarkGfm, remarkDetype];
+const remarkPlugins = [remarkGfm, remarkDirective, remarkDetype, remarkPkgManager, remarkChoiceGroup];
 const config = {
     root,
     plugins: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brillout/docpress",
-  "version": "0.16.7",
+  "version": "0.16.8",
   "type": "module",
   "dependencies": {
     "@brillout/picocolors": "^1.0.10",
@@ -12,7 +12,9 @@
     "@shikijs/transformers": "1.2.0",
     "@vitejs/plugin-react-swc": "^3.10.2",
     "detype": "^1.1.3",
+    "npm-to-yarn": "^3.0.1",
     "rehype-pretty-code": "0.13.0",
+    "remark-directive": "^4.0.0",
     "remark-gfm": "4.0.0",
     "shiki": "1.2.0",
     "unist-util-visit": "^5.0.0",
@@ -65,6 +67,7 @@
     "@types/node": "^24.10.0",
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
+    "mdast-util-directive": "^3.1.0",
     "mdast-util-mdx-jsx": "^3.2.0"
   },
   "repository": "https://github.com/brillout/docpress",

package/renderer/onRenderHtml.tsx

@@ -99,6 +99,7 @@ function getOpenGraphTags(url: string, documentTitle: string, config: Config) {
 // Resources:
 // - https://www.google.com/s2/favicons?domain=vike.dev
 // - https://stackoverflow.com/questions/59568586/favicon-don%c2%b4t-show-up-in-google-search-result/59577456#59577456
+// - https://stackoverflow.com/questions/76123025/attach-google-search-specific-favicon-to-html
 // - https://developers.google.com/search/docs/appearance/favicon-in-search
 //
 // Examples:
@@ -108,8 +109,10 @@ function getOpenGraphTags(url: string, documentTitle: string, config: Config) {
 //   https://rubyonrails.org
 // - Favicon shown in browser is different than favicon shown in Google:
 //   https://evilmartians.com
-//   Shown in Google: <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+//   Shown in Google: <link rel="apple-touch-icon" href="/apple-touch-icon.png" /> or <link rel="manifest" href="/manifest.webmanifest" />
 //   Shown in Browser: <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+//   https://gemini.google.com/share/8bcf76a26783
+//   https://chatgpt.com/share/696930b6-4414-800d-9c55-598ac7fa1ccb
 function getFaviconTags(config: Config) {
   const { faviconBrowser, faviconGoogle } = getFavicons(config)
   assert(faviconBrowser)

package/types/Config.ts

@@ -48,6 +48,7 @@ type Config = {
   navLogoTextStyle?: React.CSSProperties
 
   globalNote?: React.ReactNode
+  choices?: Record<string, Choice>
 }
 
 /** Order in Algolia search results */
@@ -58,3 +59,8 @@ type Category =
       /** Hide from Algolia search */
       hide?: boolean
     }
+
+type Choice = {
+  choices: string[]
+  default: string
+}

package/vite.config.ts

@@ -6,10 +6,13 @@ import type { PluginOption, UserConfig } from 'vite'
 import { parsePageSections } from './parsePageSections.js'
 import rehypePrettyCode from 'rehype-pretty-code'
 import remarkGfm from 'remark-gfm'
+import remarkDirective from 'remark-directive'
 import { transformerNotationDiff } from '@shikijs/transformers'
 import { rehypeMetaToProps } from './code-blocks/rehypeMetaToProps.js'
 import { remarkDetype } from './code-blocks/remarkDetype.js'
 import { shikiTransformerAutoLinks } from './code-blocks/shikiTransformerAutoLinks.js'
+import { remarkPkgManager } from './code-blocks/remarkPkgManager.js'
+import { remarkChoiceGroup } from './code-blocks/remarkChoiceGroup.js'
 
 const root = process.cwd()
 const prettyCode = [
@@ -21,7 +24,7 @@ const prettyCode = [
   },
 ]
 const rehypePlugins: any = [prettyCode, [rehypeMetaToProps]]
-const remarkPlugins = [remarkGfm, remarkDetype]
+const remarkPlugins = [remarkGfm, remarkDirective, remarkDetype, remarkPkgManager, remarkChoiceGroup]
 
 const config: UserConfig = {
   root,