¿Cómo puedo probar cómo se verá mi archivo readme.md antes de comprometerme con github?

235

Estoy escribiendo un archivo Léame para mi proyecto github en formato .md. ¿Hay alguna manera de probar cómo se verá mi archivo readme.md antes de comprometerme con github?

github markdown github-flavored-markdown Usman Ismail
fuente
44
Estoy respondiendo esto como un comentario porque el subproceso está cerrado y ninguna de las soluciones estaba representando tablas de tuberías de la misma manera que github. La solución web que parece más cercana está aquí: pandao.github.io/editor.md/en.html
Donnie D'Amato
Con GitLab 13.0 (mayo de 2020), el editor de sitio estático para GitLab tiene un editor WYSIWYG. Vea mi respuesta a continuación .
VonC

Respuestas:

150

De muchas maneras: si estás en una Mac, usa Mou .

Si desea probar en un navegador, puede probar StackEdit , como lo señalaron @Aaron o Dillinger ya que Notepag parece estar caído ahora. Personalmente uso Dillinger ya que simplemente funciona y guarda todos mis documentos en la base de datos local de mi navegador.

Tres
fuente
55
dillinger.io también parece estar inactivo ahora, aunque todavía es el primero que aparece cuando buscas en Google "markdown online viewer", por lo que podría ser yo. Utilicé con éxito stackedit.io para obtener una vista previa y editar mi readme.md.
Aaron
Dillinger no está bien. Ha estado bien la mayor parte del tiempo.
tres
1
StackEdit es una gran herramienta. ¡Gracias!
Olkunmustafa
StackEdit formatea "listas de definiciones", github no. StackEdit pone bloques de código de triple backtick en su propia línea (útil para usar en listas numeradas), github no. Hay otras diferencias La única apuesta segura es hacer una prueba y error con una esencia y eliminarla cuando haya terminado.
Bruno Bronosky
1
Desafortunadamente no parece que Mou soporte MacOS Mojave (10.14)
Chris Priest
79

Atom funciona muy bien fuera de la caja: solo abra el archivo Markdown y presione Ctrl + Shift + M para alternar el panel de vista previa Markdown junto a él. Maneja HTML e imágenes también.

Captura de pantalla de Atom

Brian Burns
fuente
2
Como tenía recursos locales, como capturas de pantalla de la aplicación, esta solución funciona mejor. ¡Gracias!
Emadpres
66
¡He estado usando el átomo durante un año y no tenía idea de que podría hacer eso! Saca la vergüenza monja ...
PaulB
átomo de instalación de barril de cerveza
jmgarnier
perfs ya tenía instalado Atom, simplemente tipeó atom .y hizo clic derecho en el archivo Léame>Markdown Preview
austin
Atom gobierna el gallinero. Ninguna de las secciones plegables compatibles con stackedit, Dillinger o typora a través de <details>etiquetas HTML . Atom lo hace y se ve mejor que el resto para arrancar.
David Parks
35

Este ha demostrado ser confiable por bastante tiempo: http://tmpvar.com/markdown.html

Motin
fuente
Tuvo un buen comienzo, pero este no muestra reglas horizontales ... abandonado antes de nuevas pruebas.
Ben
Agradable para un chequeo rápido sin embargo.
Nikos Alexandris
35

Esta es una pregunta bastante antigua, sin embargo, dado que me topé con ella mientras buscaba en Internet, tal vez mi respuesta sea útil para otros. Acabo de encontrar una herramienta CLI muy útil para representar el descuento de GitHub: agarre . Utiliza la API de GitHub, por lo que se presenta bastante bien.

Francamente, el desarrollador de grip , tiene una respuesta más elaborada sobre estas preguntas muy similares:

aleimba
fuente
2
¡Gracias! Es bueno no tener que interrumpir mi flujo de trabajo y abrir un editor diferente o ir a un sitio web diferente
OneWorkingHeadphone
1
Esta debería ser la respuesta aceptada: ¡es perfecta! Simplemente presione Alt entre su editor y su navegador, y automáticamente volverá a representar el descuento, y se ve exactamente como lo hace en GitHub. Finalmente una solución aceptable.
Upio
30

Por lo general, solo lo edito en el sitio web de GitHub directamente y hago clic en "Vista previa" justo encima de la ventana de edición.

Tal vez esa es una nueva característica que se ha agregado desde que se realizó esta publicación.

Justin Harris
fuente
8
El problema con esta solución es que GitHub (hasta ahora) muestra diferencias en línea de los cambios, lo que hace que una vista previa sea bastante inutilizable si desea tener una impresión de cómo se ven los cambios y no qué cambió realmente.
B12Toaster
2
@ B12Toaster Puede crear un nuevo archivo en el repositorio utilizando el sitio web de GitHub (sin guardarlo) y asígnele un nombre xxx.mdy pegue su código allí. La extensión de archivo es .mdpara que pueda obtener una vista previa de sus cambios. Actualizará la utilidad que termine, luego copie el contenido del archivo y péguelo sobre el readme.mdarchivo original .
Mahmoud el
Un problema adicional es que no muestra todo con precisión. Un ejemplo concreto: si está centrando una imagen en la parte superior utilizando <div align='center'><img ...></div>, no se mostrará centrada en la vista previa, se alineará a la izquierda. Tienes que guardarlo para verlo con precisión, lo que hace que la vista previa no sea confiable en mi opinión.
AFOC
28

Visual Studio Code tiene la opción de editar y obtener una vista previa de los cambios del archivo md. Dado que VS Code es independiente de la plataforma, esto funcionaría para Windows, Mac y Linux.

Para cambiar entre vistas, presione Ctrl + Shift + V en el editor. Puede ver la vista previa en paralelo (Ctrl + KV) con el archivo que está editando y ver los cambios reflejados en tiempo real a medida que edita.

También...

P: ¿VS Code es compatible con GitHub Flavored Markdown?

R: No, VS Code apunta a la especificación de Markdown de CommonMark usando la biblioteca markdown-it. GitHub se está moviendo hacia la especificación CommonMark.

Más detalles aquí

Nikhil Agrawal
fuente
3
¡¡Agradable!! No tengo que instalar atom !!
Aerin
1
Por cierto, quería probar el enlace a los títulos utilizados por GitHub ( stackoverflow.com/a/45860695/5362795 ) y descubrí que también es compatible con VS Code.
Nagev
5

Utilizo un archivo HTML alojado localmente para obtener una vista previa de los archivos Léame de GitHub.

Miré varias opciones existentes, pero decidí desarrollar las mías para cumplir con los siguientes requisitos:

  • Fila india
  • URL alojada localmente (intranet)
  • No se requiere extensión del navegador
  • Sin procesamiento del lado del servidor alojado localmente (por ejemplo, sin PHP)
  • Ligero (por ejemplo, no jQuery)
  • Alta fidelidad: use GitHub para representar el Markdown y el mismo CSS

Guardo copias locales de mis repositorios de GitHub en directorios hermanos bajo un directorio "github".

Cada directorio de repos contiene un archivo README.md:

.../github/
           repo-a/
                  README.md
           repo-b/
                  README.md
           etc.

El directorio github contiene el archivo HTML "vista previa":

.../github/
           readme.html

Para obtener una vista previa de un archivo Léame, busco github / readme.html, especificando el repositorio en la cadena de consulta:

http://localhost/github/readme.html?repo-a

Alternativamente, puede copiar el archivo readme.html en el mismo directorio que README.md y omitir la cadena de consulta:

http://localhost/github/repo-a/readme.html

Si readme.html está en el mismo directorio que README.md, ni siquiera necesita servir readme.html a través de HTTP: simplemente puede abrirlo directamente desde su sistema de archivos.

