Este documento proporciona una referencia completa para las APIs, utilidades y opciones de configuración del tema Astro Modular.

Colecciones de Contenido

Colección de Posts

```typescript
interface PostData {
title: string;
description: string;
date: Date;
tags?: string[];
draft?: boolean;
image?: string;
imageAlt?: string;
imageOG?: boolean;
hideCoverImage?: boolean;
hideTOC?: boolean;
targetKeyword?: string;
noIndex?: boolean;
}
```

Colección de Páginas

```typescript
interface PageData {
title: string;
description: string;
draft?: boolean;
lastModified?: Date;
image?: string;
imageAlt?: string;
hideCoverImage?: boolean;
hideTOC?: boolean;
noIndex?: boolean;
}
```

Colección de Proyectos

```typescript
interface ProjectData {
title: string;
description: string;
date: Date;
categories?: string[];
repositoryUrl?: string;
demoUrl?: string;
status?: string; // Cualquier valor de cadena - “completed”, “in-progress”, “On Hold”, etc.
image?: string;
imageAlt?: string;
hideCoverImage?: boolean;
hideTOC?: boolean;
draft?: boolean;
noIndex?: boolean;
featured?: boolean;
}
```

Colección de Documentación

```typescript
interface DocumentationData {
title: string;
description: string;
category: string;
order: number;
lastModified?: Date;
version?: string;
image?: string;
imageAlt?: string;
hideCoverImage?: boolean;
hideTOC?: boolean;
draft?: boolean;
noIndex?: boolean;
showTOC?: boolean;
featured?: boolean;
}
```

Colección Especial

```typescript
interface SpecialData {
title: string;
description: string;
hideTOC?: boolean;
}
```

Páginas Especiales:

• home.md - Contenido del blurb de la página de inicio
• 404.md - Contenido de la página de error 404
• posts.md - Página de índice de posts (solo título y descripción)
• projects.md - Contenido de la página de índice de proyectos
• docs.md - Contenido de la página de índice de documentación

API de Configuración

Interfaz de Configuración del Sitio

```typescript
interface SiteConfig {
// Información del Sitio
site: string;
title: string;
description: string;
author: string;
language: string;
faviconThemeAdaptive: boolean;
defaultOgImageAlt: string;

// Configuración Global
theme: “minimal” | “oxygen” | “atom” | “ayu” | “catppuccin” | “charcoal” | “dracula” | “everforest” | “flexoki” | “gruvbox” | “macos” | “nord” | “obsidian” | “rose-pine” | “sky” | “solarized” | “things” | “custom”;
customThemeFile?: string;
availableThemes: “default” | Array;
fonts: {
source: “local” | “cdn”;
families: {
body: string;
heading: string;
mono: string;
};
display: “swap” | “fallback” | “optional”;
};
layout: {
contentWidth: string;
};
tableOfContents: {
enabled: boolean;
depth: number;
};
footer: {
enabled: boolean;
content: string;
showSocialIconsInFooter: boolean;
};
hideScrollBar: boolean;
scrollToTop: boolean;
featureButton: “mode” | “graph” | “theme” | “none”;
deployment: {
platform: “netlify” | “vercel” | “github-pages” | “cloudflare-workers”;
};

// Paleta de Comandos
commandPalette: {
enabled: boolean;
shortcut: string;
placeholder: string;
search: {
posts: boolean;
pages: boolean;
projects: boolean;
docs: boolean;
};
sections: {
quickActions: boolean;
pages: boolean;
social: boolean;
};
quickActions: {
enabled: boolean;
toggleMode: boolean;
graphView: boolean;
changeTheme: boolean;
};
};

// Foto de Perfil
profilePicture: {
enabled: boolean;
image: string;
alt: string;
size: “sm” | “md” | “lg”;
url?: string;
placement: “footer” | “header”;
style: “circle” | “square” | “none”;
};

// Navegación
navigation: {
showNavigation: boolean;
style: “minimal” | “traditional”;
showMobileMenu: boolean;
pages: NavigationItem[];
social: Array<{ title: string; url: string; icon: string }>;
};

// Opciones de Inicio
homeOptions: {
featuredPost: {
enabled: boolean;
type: “latest” | “featured”;
slug?: string;
};
recentPosts: {
enabled: boolean;
count: number;
};
projects: {
enabled: boolean;
count: number;
};
docs: {
enabled: boolean;
count: number;
};
blurb: {
placement: “above” | “below” | “none”;
};
};

// Opciones de Posts
postOptions: {
postsPerPage: number;
readingTime: boolean;
wordCount: boolean;
tags: boolean;
linkedMentions: {
enabled: boolean;
linkedMentionsCompact: boolean;
};
graphView: {
enabled: boolean;
showInSidebar: boolean;
maxNodes: number;
showOrphanedPosts: boolean;
};
postNavigation: boolean;
showPostCardCoverImages: “all” | “featured” | “home” | “posts” | “featured-and-posts” | “none”;
postCardAspectRatio: AspectRatio;
customPostCardAspectRatio?: string;
comments: {
enabled: boolean;
provider: string;
repo: string;
repoId: string;
category: string;
categoryId: string;
mapping: string;
strict: string;
reactions: string;
metadata: string;
inputPosition: string;
theme: string;
lang: string;
loading: string;
};
};

// Tipos de Contenido Opcionales
optionalContentTypes: {
projects: boolean;
docs: boolean;
};
}
```

Tipos de Relación de Aspecto

```typescript
type AspectRatio =
| “16:9”
| “4:3”
| “3:2”
| “og”
| “square”
| “golden”
| “custom”;
```

Funciones de Utilidad

Generación de SEO

```typescript
// Generar datos SEO para posts
generatePostSEO(post: Post, url: string): SEOData

// Generar datos SEO para proyectos
generateProjectSEO(project: Project, url: string): SEOData

// Generar datos SEO para documentación
generateDocumentationSEO(doc: Docs, url: string): SEOData

// Generar datos SEO para páginas
generatePageSEO(page: Page, url: string): SEOData
```

Procesamiento de Markdown

```typescript
// Procesar contenido markdown y extraer datos
processMarkdown(content: string): {
excerpt: string;
wordCount: number;
hasMore: boolean;
}

// Calcular tiempo de lectura
calculateReadingTime(content: string): ReadingTime

// Extraer tiempo de lectura del plugin remark o calcular manualmente
getReadingTime(remarkData: any, content?: string): ReadingTime | null

// Generar tabla de contenidos (async)
generateTOC(headings: Heading[]): Promise<Heading[]>

// Procesar datos de contenido para visualización (posts, proyectos, docs, etc.)
processPost(post: any): Promise
```

Optimización de Imágenes

```typescript
// Optimizar ruta de imagen específicamente para posts
optimizePostImagePath(imagePath: string, postSlug?: string, postId?: string): string

// Función genérica de optimización de imágenes para todos los tipos de contenido
optimizeContentImagePath(imagePath: string, contentType: string, contentSlug?: string, contentId?: string): string

// Eliminar sintaxis de doble corchete de Obsidian de las rutas de imágenes
stripObsidianBrackets(imagePath: string): string

// Obtener imagen OG de respaldo
getDefaultOGImage(): OpenGraphImage
```

Procesamiento de Enlaces Internos

El tema usa plugins remark personalizados para manejar enlaces internos y embeds.

```typescript
// Procesamiento de wikilinks remark
remarkInternalLinks()

// Procesamiento de embeds de Obsidian
remarkObsidianEmbeds()
```

Gestión de Temas

```typescript
// Obtener colores del tema para la vista de grafo
getGraphThemeColors(): GraphThemeColors

// Actualizar variables CSS del tema
updateThemeCSSVariables(theme: string): Promise
```

Props de Componentes

Componente PostCard

```typescript
interface PostCardProps {
post: Post | Project | Docs;
eager?: boolean;
showCoverImage?: boolean;
aspectRatio?: string;
}
```

Componente TableOfContents

```typescript
interface TableOfContentsProps {
headings: Heading[];
maxDepth?: number;
}
```

Componente GiscusComments

```typescript
interface GiscusCommentsProps {
enabled: boolean;
repo: string;
repoId: string;
category: string;
categoryId: string;
mapping: string;
strict: string;
reactions: string;
metadata: string;
inputPosition: string;
theme: string;
lang: string;
loading: string;
}
```

Definiciones de Tipos

Tipos Principales

```typescript
interface Heading {
depth: number;
slug: string;
text: string;
}

interface ReadingTime {
text: string;
minutes: number;
time: number;
words: number;
}

interface SEOData {
title: string;
description: string;
canonical: string;
ogImage?: OpenGraphImage;
ogType: ‘website’ | ‘article’;
publishedTime?: string;
modifiedTime?: string;
tags?: string[];
noIndex?: boolean;
}

interface OpenGraphImage {
url: string;
alt: string;
width: number;
height: number;
}
```

Proceso de Compilación

Sincronización de Activos

El tema sincroniza automáticamente los activos desde las carpetas de contenido al directorio público durante la compilación y el desarrollo.

Plataformas de Despliegue

• Netlify: Soporte completo para redirecciones y formularios
• Vercel: Soporte completo para redirecciones y caché
• Cloudflare Workers: Configuración de despliegue compatible
• GitHub Pages: Soporte de despliegue de sitio estático

Herramientas de Desarrollo

Scripts

```bash

Desarrollo

pnpm run dev # Iniciar servidor de desarrollo
pnpm run build # Compilar para producción
pnpm run update # Actualizar tema a la última versión (mantiene tu contenido)
pnpm run sync-images # Sincronizar imágenes de contenido a público
pnpm run process-aliases # Procesar aliases de contenido
pnpm run check-images # Verificar imágenes faltantes
pnpm run version # Obtener versión del tema
```

Esta referencia de API proporciona documentación completa para todos los aspectos del tema Astro Modular, desde colecciones de contenido hasta funciones de utilidad e interfaces de componentes.