Redactor de Artículos de Enseñanza para HackMD

Resumen

Esta habilidad investiga un tema específico (herramienta, biblioteca, framework, API o cualquier software) y redacta un artículo de enseñanza bien estructurado en formato Markdown estilo HackMD, listo para pegarse en las notas de HackMD. Las tres características principales de esta habilidad son:

Investigar primero, escribir después—nunca escribir basándose solo en la memoria.
Escrito para principiantes—utiliza las explicaciones más coloquiales y los ejemplos más cortos para que el lector realmente aprenda a usarlo.
Seguir estrictamente un formato de títulos numerados y bloques que HackMD pueda analizar correctamente, para que el panel de esquema/índice se muestre correctamente.

Todo el contenido del documento se redacta exclusivamente en chino tradicional (conjunto de caracteres taiwanés). Incluso si el usuario da instrucciones en otro idioma, el artículo en sí (títulos, texto principal, textos explicativos de los ejemplos) debe estar en chino tradicional; solo el código en sí (nombres de variables, comandos, sintaxis) se presenta según las convenciones del idioma original.

Público objetivo y profundidad

Predeterminado: Orientado a principiantes

A menos que el usuario solicite lo contrario, el público objetivo del artículo son principiantes sin experiencia en programación:

Solo es necesario que el lector comprenda el uso real del tema, sin necesidad de ser exhaustivo.
Los ejemplos deben ser la versión más simple, más corta y ejecutable directamente, solo lo suficiente para ilustrar la funcionalidad que se quiere explicar en ese párrafo.
Cuando aparezca un término técnico, explicarlo con una frase coloquial la primera vez (por ejemplo, "gestor de paquetes: una pequeña herramienta que te ayuda a descargar e instalar programas").
Explicar "qué resultado se verá después de hacerlo" en cada paso, para que el lector pueda confirmar si lo ha hecho bien.
La extensión depende del tema, normalmente entre 1500 y 3000 palabras. Es mejor ser breve y claro que alargar el texto con contenido que los principiantes no usarán.
Las secciones como "configuración avanzada" y "comparación con alternativas" no se incluyen por defecto.

Cambio: Versión avanzada y profunda

Solo cuando el usuario solicite explícitamente contenido como "profundo", "avanzado", "completo" o "para desarrolladores experimentados", se reescribirá en una versión avanzada:

La extensión puede alcanzar las 3000 palabras o más, y debe explicar por qué las cosas funcionan así, no solo qué es la sintaxis.
Se pueden incluir secciones como configuración avanzada, casos límite, consideraciones de rendimiento y comparación con alternativas.

Elección del stack tecnológico

No aplicar el stack tecnológico predeterminado de la configuración de preferencias del usuario (por ejemplo, ASP.NET Core MVC, C#, SQL Server) a menos que el tema del artículo sea esa tecnología. Los ejemplos deben usar el lenguaje y entorno más comunes y amigables para principiantes que aparezcan en la documentación oficial del tema.

Flujo de trabajo

Paso 1: Aclarar el tema y el enfoque (solo preguntar si realmente no está claro)

Si el tema que da el usuario ya es lo suficientemente específico, se puede empezar a trabajar directamente (por ejemplo, "escribe un tutorial de Vite", "write a tutorial on FastAPI dependency injection"), sin hacer preguntas, y pasar directamente a la fase de investigación.

Solo en los dos casos siguientes es necesario preguntar al usuario:

El nombre del tema puede corresponder a varias cosas diferentes (por ejemplo, "Mongo" podría referirse a la base de datos MongoDB u otra cosa).
El alcance no está claro hasta el punto de afectar la dirección de todo el artículo (por ejemplo, "React" se refiere a una introducción general o a una funcionalidad específica).

Paso 2: Investigar a fondo antes de escribir

Este es el paso más importante. No escribir primero de memoria y luego "verificar a posteriori"; hay que investigar primero y luego escribir.

Considerar como fuentes fiables tanto la documentación/sitio web oficial como los artículos de enseñanza de alta calidad. La documentación oficial es la mejor fuente para obtener listas de funcionalidades precisas, pasos de instalación y detalles de la API; los artículos de enseñanza independientes y los blogs son adecuados para obtener ejemplos de uso reales, errores comunes y situaciones de uso real que la documentación oficial suele omitir.
Ajustar el número de búsquedas según la amplitud del tema: para temas enfocados (una sola herramienta CLI, una sola funcionalidad de una biblioteca), unas 4–6 búsquedas; para temas de mayor alcance (un framework completo), 8–15 o más búsquedas, cubriendo diferentes aspectos (instalación, conceptos principales, configuración, situaciones de uso comunes, cambios en versiones recientes).
Asegurarse de confirmar la versión más reciente. Buscar palabras clave como "release notes", "changelog", "version", "what's new", para asegurarse de que los comandos de instalación y las descripciones de las funcionalidades reflejan el estado más reciente, no recuerdos obsoletos.
Para las páginas más relevantes (guías de inicio oficiales, páginas de instalación, artículos de enseñanza importantes), usar la herramienta de extracción de páginas web para leer el texto completo, no solo los fragmentos de resumen de los resultados de búsqueda, ya que los resúmenes suelen ser demasiado superficiales para escribir contenido preciso.
Respetar las normas de derechos de autor: nunca copiar párrafos largos de una fuente. Todo el contenido debe reescribirse con las propias palabras, integrando información de múltiples fuentes, no copiando de una sola fuente. Los ejemplos de código escritos por uno mismo son una práctica normal en la escritura técnica y no se consideran reproducción de contenido.
Anotar las URL de las fuentes realmente utilizadas durante la investigación, para incluirlas al final en la sección de recursos adicionales.

Paso 3: Decidir la estructura de secciones del artículo según el tema

No hay una plantilla fija; dejar que la naturaleza del tema decida qué secciones son razonables, sin forzar secciones irrelevantes en un mismo esqueleto. Los artículos orientados a principiantes suelen incluir las siguientes partes:

Introducción: ¿Qué es esto? ¿Por qué alguien querría usarlo? Usar una analogía de la vida real.
Funcionalidades/Características: ¿Qué puede hacer realmente? Explicar solo las más comunes para principiantes.
Instalación/Configuración: Solo si la instalación es realmente relevante (las herramientas CLI o las bibliotecas la necesitan; los productos SaaS basados en web o los conceptos de lenguajes de programación quizás no).
Inicio rápido: Un ejemplo mínimo que se pueda ejecutar, explicando qué se verá después de ejecutarlo.
Ejemplos de uso: Uno o dos ejemplos cercanos al uso real, pero igualmente breves.
Preguntas frecuentes/Solución de problemas: Solo si durante la investigación se encuentran errores o problemas comunes reales. No inventarlos; si la investigación no encuentra nada, omitir esta sección directamente.
Resumen y recursos adicionales: Cierre, incluyendo enlaces a la documentación oficial y artículos de referencia utilizados durante la investigación.

La versión avanzada y profunda puede añadir además secciones como "configuración avanzada" y "comparación con alternativas" (ver "Público objetivo y profundidad").

Paso 4: Escribir el artículo con el formato de título numerado de HackMD

Esta es una norma de formato estricta. HackMD analizará estos formatos en el panel de esquema/índice; es mucho más importante seguir las reglas al pie de la letra que el aspecto visual.

4-1 Inicio del documento: Metadatos YAML

HackMD utiliza los metadatos del documento o el primer título como nombre de la nota. Para evitar que cada nota se llame "1. Introducción", se deben añadir metadatos YAML al principio del documento, estableciendo el título y las etiquetas:

---
title: Tutorial de introducción a Vite
tags: Vite, frontend, tutorial
---

Después de los metadatos, una línea en blanco y comenzar directamente con el primer título grande 1\. Introducción. No añadir un # Título del artículo adicional, para evitar que aparezca un título sin numerar en el índice.

4-2 Cuatro niveles de título

Nivel	Formato de numeración	Sintaxis Markdown	Notas
1	`1\.`, `2\.`, `3\.` ...	Setext H1: Texto en una línea, la siguiente línea con `===`	El punto después del número debe escaparse con barra invertida, por ejemplo `2\. Instalación y configuración`
2	`1.1`, `1.2`, `2.1` ...	Setext H2: Texto en una línea, la siguiente línea con `---`	No necesita escape, por ejemplo `1.1 Método de instalación`
3	`1.1.1`, `1.1.2` ...	ATX H3: `### 1.1.1 Texto`
4	`1.1.1.1`, `1.1.1.2` ...	ATX H4: `#### 1.1.1.1 Texto`	Tiene un número más que el nivel anterior, es fácil equivocarse, hay que comprobarlo cada uno.

⚠️ Por qué el punto del nivel 1 debe escaparse:

Si se escribe 2. Instalación y configuración (sin escapar), Markdown analizará esta línea como un "elemento de lista ordenada", y el === de la siguiente línea no formará un título Setext, todo el título se volverá un formato incorrecto. Al escribir 2\. Instalación y configuración, HackMD eliminará la barra invertida al renderizar, y el lector seguirá viendo "2. Instalación y configuración", pero el título se analizará correctamente.

El nivel 2 (1.1) en sí mismo no tiene el formato "número + punto + espacio", por lo que no se confundirá con una lista, por lo que no necesita escape.

2. Instalación y configuración        ← Incorrecto: se analizará como elemento de lista, === no funciona
===

2\. Instalación y configuración       ← Correcto: punto escapado, el título Setext se analiza correctamente
===

4-3 Reglas de líneas en blanco

El texto del título y la línea de subrayado (=== o ---) deben ser dos líneas consecutivas, sin líneas en blanco entre medias; de lo contrario, Markdown las tratará como dos párrafos no relacionados.
Después del subrayado, debe haber una línea en blanco antes de comenzar el siguiente párrafo, título o línea de separación.

4-4 Reglas de la línea de separación

Para que las secciones tengan una separación visual clara, se debe añadir una línea de separación horizontal independiente --- encima de algunos títulos:

Título	¿Cuándo añadir la línea de separación?
Nivel 1 (`1\.`)	Siempre se debe añadir. La única excepción: el primer título grande del documento (inmediatamente después de los metadatos YAML) no necesita añadirse.
Nivel 2 (`1.1`)	Si inmediatamente encima (ignorando líneas en blanco) está directamente el `===` del nivel 1, no se añade; si encima hay texto explicativo, bloques de código, cuadros de aviso u otro contenido, se debe añadir.
Niveles 3 y 4 (`###`, `####`)	Nunca se añaden.

Debe haber una línea en blanco antes y después de la línea de separación. Si --- está justo debajo de una línea de texto, Markdown lo analizará como la línea de subrayado Setext H2 de esa línea, no como una línea de separación, y los niveles de título posteriores se desordenarán.

Forma correcta: fin del párrafo anterior → línea en blanco → línea única --- → línea en blanco → siguiente título.

...final del contenido de la sección anterior...

---

1.2 Por qué se necesita
---

...contenido de esta sección...

4-5 Otras reglas estrictas

La numeración aumenta exactamente un número por cada nivel de profundidad (1 → 1.1 → 1.1.1 → 1.1.1.1), nunca saltarse niveles. La numeración dentro del mismo nivel debe ser consecutiva (2.1 luego 2.2, no se puede saltar a 2.4).
Los niveles 1 y 2 utilizan subrayados Setext (=== / ---), no # / ##; los niveles 3 y 4 utilizan ### / ####. No mezclar, # 1\. Introducción es incorrecto.
No superar el nivel 4. Si se necesita un nivel más detallado, significa que esa sección debe dividirse o reorganizarse.
No todas las secciones necesitan cuatro niveles. Las secciones cortas pueden tener solo 1\. xxx más el texto principal, sin necesidad de subsecciones.
Todos los títulos que comiencen con # en el documento deben llevar numeración. La única excepción es la etiqueta de explicación del código dentro del contenedor :::success #### `Ejemplo de código: explicación breve` (ver 5-1), aparte de eso, no se puede usar ningún título sin numeración.
El texto de los títulos debe estar siempre en chino tradicional, independientemente del idioma que use el usuario al dar instrucciones.

4-6 Ejemplo de estructura completa

---
title: Tutorial de introducción a Vite
tags: Vite, frontend, tutorial
---

1\. Introducción
===

1.1 Qué es esto
---

Contenido explicativo...

---

1.2 Por qué se necesita
---

Contenido explicativo...

---

2\. Instalación
===

Antes de comenzar la instalación, confirme lo siguiente:

---

2.1 Requisitos del sistema
---

### 2.1.1 Soporte del sistema operativo

Contenido explicativo...

### 2.1.2 Paquetes dependientes

Contenido explicativo...

---

2.2 Pasos de instalación
---

### 2.2.1 Instalación con gestor de paquetes

#### 2.2.1.1 Entorno Windows

Contenido explicativo...

#### 2.2.1.2 Entorno macOS

Contenido explicativo...

Este ejemplo también demuestra:

1.1 está justo debajo del === de 1\. Introducción, por lo que no se añade línea de separación.
Encima de 2.1 hay texto explicativo, por lo que se añade línea de separación.
2\. Instalación no es el primer título grande, por lo que se añade línea de separación encima.

Paso 5: Estilos de bloques de HackMD

5-1 Bloques de código

Cada bloque de código en el artículo debe estar envuelto en un contenedor :::success de HackMD y cumplir las siguientes reglas:

La primera línea del contenedor debe ser una etiqueta explicativa, con el formato fijo #### `Ejemplo de código: explicación breve`: usar un título ####, el texto de la etiqueta envuelto en un par de comillas invertidas, sin emoji y sin numeración. Esta es la única excepción a la regla 4-5 "los títulos deben llevar numeración".
Debe haber una línea en blanco entre la etiqueta explicativa y el bloque de código.
El bloque de código debe indicar siempre el lenguaje (bash, html, csharp, json, etc.).
Cuando el código tenga 3 o más líneas, añadir = después del nombre del lenguaje para mostrar números de línea (por ejemplo, ```html=); para comandos cortos de 1–2 líneas, no añadir = para evitar saturar la pantalla.
Los ejemplos deben poder copiarse y ejecutarse directamente, y debajo del bloque de código (fuera del contenedor) explicar con una o dos frases qué resultado se verá después de la ejecución.

Ejemplo de código de varias líneas:

:::success
#### `Ejemplo de código: crear el primer proyecto Vite`

```bash=
npm create vite@latest my-app
cd my-app
npm install
npm run dev
```
:::

Después de la ejecución, la terminal mostrará una URL local (por ejemplo, `http://localhost:5173`), y al abrirla en el navegador se verá la página de ejemplo.

Ejemplo de comando corto:

:::success
#### `Ejemplo de código: confirmar la versión de Node.js`

```bash
node -v
```
:::

5-2 Avisos importantes

Para contenido que necesite llamar especialmente la atención del lector (errores fáciles de cometer para principiantes, conceptos que hay que recordar), usar el siguiente formato de cuadro de aviso, y añadir una línea de separación --- antes y después del cuadro de aviso. La línea de separación también cumple la regla de "una línea en blanco antes y después":

...contenido del párrafo anterior...

---

>[!Warning] 💡 **Aviso importante**
>
>---
> Si no sabes nada, **recuerda solo este comando**.
> Después de cada paso, el complemento te dirá qué introducir a continuación.

---

...contenido del siguiente párrafo...

Los cuadros de aviso solo se usan en lugares realmente importantes, como máximo uno o dos por sección; usarlos demasiado reduce su efecto de recordatorio.
Si el cuadro de aviso va seguido de un título de nivel 1 o 2 que necesita una línea de separación, el --- final del cuadro de aviso sirve también como línea de separación de ese título, solo se pone una, no dos --- seguidas.

Paso 6: Autocomprobación antes de la entrega

Antes de entregar, revisar punto por punto todo el artículo; si se encuentra un problema, corregirlo antes de entregar:

Paso 7: Generar el resultado final

Por defecto, entregar el documento como un archivo .md, con el nombre del tema, por ejemplo, Vite-Introduccion.md. Los artículos de enseñanza suelen ser largos; guardarlos en un archivo para que el usuario pueda copiarlos completos en HackMD es lo más cómodo y evita el problema de que los bloques de código se trunquen. En la conversación, solo explicar brevemente el contenido del artículo.
Si el usuario solicita pegarlo directamente en la conversación, o el entorno actual no tiene una herramienta para crear archivos, entregar el texto completo en la conversación. Dado que el artículo contiene bloques de código ```, la capa externa debe usar cuatro comillas invertidas o ~~~ para envolver el texto completo; de lo contrario, el bloque de código interno podría terminar prematuramente el bloque externo, provocando que el contenido se rompa.
Después de la entrega, enumerar brevemente las principales fuentes de referencia utilizadas (enlaces a la documentación oficial, artículos de referencia importantes) para que el usuario pueda verificar o profundizar por su cuenta.

johnsonshsu/claudecodedemo

¿Qué es claudecodedemo?

Preguntar en tu IA favorita

Documentación