Trabajando con README.md en github.com [cerrado]

No estoy muy familiarizado con el lenguaje de marcado ligero que usa github al actualizar los archivos README.

¿Dónde están los recursos que puedo leer sobre cómo escribir la sintaxis de marcado apropiada 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 de github?

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

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

buen consejo de esa página:

presione M en cualquier página de Github con un editor de Markdown para revelar la hoja de trucos.

También puede usar la página de vista previa en vivo de Github Markdown para probar sus documentos de Markdown.

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

Actualización 09/09/2014 : CommonMark, se ha publicado una especificación y un estándar de rebajas.

( Volver a publicar esta respuesta con algunas modificaciones).

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

Instálelo con:

$ pip install grip

Y para usarlo, simplemente:

$ grip

Luego visite localhost:5000para ver el readme.mdarchivo en esa ubicación.

También puede especificar su propio archivo:

$ grip CHANGES.md

Y cambia el puerto:

$ grip 8080

O combine los dos anteriores:

$ grip CHANGES.md 8080

Incluso puede representar Markdown con sabor a GitHub (es decir, cómo se representan los comentarios y los problemas), opcionalmente con el contexto del repositorio para hacer referencias de hipervínculo automático a otros problemas:

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

Para mayor brevedad, consulte el resto de las opciones y sus detalles mediante la ayuda de CLI:

$ grip -h

Características notables:

• Representa las páginas para que aparezcan exactamente como en GitHub
• Bloques vallados
• API de Python
• Navegar entre archivos vinculados
• Exportar un documento renderizado a un archivo

Espero que esto ayude. Compruébalo .

Aquí hay un buen editor en línea / en vivo:

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

También hay un Previewbotón en GitHub.

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

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

ACTUALIZAR

Recién descubrí después de buscar Markdowny Visual Studio que si está usando VS, puede instalar Web Essentials y tener Markdownsoporte directamente desde Visual Studio. ¡Eso es genial!

Tiene:

• Resaltado de sintaxis => Coloración completa para la sintaxis de Markdown
• Intellisense para lenguajes incrustados ( W00T ) => La función de lenguaje incrustado de GitHub es totalmente compatible con la compatibilidad con la sintaxis del lenguaje `` `.

• Ventana de vista previa => Ver una ventana de vista previa en paralelo del HTML renderizado
• Compilar en HTML => Haga clic con el botón derecho en cualquier archivo Markdown y seleccione Compilar Markdown en HTML. Esto generará un archivo .html anidado bajo el archivo Markdown y permanecerá sincronizado a medida que cambie el archivo Markdown.
• Hoja de estilo personalizada => Puede agregar una hoja de estilo específica de la solución para controlar los estilos de la ventana de vista previa.

Detalles al respecto aquí .

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

Las solicitudes de confirmación y extracción, incluidos los archivos en prosa, ahora cuentan con vistas de origen y renderizadas .

Los cambios que no son de texto aparecen con un subrayado de puntos discretos. Coloca el cursor sobre el texto para ver qué ha cambiado:

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

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

A partir de hoy, puede obtener una vista previa mientras edita el archivo.

No encontré que las otras herramientas fueran lo suficientemente buenas, quería:

1. Posibilidad de editar sin conexión
2. No solo la rebaja regular, sino la rebaja real con sabor a Github

Esto es lo que finalmente me decidí: 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 tengo un alias:

alias gm='gfms -a -p 8070'

El uso de la -popción llega a la API de Github y usa el CSS de Github actual y real para que no haya sorpresas.