Skip to content

Latest commit

 

History

History
176 lines (120 loc) · 10.9 KB

CONTRIBUTING.es.md

File metadata and controls

176 lines (120 loc) · 10.9 KB
Raw

Como comunidad le damos la bienvenida a cualquiera que desee escribir y enviar entradas al blog de Playful Programming. ¡Vamos! En este documento revisaremos los pasos necesarios para crear una nueva publicación, y después enviarla a PP como una pull request o solicitud para incorporar cambios.

[!NOTA] Para un tutorial más general sobre cómo contribuir a un proyecto con GitHub podrías revisar la guía Primeras contribuciones antes de seguir leyendo esta página.

Algunos puntos a tomar en cuenta cuando escribas tu artículo:

  • ¡Sé incluyente! En PP apoyamos a los desarrolladores de todos los niveles de experiencia - no excluyamos a los novatos ni desanimemos a los lectores que desean aprender algo nuevo.
  • Busca proporcionar información relevante y verdadera - ¡Te recomendamos citar las fuentes de tu trabajo!
  • Mantén tu contenido imparcial; es decir, no hagas anuncios de productos o servicios sin ninguna razón.

Si en algún momento te sientes bloqueado o tienes alguna duda que quieras resolver, no dudes en abrir un reporte de problema en GitHub o bien comunícate con nosotros en Discord. ¡Estaremos encantados de ayudarte!

Contenido:

  1. Crear un perfil de autor
  2. Escribir una nueva entrada
  3. Traducir una entrada del blog
  4. Enviar una pull request

Crear un perfil de autor

Antes de crear una nueva entrada, deberás añadir información acerca de ti. Para lograr eso, crea una nueva carpeta en content/ con tu nombre de usuario, y agrega un archivo index.md dentro de ésta; por ejemplo: content/eric/index.md.

Veamos un ejemplo de cómo se vería tu archivo index.md:

---
{
  // "name" será tu nombre a mostrar, como quieras 
  // que se vea en tus entradas
  name: "Eric el Programador",

  // "firstName" y "lastName" son necesarios para
  // las etiquetas de OpenGraph - llena estos campos con los datos
  // que consideres apropiados
  firstName: "Eric",
  lastName: "el Programador",

  // "description" es una biografá corta que se mostrará en tu página de perfil
  description: "Programador Haskell, escritor de fanfictions, un unicornio omnisciente.",

  // Tus usuarios de redes sociales pueden incluir "twitter", "github", "gitlab",
  // "linkedIn", "twitch", "dribbble", "mastodon", "threads", "youtube",
  // y "cohost", además de un "website" ¡Puede ser lo que quieras!
  socials: {
    mastodon: "https://hachyderm.io/@playfulprogramming",
    github: "playfulprogramming",
    website: "https://playfulprogramming.com/"
  },

  // Los "pronombres" son opcionales, pero recomendamos que los incluyas en tu perfil
  pronouns: "they/them",

  // "profileImg" es el valor de una imagen que debe estar en la misma ubicación de este archivo
  // - de preferencia con formato PNG/JPEG y al menos 512px de resolución
  profileImg: "./profile.png",

  // El campo "roles" reflejará cómo vas a contribuir al sitio - si vas a
  // crear una entrada, solo definelo como "author", pero existen más roles
  // ¡Hay roles para programadores y traductores también!
  roles: ["author"]
}
---

¿No quieres mostrar tu foto real en el sitio? ¡Está bien! Tenemos bastantes emoticones de unicornio personalizados que puedes usar como imagen de perfil. ¡Son adorables, ve a verlos! 🤩

Una vez que tengas creado tu perfil, puedes ir al siguiente paso...

Escribir una nueva entrada

Todas las entradas en Playful Programming están dentro de una carpeta: content/{username}/posts/ - estructuramos esto con una subcarpeta para cada entrada, que contiene un archivo markdown llamado index.md. El nombre de la carpeta con la entrada coincidirá con su URL dentro del sitio.

¿Estás familiarizado/a con Markdown?

¿Revisa el documento Markdown Cheatsheet para ver ejemplos de cómo formatear distintos tipos de contenido en este archivo!

Cuando escribas tu entrada, necesitarás incluir metadatos en el frontmatter en la parte superior del archivo:

---
{
  title: "Mi primera entrada en el blog",
  description: "¡Ésta es mi primera entrada en el sitio de Playful Programming!",
  published: '2023-04-11',
  tags: ["meta"],
  license: 'cc-by-4'
}
---

¡Hola! ¡Ésta es mi primera entrada! (TODO: escribir más texto aquí)

Nota: El título que definas en el campo "title" siempre se verá en la parte superior de tu entrada. No necesitas iniciar tu entrada con otro encabezado - de lo contrario ¡tu entrada tendrá dos títulos!

Propiedades opcionales

