Trabajando con README.md en github.com

Question

No estoy muy familiarizado con el lenguaje de marcado liviano utilizado por github al actualizar archivos README.

¿Dónde están los recursos que puedo leer sobre cómo escribir la sintaxis de marcado adecuada para los archivos README/wiki de mi biblioteca de código abierto?

¿Y hay alguna herramienta que pueda "revisar mis documentos localmente en mi navegador" antes de enviar el archivo README actualizado a mi repositorio github?

Answer 1

El marcado en cuestión se llama casualmente Markdown, creado por John Gruber, autor del Daring Fireball blog. La fuente original de Markdown se puede encontrar en Daring Fireball - Markdown.

Hay muchos dialectos Markdown, la documentación para Github se puede encontrar en la página Github Flavored Markdown.

buena propina de esa página:

prensa M en cualquier página de Github con un editor de rebajas para revelar la cheatsheet.

También puede usar la página Github Markdown Live Preview para probar sus documentos Markdown.

Actualización 2012-11-08: Se están realizando esfuerzos para estandarizar la sintaxis de Markdown. Ver The Future of Markdown - Jeff Atwood, Coding Horror y W3C Markdown Community Group.

Actualización 2014-09-09: CommonMark Se ha lanzado un estándar de marcado y especificación.

Answer 2

Tenga en cuenta que desde 2014 febrero con "Rendered Prose Diffs", también se puede ver la versión renderizada de un diff en un archivo de rebajas:

compromete y tirar de las solicitudes, incluyendo archivos de prosa ahora de entidad de origen y prestados vistas.

cambios que no contenían texto aparecen con un subrayado de puntos de baja intensidad.Pase el ratón sobre el texto para ver qué ha cambiado:

Answer 3

no he encontrado que las otras herramientas eran lo suficientemente buenos - que quería:

1. Posibilidad de editar sin conexión
2. No solo el descuento normal, sino el descuento real Github con descuento

Esto es lo que en última instancia se establecieron en: https://github.com/ypocat/gfms

> gfms 

Github Flavored Markdown Server. 
Run in your project's root directory. 
Usage: gfms 

Options: 
    -p, --port    Port number to listen at.  [required] 
    -h, --host    Host address to bind to.   [default: "localhost"] 
    --proxy     if behind a proxy, proxy url. 
    -a, --api    Render using Github API. 
    -n, --no-api-on-reload Disable usage of Github API when the doc is manually reloaded. 

así que he alias:

alias gm='gfms -a -p 8070' 

El uso de la opción -p golpea el API Github y utiliza el real, actual Github CSS por lo que aren No hay sorpresas.

Answer 4

Otra opción: el nuevo editor de texto de Github, Atom, renderizará el descuento con sabor a github a medida que lo edite. Ver https://atom.io/

No estoy seguro de si será gratis (como en la cerveza) a largo plazo.

Answer 5

Hay un buen editor de línea/en vivo aquí:

http://jbt.github.io/markdown-editor/

También hay un botón Preview en GitHub.

Consulte en la siguiente captura de pantalla que este botón aparece cuando hice clic en Editar en README.md.

mi humilde opinión el editor vivo es mejor que el actual disponible en GitHub.

ACTUALIZACIÓN

Hace un momento me pareció que después de buscar Markdown y Visual Studio que si usted está utilizando VS, puede instalar Web Essentials y tienen Markdown apoyo desde dentro de Visual Studio. ¡Eso es genial!

Tiene:

• resaltado de sintaxis => coloración completa de Markdown sintaxis
• Intellisense para lenguajes integrados (W00T) => característica del lenguaje incrustado de GitHub es totalmente apoyo de soporte para la sintaxis del lenguaje `` `.

• ventana de vista previa => Vea una ventana de vista previa de lado a lado del HTML representado
• Compilar a HTML => Haga clic derecho en cualquier archivo de rebajas y seleccione Compilación de rebajas a HTML. Esto generará un archivo .html anidado bajo el archivo Markdown y se mantendrá sincronizado a medida que cambie el archivo Markdown.
• Custom Stylesheet => Puede agregar una hoja de estilo específica de la solución para controlar los estilos de la ventana de vista previa.

Detalles sobre este/a here.

Answer 6

(Re-posting this answer con algunas modificaciones.)

Un poco tarde al juego, pero escribí un pequeño CLI en Python. Se llama Grip (Github Readme Instant Preview). Agregando a la respuesta de Patrick, esto le permitirá "revisar mis documentos localmente en mi navegador".

instalarlo con:

$ pip install grip 

Y para usarlo, simplemente:

$ grip 

A continuación, visita localhost:5000 para ver el archivo readme.md en ese lugar.

También puede especificar su propio archivo:

$ grip CHANGES.md 

Y cambiar el puerto:

$ grip 8080 

o combinar las dos anteriores:

$ grip CHANGES.md 8080 

Usted puede incluso hacer que GitHub- Marklow Markdown (es decir, cómo se emiten los comentarios y los problemas), opcionalmente con el contexto del repositorio para el auto-hyperlink refere rencias a otras cuestiones:

$ grip --gfm --context=username/repo issue.md 

Por razones de brevedad, ver el resto de las opciones y sus detalles utilizando la ayuda de CLI:

$ grip -h 

Características notables:

• hace que las páginas aparezcan exactamente como en GitHub
• Bloques cercados
• Python API
• Navegar entre los archivos vinculados
• exportar un documento prestado a un archivo

Espero que esto ayude. Check it out.

Answer 7

A partir de hoy, puede previsualizar mientras edita el archivo.