Guías de escritura

Creación de un archivo de guía

Para empezar a escribir una guía, necesitas crear un archivo con la extensión .mdx. Necesitas crear este archivo dentro del directorio /content/docs/en a partir de ahí, dependerá de la sección en la que quieras crear la guía, por lo que podrás decidir en qué carpeta debes colocarla.

Supongamos que quiero crear una guía de fundamentos de Java, la colocaría en /content/docs/en/guides/java-basics. Tendrás que investigar un poco para decidir dónde quieres colocarla.

Info

Si ya existe una guía en la sección sobre la que quieres escribir, puedes pulsar simplemente el botón "Editar en GitHub" en nuestro sitio web y este te llevará a la carpeta correspondiente; a partir de ahí, puedes escribir en esa misma carpeta para que tu guía aparezca en la misma sección.

Frontmatter

El Frontmatter es el metadato de tu guía; indica a nuestro sitio web cómo debe mostrarse la guía. Esto debe ir en la parte superior del archivo, que empieza con --- y termina con ---.

Aquí un ejemplo:

---
title: "Java Basics"
description: "Learn the basics of Java programming."
authors:
    - name: "Your Name"
      url: "https://yourwebsite.com"
icon: YourIcon 
---

Como puedes ver, es bastante autoexplicativo, solo tienes que rellenar los detalles correspondientes a tu guía específica. Si no tienes una URL que quieras enlazar, simplemente no escribas esa línea completa. Adicionalmente, la sección de autores es opcional, así que si no quieres añadirla, puedes omitirla, aunque te animamos a hacerlo y darte crédito.

La identación en el frontmatter es importante, así que asegúrate de mantenerla consistente con el ejemplo.

Estructura del contenido

Debes estructurar el contenido de tu guía de forma clara y organizada. Aquí tienes algunos consejos para hacerlo:

Introducción: Empieza con una visión general del tema y lo que el lector puede esperar aprender.
Prerequisitos: Enumera los requisitos previos o conocimientos necesarios que el lector debería tener antes de empezar la guía.
Instrucciones Paso-a-Paso: Divide el contenido en pasos claros y accionables. Usa encabezados y sub encabezados para organizar la información.
Ejemplos de código: Incluye fragmentos de código para ilustrar los puntos clave. Asegúrate de explicar cada ejemplo a fondo.
Conclusión: Resume los puntos principales y anima al lector a profundizar más o a poner en práctica lo que aprendió.

Si estás escribiendo una sección muy grande, deberías dividirla en varias páginas para que al lector le resulte más fácil asimilar la información. ¡Nadie quiere leerse un muro enorme de texto de una sola vez!

Cuando escribimos guías, también deberíamos pensar en cómo lo asumirá la gente, muchas personas prefieren ojear el contenido en lugar de leerlo en detalle. Por eso es mejor dividir la información en varias páginas, de modo que al lector le parezca una cantidad menor de contenido. Además, considera usar viñetas, listas enumeradas y otras técnicas de formato para que el contenido sea más fácil de escanear.

Formato

Usamos Markdown para formatear nuestras guías. Aquí tienes algunos puntos clave a tener en cuenta:

Usa encabezados (#, ##, ###) para organizar tu contenido.
Usa viñetas y listas enumeradas para mayor claridad.
Use code blocks (```) for code snippets.
Usa links de referencia a otras guías o recursos externos.

Este es el mismo tipo de formato que verás en la mayoría de sitios web de documentación y también en plataformas de redes sociales como Discord.

Links

Everyone knows what a link is. However, there is a difference between linking to an external resource and linking to an internal one.

In general, in Markdown they are written like this: [Your Text](Your link)

External

Nothing to explain, just https://example.com.

Internal

You cannot use regular links here. Let's say your link to another guide is https://hytalemodding.dev/en/docs/quick-start. You can't write it like that because you are not only referring to the page but also to the language, which is not correct. Instead, type ./quick-start which is correct and links to the page in the user's language.

Accessing files

Current Folder: ./
Folder above: ../ as many times as this folder is higher in the hierarchy.

Icons

If you want to add an icon for your page then you should use Lucide.

Go to the site and find an icon you like.
Once you have selected an icon, click on it, then click "See in action"
Next, click on "React" which we are using. You will only need the text in the curly brackets on the first line.
Next, simply paste icon: YourIcon into Frontmatter.

Callout

También puedes usar un Callout para resaltar información importante o consejos. Usa la siguiente sintaxis:

<Callout>
    Esto es un mensaje Callout.
</Callout>

Info

Esto es un mensaje Callout

Puedes cambiar el color del callout añadiendo un atributo type Por ejemplo:

<Callout type="info">
    Esto es información del callout.
</Callout>

Tipos disponibles: info, warning, error, y success

Difficulty levels

These are types of callouts, they are optional, they show how complex your page can be. There are 3 main levels of complexity.

Level: Beginner

Use lvl_beginner. This page contains information for those who are starting out with modding.

Level: Intermediate

Use lvl_intermediate. This page contains information for those who want to deepen their knowledge.

Level: Advanced

Use lvl_advanced. This page contains information for those who already know how to make quality mods, and contains something additional.

Their usage is the same as in callout, but we would advise not to change the title. Inside, you write why your page is classified as this level and what the user should know.

Conclusión

¡Eso es todo! Ahora eres un master escribiendo guías. Solo recuerda: no hace falta que tu inglés sea perfecto, escribe la guía tal y como le explicarías el tema a alguien y no dudes en pedir feedback o ayuda si lo necesitas.

¡Feliz escritura!

Guías de escritura

On this page