Proyecto Astro Starlight

Instalación y configuración inicial

Para crear un nuevo proyecto Astro Starlight utilizamos el comando de creación oficial:

# Crear nuevo proyecto Astro con Starlight
npm create astro@latest -- --template starlight
# Seguir las instrucciones del asistente
# Nombre del proyecto: neodigital-wiki

# Instalar dependencias adicionales
cd neodigital-wiki
npm install @astrojs/sitemap sharp

Configuración del proyecto

Para adaptar el proyecto a nuestras necesidades, editamos el archivo astro.config.mjs con la siguiente configuración:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  site: 'https://wiki.neodigital.mx',
  build: {
    format: 'directory',
  },
  integrations: [
    starlight({
      title: 'NeoDigital Wiki',
      defaultLocale: 'root',
      locales: {
        root: {
          label: 'Español',
          lang: 'es-ES',
        },
      },
      social: {
        github: 'https://github.com/NeoDigital-MX',
      },
      sidebar: [
        {
          label: 'Inicio',
          items: [
            { label: 'Portada', link: '/' },
            { label: 'Introducción', link: '/introduction' },
          ],
        },
      ],
      customCss: ['./src/styles/custom.css'],
    }),
    sitemap(),
  ],
});

Esta configuración incluye:

URL del sitio para SEO
Formato de directorio para URLs limpias
Configuración del idioma en español
Enlaces a redes sociales
Estructura inicial de la barra lateral
Soporte para CSS personalizado
Generación automática de sitemap

Estructura de directorios

Astro Starlight sigue una estructura de directorios específica que facilita la organización del contenido. La más importante es la carpeta src/content/docs/, donde se alojan todas las páginas de documentación:

neodigital-wiki/
├── public/              # Archivos estáticos (imágenes, favicon, etc.)
├── src/
│   ├── assets/          # Recursos como imágenes que serán procesados por Astro
│   │   └── making-of/  # Directorio para esta sección (ruta: /making-of/*)
│   └── styles/          # Archivos CSS para personalización
│       └── custom.css   # Estilos personalizados para el sitio
├── astro.config.mjs     # Configuración principal de Astro
├── package.json         # Dependencias y scripts
└── tsconfig.json        # Configuración de TypeScript

Formato de documentos

Cada documento Markdown en src/content/docs/ se convierte automáticamente en una página del wiki, utilizando la siguiente estructura:

---
title: Título de la página
description: Descripción de la página para SEO y metadatos
---

# Contenido principal

El contenido de la página escrito en Markdown...

Organización del contenido

El contenido se puede organizar en subdirectorios para una mejor estructura. Ejemplo:

src/content/docs/
├── guias/           # Subdirectorio para guías
│   ├── instalacion.md
│   └── configuracion.md
└── referencia/      # Subdirectorio para documentación de referencia
    ├── api.md
    └── comandos.md

Estos subdirectorios se reflejan en las URLs, por ejemplo, /guias/instalacion.

Siguientes pasos

Una vez configurado el proyecto, continuamos con la dockerización para prepararlo para su despliegue en producción.