Manual interactivo para principiantes

De una carpeta a un sitio web con GitHub Pages

Aprenda a crear un repositorio, organizar varios proyectos, subir un archivo HTML y obtener una liga pública para compartir con estudiantes, lectores o clientes.

Progreso del manual0 de 10 pasos completados

Antes de comenzar

No necesita instalar programas ni utilizar la Terminal. Este procedimiento se realiza desde el navegador con la interfaz web de GitHub.

RepositorioCarpeta principal en línea donde se almacenan archivos e historial.
CommitRegistro de cambio; funciona como una fotografía del proyecto.
Rama mainVersión principal del proyecto.
GitHub PagesServicio que convierte archivos estáticos en un sitio web público.
HACK: piense en GitHub como un archivador con historial. Cada carpeta contiene un proyecto y cada commit registra una mejora.

1Crear una cuenta o iniciar sesión

Entre a GitHub y acceda con su cuenta. Para publicar con Pages, conviene que el repositorio sea público.

2Crear el repositorio

  1. Abra el menú + y seleccione New repository.
  2. Escriba un nombre corto, en minúsculas y sin espacios.
  3. Seleccione Public.
  4. Active Add a README file.
  5. Presione Create repository.

Ejemplo de nombre

magia-tools

Descripción de ejemplo

Biblioteca de herramientas interactivas sobre IA, negocios, finanzas, marketing e innovación.
Evite: espacios, acentos o caracteres especiales. Use guiones: madurez-ia.

3Diseñar la estructura

Un repositorio general puede contener una portada y varias herramientas. Cada herramienta debe vivir dentro de su propia carpeta.

magia-tools/ ├── index.html ├── README.md ├── criptoagilidad/ │ └── index.html ├── madurez-ia/ │ └── index.html ├── preparacion-datos/ │ └── index.html └── assets/ ├── images/ ├── css/ └── js/
HACK: cada carpeta funciona como una miniweb. Si contiene index.html, GitHub Pages abrirá esa herramienta al entrar a la carpeta.

4Crear una carpeta

GitHub no conserva carpetas vacías. Seleccione Add file → Create new file y escriba:

criptoagilidad/.gitkeep

Agregue cualquier texto breve y confirme el cambio.

Create criptoagilidad folder

5Preparar el archivo principal

El archivo que desea publicar debe llamarse exactamente:

index.html
Importante: Index.html o inicio.html no son equivalentes.

Ejemplo mínimo

<!DOCTYPE html> <html lang="es"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Mi primera herramienta</title> </head> <body> <h1>Mi proyecto ya está en línea</h1> </body> </html>

6Subir el proyecto

  1. Entre en la carpeta correcta.
  2. Seleccione Add file → Upload files.
  3. Arrastre index.html y los archivos adicionales.
  4. Escriba un mensaje de commit.
  5. Presione Commit changes.

Mensajes de commit útiles

Add interactive crypto-agility test
Update landing page with new diagnostic
HACK: empiece el commit con un verbo: Add, Update, Fix, Create, Remove.

7Eliminar .gitkeep

Cuando la carpeta ya contiene index.html, abra .gitkeep, seleccione Delete file y confirme.

Remove temporary file

8Crear la portada general

En la raíz del repositorio debe existir otro index.html. Esa será la portada que enlaza a todas las herramientas.

magia-tools/ ├── index.html ← portada general ├── README.md └── criptoagilidad/ └── index.html ← test específico

Enlace relativo

<a href="./criptoagilidad/">Abrir prueba</a>
HACK: use enlaces relativos como ./criptoagilidad/; seguirán funcionando aunque cambie el dominio.

9Activar GitHub Pages

  1. Abra Settings.
  2. Seleccione Pages.
  3. En Build and deployment, elija Deploy from a branch.
  4. Seleccione main.
  5. Seleccione / (root).
  6. Presione Save.
Resultado esperado: GitHub mostrará la URL pública del sitio.
https://eldamorales.github.io/magia-tools/
https://eldamorales.github.io/magia-tools/criptoagilidad/

10Probar y compartir

  1. Abra la liga en una ventana privada.
  2. Pruebe botones y formularios.
  3. Revise el sitio desde el teléfono.
  4. Compruebe enlaces internos.
  5. Comparta la URL pública, no el archivo local.
No comparta: una ruta file:///Users/...; solo funciona en su computadora.

Ejemplo: agregar un segundo test

  1. Cree madurez-ia/.gitkeep.
  2. Suba el nuevo test como index.html.
  3. Elimine .gitkeep.
  4. Agregue una tarjeta en la portada general.
<a href="./madurez-ia/">Realizar diagnóstico de madurez en IA</a>
https://eldamorales.github.io/magia-tools/madurez-ia/

Errores frecuentes

Error 404
  • Confirme que el archivo se llama index.html.
  • Revise Pages: main + / (root).
  • Espere unos minutos y recargue en incógnito.
La carpeta aparece como archivo

Elimine el archivo incorrecto y vuelva a crearla con:

nombre-carpeta/.gitkeep
Las imágenes no cargan

Use rutas relativas y respete mayúsculas y minúsculas.

<img src="./assets/images/portada.png" alt="Portada">
Funciona localmente, pero no en Pages

Revise que no dependa de rutas locales, servidores Python, bases de datos o API keys. GitHub Pages publica sitios estáticos.

¿Puedo subir contraseñas?

No. Nunca publique contraseñas, tokens o claves privadas.

Miniquiz

¿Cómo debe llamarse el archivo principal?
¿Qué configuración publica desde la raíz?
¿Qué ruta conviene usar?

Checklist final