El archivo HTML utiliza la API de GitHub para representar el Markdown en un archivo README.md. Hay un límite de velocidad : al momento de escribir, 60 solicitudes por hora .

Funciona para mí en las versiones de producción actuales de Chrome, IE y Firefox en Windows 7.

Fuente

Aquí está el archivo HTML (readme.html):

<!DOCTYPE html>
<!--
     Preview a GitHub README.md.

     Either:

     -  Copy this file to a directory that contains repo directories,
        and then specify a repo name in the query string.

        For example:

          http://localhost/github/readme.html?myrepo

     or

     -  Copy this file to the directory that contains a README.md,
        and then browse to this file without specifying a query string.

        For example:

          http://localhost/github/myrepo/readme.html

        (or just open this file in your browser directly from
        your file system, without HTTP)
-->
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta name="author" content="Graham Hannington"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GitHub readme preview</title>
<link rel="stylesheet" type="text/css" href="http://primercss.io/docs.css"/>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";

var readmeURL;

var queryString = location.search.substring(1);

if (queryString.length > 0) {
  readmeURL = queryString + "/" + README_FILE_NAME;
} else {
  readmeURL = README_FILE_NAME;
}

// Get Markdown, then render it as HTML
function getThenRenderMarkdown(markdownURL) {
  var xhr = new XMLHttpRequest();
  xhr.open("GET", markdownURL, true);
  xhr.responseType = "text";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
     // Response text contains Markdown
      renderMarkdown(this.responseText);
    }
  }
  xhr.send();
}

// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
  xhr.responseType = "html";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
      document.getElementById("readme").innerHTML = this.response;
    }
  }
  xhr.send(markdown);
}

window.onload = function() {
  getThenRenderMarkdown(readmeURL);
}
//]]>
</script>
</head>
<body>
<header class="masthead">
<div class="container">
<span class="masthead-logo"><span class="mega-octicon
octicon-mark-github"></span>GitHub readme preview</span>
</div>
</header>
<div class="container">
<div id="readme" class="markdown-body">
<p>Rendering markdown, please wait...</p>
</div>
<footer class="footer">Rendering by
<a href="https://developer.github.com/v3/markdown/">GitHub</a>,
styling by <a href="http://primercss.io/">Primer</a>.</footer>
</div>
</body>
</html>

Notas del desarrollador

  • Por lo general, envuelvo mi código en un IIFE, pero en este caso, no vi la necesidad y pensé en mantenerlo conciso
  • No me he molestado en admitir IE de nivel de fondo
  • Para ser concisos, he omitido el código de manejo de errores (¡¿me crees ?!)
  • Agradecería los consejos de programación de JavaScript

Ideas

  • Estoy considerando crear un repositorio de GitHub para este archivo HTML y colocar el archivo en la rama gh-pages, para que GitHub lo sirva como una página web "normal". Ajustaría el archivo para aceptar una URL completa, del archivo README (o cualquier otro archivo Markdown), como la cadena de consulta. Tengo curiosidad por ver si ser alojado por GitHub eludiría el límite de solicitud de API de GitHub y si me encuentro con problemas de dominio cruzado (usando una solicitud de Ajax para obtener el Markdown desde un dominio diferente al dominio que sirve la página HTML) .

Versión original (en desuso)

He conservado este registro de la versión original por valor de curiosidad. Esta versión tenía los siguientes problemas que se resuelven en la versión actual:

  • Se requirieron algunos archivos relacionados para descargar
  • No admitía que se soltara en el mismo directorio que README.md
  • Su HTML era más frágil; más susceptible a los cambios en GitHub

El directorio github contiene el archivo HTML de "vista previa" y archivos relacionados:

.../github/
           readme-preview.html
           github.css
           github2.css
           octicons.eot
           octicons.svg
           octicons.woff

Descargué los archivos de fuente CSS y octicons de GitHub:

https://assets-cdn.github.com/assets/github- ... .css
https://assets-cdn.github.com/assets/github2- ... .css
https://github.com/static/fonts/octicons/octicons.* (eot, woff, svg)

Cambié el nombre de los archivos CSS para omitir la larga cadena de dígitos hexadecimales en los nombres originales.

Edité github.css para referirme a las copias locales de los archivos de fuente de octicons.

Examiné el HTML de una página de GitHub y reproduje suficiente estructura HTML que rodea el contenido del archivo Léame para proporcionar una fidelidad razonable; por ejemplo, el ancho restringido.

El CSS de GitHub, la fuente de octicons y el "contenedor" HTML para el contenido del archivo Léame son objetivos móviles: necesitaré descargar periódicamente nuevas versiones.

Jugué con el uso de CSS de varios proyectos de GitHub. Por ejemplo:

<link rel="stylesheet" type="text/css"
      href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">

pero finalmente decidió usar el CSS de GitHub.

Fuente

Aquí está el archivo HTML (readme-preview.html):

<!DOCTYPE html>
<!-- Preview a GitHub README.md.
     Copy this file to a directory that contains repo directories.
     Specify a repo name in the query string. For example:

     http://localhost/github/readme-preview.html?myrepo
-->
<html>
<head>
<title>Preview GitHub readme</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<!-- Downloaded copies of the CSS files served by GitHub.
     In github.css, the @font-face for font-family:'octicons'
     has been edited to refer to local copies of the font files -->
<link rel="stylesheet" type="text/css" href="github.css"/>
<link rel="stylesheet" type="text/css" href="github2.css"/>
<style>
body {
  margin-top: 1em;
}
</style>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";

var repo = location.search.substring(1);

// Get Markdown, then render it as HTML
function getThenRenderMarkdown() {
  var xhr = new XMLHttpRequest();
  xhr.open("GET", repo + "/" + README_FILE_NAME, true);
  xhr.responseType = "text";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
     // Response text contains Markdown
      renderMarkdown(this.responseText);
    }
  }
  xhr.send();
}

// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) {
  var xhr = new XMLHttpRequest();
  xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
  xhr.responseType = "html";
  xhr.onload = function(e) {
    if (this.status == HTTP_STATUS_OK) {
      document.getElementById("readme-content").innerHTML = this.response;
    }
  }
  xhr.send(markdown);
}

window.onload = getThenRenderMarkdown;
//]]>
</script>
</head>
<body>
<!-- The following HTML structure was copied from live GitHub page on 2015-12-01,
     except for the "readme-content" id of the article element,
     which was coined for this preview page.-->
<div class="main-content" role="main">
<div class="container repo-container new-discussion-timeline experiment-repo-nav">
<div class="repository-content">
<div id="readme" class="boxed-group flush clearfix announce instapaper_body md">
<h3><span class="octicon octicon-book"></span>README.md</h3>
<article class="markdown-body entry-content"
         itemprop="mainContentOfPage"
         id="readme-content"><p>Rendering markdown...</p></article>
</div>
</div>
</div>
</div>
</body>
</html>
Graham Hannington
fuente
3

Para usuarios de Visual Studio (no VS CODE).

Instalar la extensión Markdown EditorCaptura de pantalla

De esta manera, cuando abra un archivo README.md, tendrá una vista previa en vivo en el lado derecho.

ingrese la descripción de la imagen aquí

Guilherme de Jesus Santos
fuente
2

Markdown Preview , el complemento para Sublime Text mencionado en un comentario anterior ya no es compatible con ST2, pero solo es compatible con Sublime Text 3 (desde la primavera de 2018).

Lo bueno de esto: es compatible con GFM, GitHub Flavored Markdown , que puede hacer un poco más que Markdown regular. Esto es relevante si desea saber .mdexactamente cómo se verá su GH en GH. (Incluyendo este bit de información porque el OP no agregó la etiqueta GFM por sí mismos, y otros que buscan una solución podrían no estar al tanto tampoco).

