Bloques de Código

Los bloques de código con cerca en Boltdocs usan Shiki para el resaltado de sintaxis. Se calculan completamente en tiempo de compilación, asegurando tiempos de carga rápidos con cero costo de rendimiento en el lado del cliente.

Uso

Crea bloques de código usando las comillas triples estándar de Markdown. Especifica el identificador de idioma para soporte de resaltado.

// Ejemplo: src/index.ts
export function greet(name: string): string {
  return `Hello, ${name}!`
}

Parámetros del Bloque de Código (Propiedades Meta)

Boltdocs soporta parámetros personalizados en la línea de encabezado del bloque de código para configurar títulos, números de línea y ajuste de texto dinámicamente.

1. Banner de Título

Agrega title="file_name.extension" para mostrar un encabezado estilizado que contiene el nombre del archivo. Se renderiza un icono de archivo genérico junto al título para indicar el límite del bloque de código:

```tsx title="components/Button.tsx"
export const Button = () => <button>Click me</button>;
```

2. Números de Línea

Agrega showLineNumbers (o lineNumbers) para mostrar números de línea junto a tu código:

```ts showLineNumbers
const num = 42;
console.log(num);
```

3. Ajuste de Texto

Agrega wordWrap (o word-wrap) para romper líneas de código largas, evitando la barra de desplazamiento horizontal predeterminada:

```css wordWrap
.very-long-class-selector-that-needs-to-wrap-rather-than-overflowing-and-creating-a-scrollbar {
  color: red;
}
```

Combinando Parámetros

Puedes combinar estos atributos en cualquier orden:

```json title="package.json" showLineNumbers wordWrap
{
  "name": "my-cool-package",
  "version": "1.0.0",
  "description": "Un párrafo muy descriptivo que se ajustará a múltiples líneas en el renderizado del bloque de código generado en lugar de causar barras de desplazamiento horizontales."
}
```

Configuración

Puedes personalizar los temas de Shiki en boltdocs.config.ts. Puedes elegir diferentes temas para los modos claro y oscuro:

// boltdocs.config.ts
import { defineConfig } from 'boltdocs'

export default defineConfig({
  theme: {
    codeTheme: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
})

Temas Soportados

Los siguientes temas de resaltado de sintaxis están soportados de forma predeterminada:

• github-light / github-dark
• tokyo-night
• dracula
• nord
• one-dark-pro
• one-light

Características Mejoradas

• Botón de Copiar Código: Un botón de copiar flotante se agrega automáticamente a la esquina superior derecha de cada bloque de código.
• Ajuste de Texto: Las líneas de código largas se desbordan limpiamente con una barra de desplazamiento o se ajustan cuando se establece el parámetro wordWrap o word-wrap.

Personalizando Bloques de Código

Si el diseño, estilo o interacciones predeterminados del bloque de código no se ajustan a tu sistema de diseño, puedes construir fácilmente un componente de bloque de código completamente personalizado.

Boltdocs expone el estado central y la lógica de los bloques de código a través del hook useCodeBlock, permitiéndote enfocarte puramente en tu renderizado visual personalizado sin tener que reescribir el análisis complejo de HTML resaltado, temporizadores de copiado al portapapeles, lógica de expansión y truncamiento, o integraciones de formularios de retroalimentación.

1. Registrando un Bloque de Código Personalizado

Para sobrescribir el componente de bloque de código predeterminado, registra tu componente personalizado como el renderizador de la etiqueta pre en tu archivo docs/mdx-components.tsx:

import { CustomCodeBlock } from '../src/components/CustomCodeBlock'

export default {
  pre: CustomCodeBlock,
}

2. Construyendo un Componente de Bloque de Código Personalizado

Usa el hook useCodeBlock de 'boltdocs/client' para acceder al estado resuelto del bloque de código y envolver la salida en las primitivas de diseño importadas desde 'boltdocs/primitives':

import { useCodeBlock } from 'boltdocs/client'
import { CodeBlock } from 'boltdocs/primitives'

export function CustomCodeBlock(props) {
  const {
    preRef,
    copied,
    handleCopy,
    effectiveTitle,
    effectiveHighlightedHtml,
    isExpandable,
    isExpanded,
    setIsExpanded,
    shouldTruncate,
  } = useCodeBlock(props)

  return (
    <CodeBlock plain={props.plain}>
      {effectiveTitle && (
        <CodeBlock.Header>
          <CodeBlock.Group>
            <span>{effectiveTitle}</span>
          </CodeBlock.Group>
          
          <button onClick={handleCopy}>
            {copied ? '¡Copiado!' : 'Copiar'}
          </button>
        </CodeBlock.Header>
      )}

      <CodeBlock.Content shouldTruncate={shouldTruncate}>
        {effectiveHighlightedHtml ? (
          <div
            ref={preRef}
            dangerouslySetInnerHTML={{ __html: effectiveHighlightedHtml }}
          />
        ) : (
          <pre ref={preRef}>{props.children}</pre>
        )}

        {isExpandable && (
          <button onClick={() => setIsExpanded(!isExpanded)}>
            {isExpanded ? 'Mostrar menos' : 'Expandir'}
          </button>
        )}
      </CodeBlock.Content>
    </CodeBlock>
  )
}

3. Referencia de la API del Hook (useCodeBlock)

El hook useCodeBlock acepta las propiedades estándar del bloque de código (pasadas desde el compilador MDX) y devuelve el siguiente estado y propiedades resueltas: