link - Trabajando con README.md en github.com

markdown underline

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 existe alguna herramienta que pueda "revisar mis documentos localmente en mi navegador" antes de enviar el archivo README actualizado a mi repositorio github?

Answer 1

( Volviendo a publicar esta respuesta con algunas ediciones).

Un poco tarde para el juego, pero escribí una pequeña 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

Luego, visite localhost:5000 para ver el archivo readme.md 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 renderizar el marcado con sabor a GitHub (es decir, cómo se emiten los comentarios y los problemas), opcionalmente con contexto de repos para referencias de hipervínculo automático a otros problemas:

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

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

$ grip -h

Características notables:

• Renders páginas para que aparezcan exactamente como en GitHub
• Bloques cercados
• API de Python
• Navega entre los archivos vinculados
• Exportar un documento renderizado a un archivo

Espero que esto ayude. Compruébalo .

Answer 2

A partir de hoy, puede obtener una vista previa a medida que edita el archivo.

Answer 3

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 para Github se puede encontrar en la página de Github Flavoured 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 de Github Markdown Live para probar sus documentos de Markdown.

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

Actualización CommonMark : se ha lanzado CommonMark un estándar de rebajas y especificaciones.

Answer 4

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

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

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

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

En mi humilde opinión, el http://jbt.github.io/markdown-editor/ vivo es mejor que el actual disponible en GitHub.

ACTUALIZAR

Recientemente, después de buscar Markdown y Visual Studio, descubrí que si usa VS, puede instalar Web Essentials y tener compatibilidad con Markdown desde Visual Studio. ¡Eso es genial!

Tiene:

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

• Ventana de vista previa => Vea una ventana de vista previa de lado a lado del HTML renderizado
• Compile en HTML => Haga clic con el botón derecho en cualquier archivo Markdown y seleccione Compilar marcado en HTML. Esto generará un archivo .html anidado bajo el archivo Markdown y se mantendrá 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 here .

Answer 5

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

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

Esto es lo que finalmente 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 he aliased:

alias gm=''gfms -a -p 8070''

Al usar la opción -p , se llega a la API de Github y se usa el actual Github CSS actual para que no haya sorpresas.

Answer 6

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 7

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

Las solicitudes de compilación y extracción, incluidos los archivos en prosa, ahora incluyen vistas de origen y visualizadas .

Los cambios que no son de texto aparecen con un subrayado de puntos bajos. Desplácese sobre el texto para ver qué ha cambiado: