Un archivo LÉAME es una guía esencial que brinda a otros desarrolladores una descripción detallada de su proyecto de GitHub.
Quizás se pregunte por qué alguien debería dedicar tiempo a escribir un archivo README. Bueno, aquí hay algunas razones para ayudar a convencerte de que es una buena idea:
- Un buen README ayuda a que su proyecto se destaque de otros proyectos y debería ser tan bueno como su propio proyecto.
- Es lo primero que debe notar al encontrarse con su proyecto, por lo que debe ser bastante breve pero detallado.
- La calidad de una descripción README diferencia un buen proyecto de los malos.
- Muchas veces, README.md se aloja como un sitio web; ¡asegúrate de que tu página web se vea tan genial como tu proyecto!
Contenido del archivo Léame:
Los siguientes son los componentes clave generales de un archivo Léame:
- Incluya el título de su proyecto: este es el nombre del proyecto. Describe todo el proyecto en pocas palabras y ayuda a las personas a comprender el objetivo principal y el objetivo.
- Escribe una descripción: tu descripción es una parte esencial de tu proyecto. Una descripción bien mantenida le permite mostrar su trabajo a otros desarrolladores, así como a posibles empleadores.
- Cómo usar su proyecto: proporcione instrucciones y ejemplos para que los usuarios o colaboradores puedan usar el proyecto. Esto les facilitará que, si se encuentran con algún problema, siempre tengan un lugar de referencia.
- Incluya créditos: si ha trabajado en el proyecto en equipo, enumere los miembros de su equipo. También debe incluir sus perfiles de GitHub.
También puede agregar los siguientes detalles en el archivo Léame:
- ¿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, enumérelas aquí.
- Mencione algunos de los desafíos que enfrentó y las funciones que espera implementar en el futuro.
- Mencione cualquier cosa que crea que está orgulloso de construir o tener en ese proyecto
- ¿Qué aprendiste en el proceso?
- ¿Qué sigue para el proyecto?
- Mencionar lenguajes, frameworks, bases de datos, etc.
- Proporcione enlaces de implementación o cualquier otro enlace requerido
Antes de profundizar en el archivo Léame de nuestro proyecto, analicemos el lenguaje de rebajas.
Reducción
- Markdown es un lenguaje de marcado ligero que nos permite diseñar un documento de texto digital utilizando técnicas de formato típicas como encabezados, énfasis, listas, imágenes y enlaces.
- Los archivos Markdown tienen extensiones .md o .markdown . Podemos convertir Markdown en XHTML o HTML para que se muestre bien en un navegador.
- Algunos de los muchos usos de Markdown son:
- archivos Léame
- Escribir mensajes en foros de discusión en línea
- Creación de texto enriquecido mediante un editor de texto sin formato, correos electrónicos y documentación técnica.
- Los sitios populares que usan Markdown incluyen GitHub, Trello, Reddit, SourceForge y StackExchange.
- Los analizadores de Markdown también admiten colocar 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 técnicos producir documentación que puede ser colaborativa y flexible.
- Fácil de aprender : tiene una base de convenciones de formato de correo electrónico a las que la mayoría de nosotros ya estamos expuestos.
- Fácilmente legible (en su estado original), a diferencia de HTML, que está lleno de etiquetas.
- Independiente de la plataforma , lo que significa que puede crear archivos Markdown en cualquier editor de texto.
- Habilidad reutilizable : es versátil y podemos usarla para tomar notas, crear contenido para un sitio web o producir documentos listos para imprimir.
Ahora, analicemos los elementos del lenguaje de rebajas.
1. Títulos:
- Los encabezados hacen que su texto sea más legible y ayudan a dividir los temas.
- En Markdown, los encabezados se formatean con almohadillas (#) delante de la línea que contiene su encabezado.
- Puede usar hasta seis hashes, con el número de hashes correspondiente a un nivel de encabezado.
Sintaxis:
# Heading level 1 ## Heading level 2 ### Heading level 3 #### Heading level 4 ##### Heading level 5 ###### Heading level 6
Texto formateado:
2. Párrafos:
- Para dividir su información en párrafos (con un espacio 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:
Paragraph 1 Paragraph 2
3. Saltos de línea:
- Para dividir su información insertando una nueva línea con menos espacio del que obtendría al formatear como un párrafo. Se llama salto de línea.
- Para insertar un salto de línea en su archivo Markdown, termine su línea con al menos dos espacios y presione regresar. Representará una nueva línea para su texto.
Sintaxis:
Line 1 Line 2
4. Cursiva:
- Envuelva el artículo con una estrella/guion bajo en cada lado.
Ejemplo:
*one star on each side* _This text is also italic_
Texto formateado:
one star on each side This text is also italic
5. Negrita:
- Envuelve el artículo con dos estrellas o guiones bajos en cada lado.
Ejemplo:
**two stars on each side** __This text is also bold__
Texto formateado:
two stars on each side This text is also bold
6. Negrita y cursiva simultáneamente:
- ¡Haga su texto simultáneamente en negrita y cursiva para darle aún más peso!
- Use tres asteriscos (o tres guiones bajos) para envolver su palabra o frase.
Ejemplo:
***This text is italic and bold.*** ___This text is also italic and bold.___
Texto formateado:
This text is italic and bold. This text is also italic and bold.
7. Tachar:
- Envuelve el artículo en dos tildes a cada lado.
Ejemplo:
~~strikethrough~~
Texto formateado:
8. Enlaces:
- Para vincular a sitios web externos en el contenido de Markdown, use dos juegos de corchetes.
- Encierre el texto del vínculo entre corchetes [ ] y luego encierre la URL entre paréntesis ( ): [ ]().
Ejemplo:
[This text links to gfg](https://write.geeksforgeeks.org/).
Texto formateado:
This text links to gfg
9. Imágenes:
- Insertar una imagen en su archivo Markdown es similar al formato de los enlaces.
- Comience a formatear su imagen con un signo de exclamación. A continuación, use corchetes para envolver el texto alternativo de su imagen, junto a los paréntesis que contienen la URL de su imagen.
- Asegúrese de que no haya espacios entre el signo de exclamación, los corchetes o los paréntesis.
- Cuando su archivo Markdown se procesa en HTML, incrustará la imagen directamente en el cuerpo del texto.
Ejemplo:
![image](https://media.geeksforgeeks.org/wp-content/cdn-uploads/20210914130327/100-Days-of-Code-with-GFG-Get-Committed-to-a-Challenge.png)
Imagen formateada:
10. Listas desordenadas:
- Markdown le permite formatear sus listas con varios símbolos diferentes: asteriscos (*), guiones (-) o signos más (+).
- Depende de usted elegir qué símbolo prefiere. El resultado que obtienes es el mismo.
Sintaxis:
-Just add a dash first and then write a text. -If you add another dash in the following line, you will have another item in the list. - If you add four spaces or use a tab key, you will create an indented list. - If you need sert an indenta list within an intended one, just press a tab key again. Sometimes you want bullet points: *Start a line with a star *Profit!
Producción:
11. Listas ordenadas:
- Dé formato a sus listas ordenadas precediendo cada elemento de la lista con un número, seguido de un punto y luego un espacio.
- En Markdown, no importa qué números uses para dar formato a tu lista, ya que la lista siempre se representará como 1, 2, 3, etc.
Ejemplo:
1. Just type a number follow by a dot. 2. If you want to add a second item, just type in another number followed by a dot. 1. If you make a mistake when typing numbers, fear not, Markdown will correct for you. 1. If you press a tab key or type four spaces, you will get an indented list and the numbering will start from scratch. 1. If you want to insert an indented numbered list within an existing indented numbered one, just press the tab key again. -If need be, you can also add an indented unordered list within an indented numbered one, by pressing a tab key and typing adash.
Texto formateado:
12. Citas en bloque:
- A veces, en Markdown, querremos hacer referencia a una fuente externa usando comillas. Se llama cita en bloque.
- Cualquier cita en bloque se representa precediendo la primera línea de la cita en bloque con un signo de mayor que o un corchete angular (>).
Ejemplo:
> This is a blockquote > This is a blockquote > This is a blockquote
Texto formateado:
13. Reglas horizontales:
- Una regla horizontal es un pequeño elemento funcional que puede usar para dividir visualmente bloques de texto dentro de su archivo Markdown.
- Representamos una regla horizontal mediante tres o más guiones (-), asteriscos (*) o guiones bajos (_).
Ejemplo:
--- * * * ___
Texto formateado:
14. Fragmentos de código:
- Para hacer referencia a fragmentos de código como ejemplos, formatee fragmentos de código usando acentos graves ` que envuelven su fragmento de código.
- El primer acento grave «abre» el fragmento y el segundo acento grave lo «cierra».
Ejemplo:
`This is a code snippet.`
Texto formateado:
15. Bloques de código:
- El formateo de bloques de código es útil cuando tiene una gran cantidad de código para incluir en su archivo Markdown.
- Formatee sus bloques de código sangrando cada línea de su bloque de código usando una tabulación o cuatro espacios.
- Y si desea utilizar el resaltado de sintaxis, incluido el idioma.
Ejemplo:
```javascript if (isAwesome){ return true } ```
Texto formateado:
16. Escapar:
- En Markdown, a menudo necesitará incluir caracteres en su texto (por ejemplo, un asterisco) que pueden ser parte de la sintaxis de Markdown.
- Debe «escapar» estos caracteres, para que su aplicación Markdown no lea estos caracteres como formato.
- Escapas de los caracteres en Markdown usando una barra invertida antes del carácter , sin espacios intermedios.
Sintaxis:
\ backslash ` backtick * asterisk _ underscore {} curly braces [] square brackets () parentheses # hash symbol + plus sign – minus sign (hyphen) . dot ! exclamation mark
Texto formateado:
17. Listas dentro de una cita en bloque:
- Anide el formato de su lista dentro de su formato de cita en bloque.
- Formatee su cita en bloque usando un signo de mayor que (>) seguido de un espacio, incluido un signo antes de cada línea de su cita en bloque.
- Agrega el formato de tu lista (*) justo después de los signos de mayor que.
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 formateado:
18. Citas:
- Agregue una cita con el carácter > al comienzo de cada línea.
Ejemplo:
> "I make Jessica Simpson look like a rock scientist." > —Tara Reid, actress
Texto formateado:
Ya que estamos discutiendo readme.md , que está presente en los repositorios de GitHub, ¡hablemos de Markdown con sabor a GitHub!
Rebajas con sabor a GitHub
- GitHub.com usa su versión de la sintaxis Markdown que proporciona un conjunto adicional de funciones útiles, muchas de las cuales facilitan el trabajo con contenido en GitHub.com.
- Tenga en cuenta que algunas funciones de GitHub Flavored Markdown solo están disponibles en las descripciones y comentarios de problemas y requests de extracción.
- Estos incluyen @menciones, así como referencias a problemas y requests de extracción.
1. Resaltado de sintaxis:
- Resalta la sintaxis.
Ejemplo:
Código formateado:
2. Listas de tareas:
- Para crear una lista de tareas
- Si incluye una lista de tareas en el primer comentario de un problema, obtendrá un útil indicador de progreso en su lista de problemas.
- También funciona en requests de extracción.
Ejemplo:
- [x] @mentions, #refs, [links](), **formatting**, and <del>tags</del> supported - [x] list syntax required (any unordered or ordered list supported) - [x] this is a complete item - [ ] this is an incomplete item
Texto formateado:
3. Mesas:
- Puede crear tablas reuniendo una lista de palabras y dividiéndolas con guiones – (para la primera fila), y luego separando cada columna con un tubo (|).
Ejemplo:
First Header | Second Header ------------ | ------------- Content from cell 1 | Content from cell 2 Content in the first column | content in the second column
Texto formateado:
4. Nombre de usuario @menciones:
- Escribir un símbolo @, seguido de un nombre de usuario, notificará a esa persona para que venga y vea el comentario.
- Esto se llama «@mención» porque está mencionando a la persona.
- También puede @mencionar equipos dentro de una organización.
5. Enlace automático para URL:
- Cualquier URL (como http://www.github.com/) se convierte automáticamente en un enlace en el que se puede hacer clic.
6. Expresiones matemáticas:
- También puede agregar fórmulas matemáticas o ecuaciones con descuento.
Sintaxis:
$$<<mathematical expression>>$$
Ejemplo:
$$\sqrt{3}+1$$
Producción:
√3+1
Ya que ahora sabe todo acerca de readme.md, la próxima vez que cree un repositorio, ¡no olvide agregar un readme perfecto a su proyecto!
Publicación traducida automáticamente
Artículo escrito por sushreesatarupass y traducido por Barcelona Geeks. The original can be accessed here. Licence: CCBY-SA