Existen algunas propiedades extra que podrías incluir en el frontmatter de tu entrada, pero no son necesarias:

  • authors: ["autor1", "autor2"] se puede usar para especificar de forma manual los ID's de los autores de una entrada, esto cuando la publicación tenga más de un autor.
  • edited: "2023-10-21" sirve para especificar la fecha en la hiciste la "última actuaización" de tu entrada en caso de que realices modificaciones.
  • collection: "Mi genial serie de artículos" tratará a un grupo de publicaciones como una serie en caso de que todas tengan la misma cadena collection configurada.
  • order: 0 reordenará las entradas de una colección de acuerdo con el valor que proporciones. Esto no tendrá efecto a menos que la entrada se encuentre dentro de una colección.
  • originalLink: "https://example.com" especifica una URL externa que sirva como fuente para tu entrada. ¡Es importante especificar este valor si estás republicando algo que tengas escrito en otro blog!

Licencias

Proporcionar una licencia ayuda a explicar lo que los lectores pueden hacer con su trabajo - ya sea que puedan usarlo como material para un curso, o reusarlo en otras formas. Visita el sitio de Creative Commons para obtener una visión general de lo que se permite hacer dentro de los distintos tipos de licencias.

Actualmente, estas son las licencias de creative commons que se permiten como valores dentro de la propiedad "license":

También puedes omitir la propiedad "license". En este caso, tu entrada quedará bajo la licencia MPL 2.0 del repositorio.

Enlaces incrustados

Las entradas pueden incristar sus propias etiquetas <iframe> si es necesario - éstas mostrarán una vista previa de "haz clic para ejecutar" y no afectarán el tiempo de carga de la página.

También puedes incrustar algunos servicios de terceros simplemente pegando el enlace en tu entrada, como vídeos de YouTube o de Twitch, publicaciones de Twitter - y cualquier cosas compatible con oembed.com.

Imágenes y vídeos

Si metiste enlaces a imágenes o vídeos necesitarás guardar esos archivos en la misma carpeta que tu entrada y cambiar tu documento markdown para que haga referencia a éstos de forma local:

![Ferris, la adorable mascota crustácea de Rust](./ferris.png)

¡Asegúrate de incluir un texto alt descriptivo! Toma en cuenta qué información agregan esas imágenes a tu entrada, y qué contexto podría ser importante para los lectores con capacidades visuales diferentes.

Los vídeos también se pueden incrustar con la siguiente sintaxis:

<video src="./ios_vs_android.mp4" title="Una comparación de cómo se aplica el espaciado de texto en iOS y Android"></video>

Cuando sea posible, los elementos <video> deberán elegirse por sobre los archivos .gif u otras imágenes animadas en tus entradas. Esto es por motivos de accesibilidad - los vídeos dan más control a los usuarios acerca de cuándo y cómo es que la animación se reproduce.

Traducir una entrada del blog

Si quires agregar una traducción, primero asegúrate de crear un Archivo de datos de autor con el rol de "translator", ¡Así podrás recibir crédito por tu trabajo en el sitio!

Para crear un archivo de traduccción para una entrada, copia su archivo index.md y renómbralo a index.(lenguaje).md, donde (lenguaje) es el lenguaje al que traduces la entrada. Por ejemplo, una traducción al fr (francés) podría ser nombrada index.fr.md. El contenido dentro de este archivo puede ser traducido a su lenguaje respectivo.

Si fuera necesario traducir cualquiera de las inágenes usadas en la entrada, éstas deberán ser nombradas de forma similar - por ejemplo, una traducción de dom_tree.svg deberá ser nombrada dom_tree.fr.svg.

Cualquier enlace a esas imágenes deberá ser actualizado en el archivo index.fr.md de la entrada para que apunte a la imagen traducida.

Para una referencia de los códigos de cada lenguaje, puedes consultar el archivo /content/data/languages.json - si el lenguaje que quieres usar no se encuentra tal vez sea necesario que lo agregues.

Encontrar un código de lenguaje

Cada código de lenguaje dentro de /content/data/languages.json debería estar formado de dos letras en minúscula. Si incluye una región, agrega un guion seguido de otras dos letras en minúscula. Por ejemplo, el código para el francés es fr - para referirse al dialecto del francés que se habla en Canadá, el código será fr-ca.

Por favor usa - en lugar de _ en los formatos ISO de la región del idioma. En lugar de fr_ca, deberá ser fr-ca.

Consulta la lista Wikipedia: List of ISO 639-1 codes para conocer los identificadores que usarás en este formato.

Enviar una Pull Request

Una vez que hayas hecho todos los cambios, crea una Pull Request para agregar tu entrada al sitio.

  • Abre una nueva Pull Request desde tu fork (bifurcación).
  • Revisa que todos tus archivos estén dentro de la Pull Request, y que éstos estén siendo combinados dentro de la rama principal o main.
  • Crea el PR y espera a que quien mantiene el sitio lo revise.
  • Una vez combinada (merged), ¡Tu entrada será visible en el sitio!

¡Nos pondremos en contacto contigo si tenemos alguna duda o retroalimentación cuando revisemos tu entrada!