Skip to main content
MyBrain
Vista previa de Astro Modular, mostrando diferentes opciones de tema y diseño.

Configuración

Version 0.8.1

Esta guía completa cubre todo lo necesario para configurar y personalizar tu blog modular de Astro, diseñado para usuarios de Obsidian que quieren publicar contenido con mínima fricción.

Requisitos Previos y Configuración

Necesitarás:

  • Git
  • Conocimiento básico de markdown
  • Obsidian (opcional)

Si quieres compilar y probar localmente, necesitarás:

  • Node.js 24.13.0+
  • pnpm 10.29.3+ (recomendado) o npm

Instalación

# Instalar pnpm (si no está instalado)
npm install -g pnpm

# Instalar dependencias
pnpm install

# Vista previa
pnpm dev # o pnpm preview
# Disponible en http://localhost:5000

# Compilar para producción
pnpm build

Configuración

Important

Si esto aplica para ti, puedes saltar directamente a la sección Estructura de Contenido.

Configuración Principal

Configura todo en src/config.ts. La configuración está organizada en secciones:

export const siteConfig = {
  // Información del Sitio
  site: 'https://tudominio.com',
  title: 'Título de Tu Blog',
  description: 'Descripción de tu blog',
  author: 'Tu Nombre',  // Autor global para todos los posts
  language: 'es',
  faviconThemeAdaptive: true,
  defaultOgImageAlt: "Logo de Astro Modular.",
}

Personalización

Tema y Diseño

Selecciona opciones de tema y diseño en la configuración:

// Configuración Global
theme: "oxygen",
customThemeFile: "custom",
availableThemes: "default", // Muestra todos los temas integrados
fonts: {
  source: "local",
  families: {
    body: "Inter",
    heading: "Inter",
    mono: "JetBrains Mono",
  },
  display: "swap",
},
layout: {
  contentWidth: "45rem",
},
tableOfContents: {
  enabled: true,        // Toggle global de TOC para todos los posts
  depth: 4,            // Profundidad máxima de encabezados (2-6, donde 2=H2, 3=H3, etc.)
},
footer: {
  enabled: true,
  content: `© 2025 {author}. Construido con Astro Modular.`,
  showSocialIconsInFooter: true,
},
hideScrollBar: false,  // Ocultar barra de scroll del navegador
scrollToTop: true,     // Mostrar botón de scroll hacia arriba
featureButton: "mode", // "mode" | "graph" | "theme" | "none" - qué hace el botón principal
deployment: {
  platform: "netlify", // "netlify" | "vercel" | "github-pages" | "cloudflare-workers"
},

Las opciones de tema son actualmente Oxygen, Minimal, Atom, Ayu, Catppuccin, Charcoal, Dracula, Everforest, Flexoki, Gruvbox, macOS, Nord, Obsidian, Rosé Pine, Sky, Solarized, Things y Custom. Los cambios de tema son visibles en tiempo real con pnpm dev.

Temas Personalizados

Puedes crear tus propios temas personalizados:

  1. Renombrar la plantilla: Renombra src/themes/custom/custom.ts a lo que quieras
  2. Modificar colores: Actualiza las escalas de colores para coincidir con tu diseño
  3. Actualizar configuración:
    • Establece theme: "custom" en src/config.ts
    • Establece customThemeFile: "nombre-de-tu-tema" (nombre de archivo sin extensión .ts)
  4. Probar: Usa pnpm dev para ver los cambios de tu tema en tiempo real

¡El sistema automáticamente encuentra y usa tu tema personalizado!

Consulta src/themes/custom/README.md para instrucciones detalladas y mejores prácticas.

Configuración de Fuentes

Personaliza fuentes para encabezados, texto del cuerpo y código con opciones de carga flexibles:

fonts: {
  source: "local", // "local" para fuentes auto-hospedadas, "cdn" para Google Fonts CDN
  families: {
    body: "Inter",      // Familia de fuente para texto del cuerpo
    heading: "Inter",   // Familia de fuente para encabezados
    mono: "JetBrains Mono", // Familia de fuente monoespaciada
  },
  display: "swap", // Estrategia de carga de fuentes: "swap", "fallback", o "optional"
}

Opciones de Carga de Fuentes:

  • Fuentes locales (source: "local"): Fuentes auto-hospedadas para mejor rendimiento y privacidad
  • Fuentes CDN (source: "cdn"): Google Fonts CDN para opciones de fuentes ilimitadas

Fuentes Soportadas (Modo Local):

  • Sans-Serif: Inter, Roboto, Open Sans, Lato, Poppins, Source Sans Pro, Nunito, Montserrat
  • Serif: Playfair Display, Merriweather, Lora, Crimson Text, PT Serif, Libre Baskerville
  • Monospace: Fira Code, JetBrains Mono, Source Code Pro, IBM Plex Mono, Cascadia Code

Paleta de Comandos

La paleta de comandos proporciona navegación instantánea y funcionalidad de búsqueda:

commandPalette: {
    enabled: true,
    shortcut: "ctrl+K",
    placeholder: "Buscar posts",
    search: {
      posts: true,
      pages: false,
      projects: false,
      docs: false,
    },
    sections: {
      quickActions: true,
      pages: true,
      social: true,
    },
    quickActions: {
      enabled: true,        // Habilitar sección de acciones rápidas
      toggleMode: true,     // Mostrar toggle de modo oscuro/claro
      graphView: true,      // Mostrar botón de vista de grafo
      changeTheme: true,    // Mostrar selector de tema
    },
}

Características:

  • Búsqueda Instantánea: Presiona ctrl+K (o un atajo diferente que definas) para buscar contenido
  • Acciones Rápidas: Cambio de tema, atajos de navegación
  • Personalizable: Cambia atajo, texto de marcador de posición y secciones habilitadas

Foto de Perfil

Agrega un toque personal con una foto de perfil configurable:

profilePicture: {
  enabled: true,
  image: "/profile.jpg",        // Ruta a tu imagen (colocar en directorio public/)
  alt: "Foto de perfil",        // Texto alternativo para accesibilidad
  size: "md",                   // "sm", "md", o "lg"
  url: "/about",                // URL opcional para enlazar al hacer clic
  placement: "footer",          // "footer" o "header"
  style: "circle",              // "circle", "square", o "none"
}

Configuración de Navegación

Personaliza el menú de navegación de tu sitio y enlaces sociales:

navigation: {
  showNavigation: true,           // Mostrar/ocultar navegación principal
  style: "traditional",           // Estilo de navegación "minimal" o "traditional"
  showMobileMenu: true,           // Mostrar toggle de menú móvil
  pages: [                        // Elementos del menú de navegación (NavigationItem[])
    { title: "Posts", url: "/posts/" },
    { title: "Proyectos", url: "/projects/" },
    { title: "Documentación", url: "/docs/" },
    { title: "Acerca de", url: "/about/", children: [...] },
  ],
  social: [                       // Enlaces de redes sociales
    { title: "GitHub", url: "https://github.com/usuario", icon: "github" },
    { title: "X", url: "https://x.com/usuario", icon: "x-twitter" },
  ],
}

Configuración de la Página de Inicio

El contenido de la página de inicio se controla por la sección homeOptions:

  • Post Destacado: Mostrar el post más reciente o un post destacado específico
  • Posts Recientes: Mostrar posts recientes con cantidad configurable
  • Proyectos y Documentación: Mostrar proyectos y documentación destacados
  • Blurb de Inicio: Controlar ubicación o deshabilitar completamente

Opciones de Posts

Configura características relacionadas con posts en la sección postOptions:

postOptions: {
  postsPerPage: 6,
  readingTime: true,
  wordCount: true,
  tags: true,
  linkedMentions: {
    enabled: true,
    linkedMentionsCompact: false,
  },
  graphView: {
    enabled: true,
    showInSidebar: true,
    maxNodes: 100,
    showOrphanedPosts: true,
  },
  postNavigation: true,
  showPostCardCoverImages: "featured-and-posts",
  postCardAspectRatio: "og",
  customPostCardAspectRatio: "2.5/1",
  comments: {
    enabled: false,
    provider: "giscus",
    // ... otras configuraciones de comentarios
  },
}

Tabla de Contenidos:
Habilitar la tabla de contenidos en la sección raíz tableOfContents es un toggle global para todos los posts. Otros tipos de contenido (páginas, proyectos, etc.) muestran TOC por defecto y pueden ocultarse vía frontmatter.

Menciones Enlazadas:

  • enabled: true - habilitar sección de menciones enlazadas al final de la página
  • linkedMentionsCompact: false - elegir entre vista detallada (predeterminada) o vista compacta

Opciones de Imagen de Portada:
Afecta cómo se muestran las imágenes de portada en las tarjetas de posts: "all", "featured", "home", "posts", "featured-and-posts", o "none".

Sistema de Comentarios

El tema incluye un sistema de comentarios impulsado por Giscus que usa GitHub Discussions. Consulta la guía completa para instrucciones de configuración.

Estructura de Contenido

src/content/
├── posts/                   # Posts del blog
├── pages/                   # Páginas estáticas
├── special/                 # Páginas especiales (inicio, 404, etc.)
├── projects/                # Proyectos destacados
├── docs/                    # Documentación
└── .obsidian/               # Configuración de bóveda de Obsidian

Escribir Contenido

Posts

Crea posts en src/content/posts/. Los títulos H1 están codificados desde el frontmatter, por lo que el contenido debe comenzar con H2.

---
title: "Título del Post"
date: 2026-02-22
description: "Una breve descripción"
tags: ["etiqueta1", "etiqueta2"]
image: "portada.jpg"
imageAlt: "Descripción de la imagen de portada"
draft: false
---

## Comenzar con H2
Contenido del post aquí.

Páginas, Proyectos y Documentación

Todos los tipos de contenido soportan organización basada en carpetas con activos co-ubicados. Usa draft: true para mantener el contenido oculto de producción.

Integración con Obsidian

Usando la Bóveda Incluida

Abre src/content/ en Obsidian para usar las características preconfiguradas de la bóveda:

  • Astro Composer: Crea y gestiona posts fácilmente
  • Tema Minimal: Optimizado para escritura
  • Plugin Git: Commit y sync directamente desde Obsidian

Lee la guía para información más detallada.

Características Clave

Paleta de Comandos

Presiona ctrl+K para búsqueda instantánea, acciones rápidas y cambio de tema.

Enlaces Internos

  • [[Título del Post|Texto Personalizado]] - wikilinks (solo posts)
  • [Título del Post](posts/slug-del-post.md) - enlaces markdown estándar
  • Menciones enlazadas muestran conexiones de posts automáticamente.

Optimización de Imágenes

  • Conversión a WebP para rendimiento
  • Cuadrículas responsivas para múltiples imágenes
  • Sincronización de activos copia activos al directorio público automáticamente.

Despliegue

Compila tu sitio estático con pnpm build. Genera un paquete listo para producción optimizado para tu plataforma elegida.

Solución de Problemas

Verifica las rutas de imágenes, sintaxis de frontmatter y asegúrate de que los posts destino existan para los wikilinks.