Puede usarlo con la API de GitHub si está en línea, aunque debería obtener un token de acceso personal para este propósito porque las llamadas a la API sin autenticación son limitadas. Hay más información sobre Parsing GFM en los documentos del complemento.

Kay
fuente
1

Si está utilizando Pycharm (u otro IDE de Jetbrains como Intellij, RubyMine, PHPStorm, etc.), hay múltiples complementos gratuitos para el soporte de Markdown directamente en su IDE que permiten una vista previa en tiempo real durante la edición. El complemento Markdown Navigator es bastante bueno. Si abre un archivo .md en el IDE, las versiones recientes le ofrecerán instalar complementos de soporte y le mostrarán la lista.

randalv
fuente
1

SublimeText 2/3

Paquete de instalación: Markdown Preview

Opciones:

  • Vista previa en el navegador.
  • Exportar a html.
  • Copiar al portapapeles.
alditis
fuente
Esto funciona bien porque admite github, gitlab y markdown genérico. Aunque es difícil de instalar.
Abel Callejo
0

Utiliza Jupyter Lab .

Para instalar Jupyter Lab, escriba lo siguiente en su entorno:

pip install jupyterlab

Después de la instalación, busque la ubicación de su archivo de descuento, haga clic con el botón derecho en el archivo, seleccione "Abrir con" y luego haga clic en "Vista previa de descuento".

k0L1081
fuente
0

Para Visual Studio Code, yo uso

Markdown Preview Mejora mejorada.

Olusola Omosola
fuente
0

MarkdownViewerPlusPlus es un "[...] Notepad ++ Plugin para ver un archivo Markdown presentado sobre la marcha Características

  • Panel acoplable (alternar) con un HTML representado del archivo / pestaña seleccionado actualmente
  • Compatible con CommonMark (0.28)
  • Desplazamiento sincronizado
  • Integración CSS personalizada
  • Exportación HTML y PDF
  • Notepad ++ Unicode Plugin [...] "
rob2universe
fuente
0

Puede usar el editor de sitio estático : con GitLab 13.0 (mayo de 2020) , viene con un panel WYSIWYG.

WYSIWYG para el editor de sitio estático

Markdown es una sintaxis potente y eficiente para la creación de contenido web, pero incluso los autores experimentados del contenido de Markdown pueden tener dificultades para recordar algunas de las opciones de formato menos utilizadas o escribir incluso tablas moderadamente complejas desde cero.
Hay algunos trabajos mejor realizados con un texto enriquecido, editor "Lo que ves es lo que obtienes" (WYSIWYG).

GitLab 13.0 trae una experiencia de autoría de WYSIWYG Markdown al Editor de sitio estático con opciones de formato para opciones de formato comunes como encabezados, negrita, cursiva, enlaces, listas, comillas de bloque y bloques de código.

https://about.gitlab.com/images/13_0/wysiwyg-markdow-in-sse.png

El editor WYSIWYG también elimina la onerosa tarea de editar tablas en Markdown al permitirle editar visualmente las filas, columnas y celdas de la tabla de la misma manera que editaría una hoja de cálculo. Para aquellos que se sienten más cómodos escribiendo en Markdown sin formato, incluso hay una pestaña para cambiar entre WYSIWYG y los modos de edición de texto sin formato.

Ver documentación y problema .

Una vez más, lo usaría solo para escribir su README: una vez que se vea bien, puede informarlo a su proyecto original.
Pero el punto es: no necesita más ningún complemento de vista previa de rebajas de terceros.

VonC
fuente
-1

Para aquellos que desean desarrollar en sus iPads, me gusta Textastic. Puede editar y obtener una vista previa de los archivos README.md sin una conexión a Internet, una vez que haya descargado el documento desde la nube.

ztalbot
fuente