En Desarrollo de Software, la comunicación clara es muy importante . El
archivo README.md permite transmitir eficazmente el propósito, la configuración y el uso de
su proyecto.
Tabla de Contenidos
- Qué es un archivo README.md?
- Contenido de archivo Readme
- Marcado abajo
- Por qué deberíamos usar Markdown?
- 1. Direcciones
- 2. Párrafos
- 3. Roturas de línea
- 4. Italic.
- 5. Audaz
- 6. Simultáneamente audaz e Itállic
- 7. Golpeando
- 8. Enlaces
- 9. Imágenes
- 10. Listas desordenadas
- 11. Listas ordenadas
- 12. Bloquetas
- 13. Normas horizontales
- 14. Fragmentos de código
- 15. Bloques de código
- 16. Escaparcial
- 17. Listas dentro de una letrata
- 18. Citas
- GitHub Flavored Markdown
Qué es un archivo README.md?
Un archivo README.md es un componente esencial de muchos proyectos de software, especialmente aquellos alojados en plataformas como GitHub.
Este archivo sirve como el primer punto de contacto para los usuarios y desarrolladores que quieren entender el propósito, la configuración y el uso de un proyecto.
- Un buen README ayuda a que su proyecto se destaque de otros proyectos y debe ser tan bueno como su propio proyecto.
- Es la primera cosa que se puede notar mientras se encuentra con su proyecto, por lo que debe ser bastante breve pero detallado.
- La calidad de una descripción README diferencia un buen proyecto de uno malo.
- Muchas veces README.md se aloja como un sitio web; asegúrese de que su página web se vea tan genial como su proyecto.
Contenido de archivo Readme
Los siguientes son los componentes clave generales de un archivo Readme:
- Incluya su Título de proyecto: Este es el nombre del proyecto. Describe todo el proyecto en pocas palabras y ayuda a la gente a entender el objetivo y el objetivo primario.
- Escribe una descripción: Su descripción es una parte esencial de su proyecto. Una descripción bien mantenida le permite mostrar su trabajo a otros desarrolladores, así como a los empleadores potenciales.
- Cómo usar su proyecto: Proporcione instrucciones y ejemplos para que los usuarios o contribuyentes puedan usar el proyecto. Esto les facilitará para que si se encuentran con un problema, siempre tengan un lugar de referencia.
- Incluya Créditos: Si ha trabajado en el proyecto en equipo, enumere a los miembros de su equipo. También debe incluir sus perfiles de GitHub.
También puede añadir los siguientes detalles en el archivo Readme:
- Cuál fue tu motivación? Por qué construiste este proyecto?
- Qué problema resuelve el proyecto? O, qué hace?
- Por qué usaste tecnologías específicas? Si su proyecto tiene muchas características, enumere aquí.
- Menciona algunos de los desafíos que enfrentaste y características que esperas implementar en el futuro.
- Menciona cualquier cosa que creas que estás orgulloso de construir o tener en ese proyecto
- Qué aprendiste en el proceso?
- Qué sigue para el proyecto?
- Mencione idiomas, marcos, bases de datos, etc.
- Proporcione enlaces de despliegue o cualquier otro enlace requerido.
Antes de sumergirse profundamente en nuestro proyecto, vamos a discutir el lenguaje de marcación.
Markdown: README.md
- Markdown es un lenguaje de marcado ligero que nos permite estilizar un documento de texto digital utilizando técnicas de formato típicas como títulos, énfasis, listas, imágenes y enlaces.
- Los archivos Markdown tienen extensiones .md o .markdown. Podemos convertir Markdown en XHTML o HTML para mostrar bien en un navegador.
- Algunos de los muchos usos de Markdown son:
- Archivos de lectura
- Escribir mensajes en foros de discusión en línea
- Crear texto rico usando un editor de texto plano, correos electrónicos y documentación técnica.
- Los sitios populares que usan Markdown incluyen GitHub, Trello, Reddit, SourceForge y StackExchange.
- Los parsers de Markdown también admiten la caída en bloques de código HTML que se suman a la sintaxis limitada de Markdown si desea lograr un diseño más complejo.
Por qué deberíamos usar Markdown?
- Más fácil para los escritores no tecnológicos producir documentación que pueda ser colaborativa y flexible.
- Fácil de recoger. Tiene una base de convenciones de formato de correo electrónico a la que la mayoría de nosotros estamos expuestos ya.
- Fácilmente legible (en su estado crudo), a diferencia de HTML, que está lleno de etiquetas.
- La plataforma independiente de , lo que significa que puede crear archivos de Markdown en cualquier editor de texto.
- Habilidad reutilizable: Es versátil, y podemos usarlo para tomar notas, crear contenido para un sitio web, o producir documentos listos para imprimir.
Ahora, vamos a discutir elementos del lenguaje de la marcación.
1. Direcciones
- Las direcciones hacen que su texto sea más legible y ayudan a romper los temas.
- En Markdown, las partidas están formateadas con hashs delante de la línea que contiene su título.
- Puede utilizar hasta seis hachís, con el número de hashes correspondiente a un nivel de partida.
Sintaxis:
# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
Texto de formato:
2. Párrafos
- Dividir su información en los párrafos (con una brecha notable entre cada párrafo).
- Los párrafos se dividen por una línea en blanco (una línea que no contiene caracteres) entre párrafos consecutivos.
Sintaxis:
Párrafo 1
Párrafo 2
3. Roturas de línea
- Para dividir su información insertando una nueva línea con menos espacio que usted obtend del formato como párrafo. Se llama rotura de línea.
- Para insertar una ruptura de línea en su archivo Markdown, termine su línea con al menos dos espacios y pulse la devolución. Reproducirá una nueva línea para su texto.
Sintaxis:
Línea 1
Línea 2
4. Italic.
- Envuelva el artículo con una estrella/puntuación en cada lado.
Ejemplo:
*one star on each side*
_This text is also italic_
Texto de formato:
una estrella a cada lado
Este texto también es cursiva
5. Bold
- Envuelva el artículo con dos estrellas/subrayas a cada lado.
Ejemplo:
**two stars on each side**
__This text is also bold__
Texto de formato:
dos estrellas a cada lado
Este texto también es audaz
6. Simultáneamente Bold e Itállic
- Haz tu texto Simultáneamente atrevido y cursiva para darle aún más peso.
- Utilice tres asteriscos (o tres subrayados) para envolver su palabra o frase.
Ejemplo:
***This text is italic and bold.***
___This text is also italic and bold.___
Texto de formato:
Este texto es cursiva y audaz.
Este texto también es cursiva y audaz.
7. Striking through
- Envuelva el elemento en dos tildes a cada lado.
Ejemplo:
~~strikethrough~~
Texto de formato:
8. Enlaces: Links
- Para enlazar a sitios web externos en el contenido de Markdown utilice dos conjuntos de corchetes.
- Envuelva el texto de enlace entre paréntesis [ ], y luego envuelva la URL entre paréntesis ( ): [ ]( ).
Ejemplo:
[Este texto enlaza a gfg](https://write.geeksforgeeks.org/).[This text links to gfg](https://write.geeksforgeeks.org/).
Texto de formato:
Este texto enlaza a gfg
9. Imágenes
- Insertar una imagen en tu archivo Markdown es similar al formato de enlaces.
- Comience el formato de su imagen con una marca de exclamación. A continuación, use corchetes para envolver su imagen alt texto, junto a los paréntesis que contienen la URL de su imagen.
- Asegúrese de que no haya espacios entre la marca de exclamación, los soportes cuadrados o los paréntesis.
- Cuando su archivo Markdown se renderiza a HTML, incrustará la imagen directamente en el texto del cuerpo.
Ejemplo:
Imagen de formato:
10. Listas desordenadas
- Markdown le permite formatear sus listas con varios símbolos diferentes: asteriscos (*), guiones (-), o signos más (o).
- Depende de ti elegir qué símbolo prefieres. El resultado que obtienes es el mismo.
Sintaxis:
-Sólo añade un guión primero y luego escribe un texto.
-Si añadimos otro guión en la siguiente línea, tendrás otro elemento en la lista.
- Si añadimos cuatro espacios o usas una tecla de pestañas (tab key), crearás una lista de sangrados.
- Si necesitas una lista de indenta dentro de una intención, presione una tecla de pestaña (tab key) de nuevo.
A veces quieres puntos de bala:
* Empezar una línea con una estrella
*Profit!
Producto:
11. Listas ordenadas
- Formate las listas ordenadas antes de cada elemento de la lista con un número, seguido de una parada completa y luego un espacio.
- En Markdown, no importa qué números utilice para formatear su lista, ya que la lista siempre será como 1, 2, 3, y así sucesivamente.
Ejemplo:
1. Sólo escribe un número seguir por un punto.
2. Si desea añadir un segundo elemento, simplemente escriba otro número seguido de un punto.
1. Si cometes un error al escribir números, no temas, Markdown te corregirá.
1. Si pulsa una tecla de pestañas o escriba cuatro espacios, obtendrá una lista de sangrado y la numeración comenzará de cero.
1. Si desea insertar una lista numerada en sangrado dentro de una número de novillo existente, sólo presione la tecla de la pestaña de nuevo.
-Si es necesario, también puede añadir una lista desordenada en una número sangrado, pulsando una tecla de pestañas y tecleando adash.
Texto de formato:
12. Bloquetas
- A veces en Markdown, querremos hacer referencia a una fuente externa usando comillas. Se llama bloqueo.
- Usted representa cualquier cuota de bloque por encima de la primera línea de la cita del bloque con un soporte de signo o ángulo mayor que el signo (o).
Ejemplo:
> This is a blockquote
> This is a blockquote
> This is a blockquote
Texto de formato:
13. Normas horizontales
- Una regla horizontal es un pequeño elemento funcional que puede utilizar para dividir visualmente bloques de texto dentro de su archivo Markdown.
- Representamos una regla horizontal por tres o más guiones (--), asteriscos (*), o subrayas (o).
Ejemplo:
---
* * *
___
Texto de formato:
14. Fragmentos de código
- Para hacer referencia a fragmentos de código como ejemplos, formatear fragmentos de código usando backticks que envuelven su código fragmento.
- El primer backtick abre el fragmento, y el segundo backtick "closes".
Ejemplo:
`This is a code snippet.`
Texto de formato:
15. Bloques de código
- Formato de bloques de código es útil cuando usted tiene una parte más grande de código para incluir en su archivo Markdown.
- Formate los bloques de código mediante la sangrenting cada línea de su bloque de código usando una pestaña o cuatro espacios.
- Y si te gusta usar resaltado de sintaxis, incluyendo el idioma.
Ejemplo:
```javascript
if (isAwesome){
return true
}
```
Texto de formato:
16. Escaparcial
- En Markdown, a menudo necesitarás incluir caracteres en tu texto (por ejemplo, un asterisco) que puede ser parte de la sintaxis de Markdown.
- Tienes que escapar de estos personajes, para que tu aplicación Markdown no lea estos personajes como formateado.
- Se escapan de los personajes en Markdown usando una reacción ante el personaje, sin espacio en el medio.
Sintaxis:
\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash symbol
+ plus sign
– minus sign (hyphen)
. dot
! exclamation mark
Texto de formato:
17. Listas dentro de una letrata
- Ulinee el formato de su lista dentro de su formato de blockquote.
- Formatea tu bloque con un signo mayor que el de un espacio seguido de un espacio, incluyendo un letrero antes de cada línea de tu bloque.
- Añada su formato de lista (*) justo después de sus signos más grandes que los signos.
Ejemplo:
> This is a blockquote
> * This is a list item within a blockquote
> * This is a list item within a blockquote
> * This is a list item within a blockquote
Texto de formato:
18. Citas
- Añadir una cita con el carácter de la línea al principio de cada línea.
Ejemplo:
> "I make Jessica Simpson look like a rock scientist."
> —Tara Reid, actress
Texto de formato:
Ya que estamos hablando de readme.md, que está presente en los repositorios de GitHub, le hablamos de GitHub Flavored Markdown.
GitHub Flavored Markdown
- GitHub.com utiliza su versión de la sintaxis Markdown que proporciona un conjunto adicional de características útiles, muchas de las cuales facilitan el trabajo con contenido en GitHub.com.
- Tenga en cuenta que algunas características de GitHub Flavored Markdown sólo están disponibles en las descripciones y comentarios de Issues y Pull Requests.
- Estos incluyen las "menticiones", así como referencias a las cuestiones y solicitudes de tira.
1. Sintaxis destacando
Esto resalta la sintaxis. Ejemplo:
Código de instrumentado:
2. Listas de tareas
- Para crear una lista de tareas
- Si usted incluye una lista de tareas en el primer comentario de un número, obtendrá un indicador de progreso útil en su lista de preguntas.
- También funciona en Pull Requests.
Ejemplo:
- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported
- [x] se requiere la sintaxis de la lista (cualquier lista no ordenada o ordenada soportada)
- [x] este es un artículo completo
- [ ] Este es un artículo incompleto
Texto de formato:
3. Cuadros
- Puedes crear tablas ensamblando una lista de palabras y dividiéndolas con guiones (para la primera fila), y luego separando cada columna con una tubería (o).
Ejemplo:
First Header | Second Header
------------ | -------------
Content from cell 1 | Content from cell 2
Content in the first column | content in the second column
Texto de formato:
4. Nombre de usuario .mentiones
- Escribir un símbolo, seguido de un nombre de usuario, notificará a esa persona que venga y vea el comentario.
- Esto se llama "mención" porque mencionaste al individuo.
- También puedes formar equipos de organización.
5. Enlazado automático para URLs
- Cualquier URL (como http://www.github.com/) se convierte automáticamente en un enlace clicable.
6. Expresiones matemáticas
- También puede añadir fórmula o ecuación de matemáticas con la marcación.
Sintaxis:
$$<<mathematical expression>>$$
Ejemplo:
$$\sqrt{3}+1$$
Producto:
√3+1
Desde ahora usted sabe todo sobre r eadme.md, la próxima vez que haga un repositorio no se olvide de añadir un listo perfecto a su proyecto.
Conclusión
Comprender lo que es y cómo usarlo de manera efectiva es clave para comunicar información importante sobre su proyecto. Ya sea que trabajes en un pequeño guión o en un gran proyecto de código abierto, un README.md bien escrito puede hacer tu trabajo más accesible y más fácil de entender para otros. Al esbozar claramente los objetivos de su proyecto, las instrucciones de configuración y los ejemplos de uso, el archivo README.md asegura que tanto los contribuyentes como los usuarios pueden interactuar con su proyecto de manera efectiva.
Leer mas... https://www.geeksforgeeks.org/what-is-github-readme-file-and-markdown/