Pautas para escribir ejemplos del intérprete de comandos
Las siguientes pautas cubren cómo escribir ejemplos de comandos de terminal (shell prompt) para MDN Web Docs.
Qué es una "shell"
Una shell (intérprete de comandos) es un programa que espera a que escribas un comando y luego presiones la tecla Intro. Para indicar qué comandos debes escribir, el contenido de MDN Web Docs los enumera en un bloque de código, similar a los ejemplos de código.
Tal bloque se ve así:
# Esto puede tardar un rato...
git clone https://github.com/mdn/content
cd content
Pautas generales para ejemplos de comandos
Elegir un formato
Las opiniones sobre la indentación, el uso de espacios en blanco y la longitud de las líneas siempre han generado controversia. Las discusiones sobre estos temas son una distracción de la creación y el mantenimiento del contenido.
En MDN Web Docs, usamos Prettier como formateador de código para mantener la consistencia del estilo del código (y para evitar discusiones fuera del tema). Se puede consultar el archivo de configuración para conocer las reglas actuales y leer la documentación de Prettier.
Prettier formatea todo el código y mantiene el estilo consistente. Sin embargo, hay algunas reglas adicionales que se deben seguir.
Escribir bloques de código del intérprete de comandos
Al escribir un bloque de código:
- No incluir un
$o>al comienzo de una instrucción de shell. Confunde más de lo que ayuda y no es útil a la hora de copiar las instrucciones. - Los comentarios comienzan con
#. - Elegir "bash" para indicar el idioma en markdown.
Véase también
Los documentos de desarrollo del lado del servidor de Django muestran una presentación de buenas prácticas de los comandos de la consola de shell.