Personalizando Fumadocs: Unas cuantas funciones nuevas que añadí

Últimamente le he estado dedicando mucho tiempo a Fumadocs. Su conjunto de funciones base ya es bastante sólido, pero decidí personalizar algunas cosas para hacerlo más cómodo. Espero que algo de esto te sea útil si buscas mejorar tu propia configuración.

Un componente para incrustar videos de YouTube

El componente <YouTubeEmbed> te permite insertar videos de YouTube de forma segura.

<YouTubeEmbed videoId="LX6A3OmY4uk" title="Video Title" />

Este componente cuenta con algunas propiedades interesantes:

• Responsivo (mantiene una relación de aspecto de 16:9)
• Configura automáticamente los atributos de seguridad correctos
• Optimizado para el rendimiento (carga diferida o lazy loading)

Un componente para mostrar rutas de interfaz de usuario

El componente <UiPath> te permite mostrar visualmente una secuencia de pasos en la interfaz.

<UiPath>Email activity > Has a hard bounced delivery > Yes</UiPath>

Este componente cuenta con algunas propiedades interesantes:

• Analiza automáticamente una ruta separada por >
• Renderiza cada paso como una etiqueta (chip)
• Destaca el último paso con un estilo “activo” (fondo azul)
• Separa los pasos con una flecha (›)

Los estilos se definen en app/globals.css, utilizando las siguientes clases:

• .ui-chip: el estilo de etiqueta predeterminado (fondo gris)
• .ui-chip.is-active: el estilo de etiqueta activa (fondo azul)
• .ui-sep: el estilo para el carácter separador (›)

Visualización de fechas de artículos y advertencias de contenido obsoleto

Si configuras created y updated en el frontmatter de un archivo MDX, la página del artículo mostrará automáticamente las fechas de creación y de la última actualización.

---
title: Article Title
created: 2021-04-18
updated: 2024-02-28
---

• created: la fecha de creación del artículo
• updated: la fecha de la última actualización del artículo (no se muestra si coincide con la fecha de creación)

Además, cualquier artículo que no se haya actualizado en más de un año mostrará automáticamente la siguiente advertencia:

Este artículo no se ha actualizado en más de un año. Es posible que la información aquí contenida esté desactualizada…

Esto se implementa en components/article-dates.tsx y se renderiza directamente debajo del título del artículo.

Visualización de artículos relacionados

El componente <RelatedArticles> te permite mostrar artículos relacionados dentro de una publicación.

<RelatedArticles related="blog-japanese,css,embed-html" />

Características:

• Especifica los slugs de los nombres de archivo (por ejemplo, blog-japanese) separados por comas
• Funciona tanto con carpetas entre paréntesis ((pagecreate)/blog-japanese.mdx) como con carpetas normales (payment/cant-free-trial.mdx)
• Muestra el título de cada artículo y una insignia de categoría
• Un diseño de tarjeta estilo bloque de código con fondo blanco
• Un icono Zap junto al encabezado y un icono NotebookText junto a cada artículo
• Sin subrayado en los enlaces y con cambio de color al pasar el cursor (hover)

Ejemplo de uso:

---
title: Creating a Blog Post
---

## Body

Here are some related articles.

<RelatedArticles related="blog-japanese,css,embed-html" />

También funciona sin problemas si hay espacios alrededor de las comas:

<RelatedArticles related="blog-japanese, css, embed-html" />

Archivos de implementación:

• components/related-articles.tsx: el componente de visualización de artículos relacionados
• lib/getPageBySlug.ts: una función auxiliar para obtener una página a partir de su slug
  • getPageBySlug(slug): obtiene una sola página a partir de un slug
  • getPagesBySlugs(slugs): obtiene varias páginas a partir de una lista de slugs
  • getCategoryTitleFromPage(page): obtiene el título de una categoría a partir de una página

Detalles técnicos:

• Almacena en caché el mapa de slug a página para optimizar el rendimiento
• Determina automáticamente la categoría a partir de la ruta del archivo (incluyendo carpetas entre paréntesis)
• La información de la categoría se extrae de meta.json o index.mdx mediante una caché en memoria

Funciones de la página de inicio

La página de inicio (content/docs/index.mdx) cuenta con las siguientes funciones implementadas.

Artículos añadidos recientemente y actualizados recientemente

Muestra los artículos que tienen configurado created o updated en su frontmatter, ordenados por fecha.

import { RecentCreatedPosts, RecentUpdatedPosts } from '@/components/recent-posts';

## Recently Added Articles

<RecentCreatedPosts limit={10} />

## Recently Updated Articles

<RecentUpdatedPosts limit={10} />

Características:

• Cada artículo se muestra como una tarjeta con un efecto al pasar el cursor
• Aparece un icono FileText antes del título de cada artículo
• Se muestran insignias de categoría (por ejemplo, Billing, Products/Lessons)
• No se muestran las fechas; es un formato de lista simple

Archivos de implementación:

• components/recent-posts.tsx: el componente de visualización de la lista de artículos
• lib/recent-posts.ts: las funciones para la obtención de artículos (getRecentCreatedPosts, getRecentUpdatedPosts)

Temas y artículos destacados (Visualización basada en categorías)

Un componente de shortcode que muestra hasta 5 artículos por categoría.

import { CategoryPosts } from '@/components/category-posts';

## Featured Topics & Articles

<CategoryPosts category="payment" limit={5} />

<CategoryPosts category="product" limit={5} />

<CategoryPosts category="students" limit={5} />

Características:

• Los nombres de las categorías se muestran como enlaces, y al hacer clic en uno se navega a la página de la categoría
• Aparece un icono BookText antes de cada artículo
• Los artículos se ordenan por los actualizados más recientemente (o por la fecha de creación si no hay fecha de actualización)
• Puedes reordenar las secciones cambiando el orden de las llamadas a <CategoryPosts /> en el archivo MDX

Pie de página (Footer)

Se muestra un pie de página compartido en todo el sitio. Está implementado en components/footer.tsx.

Diseño:

• Un diseño responsivo de dos columnas (una al lado de la otra en pantallas grandes, apiladas en dispositivos móviles)
• Columna izquierda: logotipo del sitio, descripción, iconos de redes sociales e información del usuario conectado
• Columna derecha: avisos del sitio (términos de servicio, información de actualización, etc.)

Qué incluye la columna izquierda:

• Título del sitio (enlazado a /docs)
• Descripción del sitio
• Iconos de redes sociales (GitHub, Discord, YouTube, Twitter/X)
• Información del usuario conectado (marcador de posición)
  • Estado de “Conectado”
  • Visualización del nombre de usuario
  • Botones de cerrar sesión / cambiar contraseña

Qué incluye la columna derecha:

• Descripción del sitio y avisos
• Una nota sobre cómo se actualiza la información
• Una nota sobre cómo se añaden nuevos artículos

Archivos de implementación:

• components/footer.tsx: el componente del pie de página
• app/layout.tsx: añade el pie de página al diseño raíz (root layout)

El pie de página se muestra automáticamente en todas las páginas y está estilizado utilizando las variables de tema de Fumadocs.