Como posso testar a aparência do meu arquivo readme.md antes de confirmar no github?

235

Estou escrevendo um leia-me para o meu projeto github no formato .md. Existe uma maneira de testar como será o meu arquivo readme.md antes de confirmar no github?

github markdown github-flavored-markdown Usman Ismail
fonte
4
Estou respondendo isso como um comentário, porque o thread está fechado e nenhuma das soluções estava renderizando tabelas de pipe da mesma maneira que o github. A solução web que parece mais próximo está aqui: pandao.github.io/editor.md/en.html
Donnie D'Amato
Com o GitLab 13.0 (maio de 2020), o editor de sites estáticos do GitLab possui um editor WYSIWYG. Veja minha resposta abaixo .
VonC

Respostas:

150

De várias maneiras: se você estiver em um Mac, use Mou .

Se você quiser testar em um navegador, tente o StackEdit , como apontado por @Aaron ou Dillinger, já que o Notepag parece estar inativo agora. Pessoalmente, uso o Dillinger, pois ele simplesmente funciona e salva todos os meus documentos no banco de dados local do meu navegador.

três
fonte
5
O dillinger.io também parece estar em baixo agora, embora ainda seja o primeiro listado quando você pesquisa no Google "visualizador online de descontos", então pode ser apenas eu. Usei com sucesso o stackedit.io para visualizar e editar meu readme.md.
Aaron
Dillinger está bem. Tem sido ok na maioria das vezes.
três
1
StackEdit é uma ótima ferramenta. Obrigado!
Olkunmustafa
O StackEdit formata "listas de definições", o github não. O StackEdit coloca blocos de código triplo de backtick na sua própria linha (útil para uso em listas numeradas), o github não. Existem outras diferenças. A única aposta segura é tentar e errar com uma essência e excluí-la quando terminar.
de Bruno Bronosky
1
Infelizmente, não se parece com o apoio Mou MacOS Mojave (10,14)
Chris Priest
79

O Atom funciona perfeitamente - basta abrir o arquivo Markdown e pressionar Ctrl + Shift + M para alternar o painel de visualização do Markdown ao lado dele. Ele lida com HTML e imagens também.

Captura de tela do Atom

Brian Burns
fonte
2
Como eu tinha recursos locais, como capturas de tela do aplicativo, essa solução funciona melhor. Obrigado!
Emadpres
6
Estou usando o átomo há um ano e não fazia ideia de que poderia fazer isso! Produzi, a freira vergonha ...
PaulB
brew barril instalar atom
jmgarnier 02/02
O perfs já tinha o Atom instalado, basta digitar atom .e clicar com o botão direito do mouse no leia-me>Markdown Preview
austin
Atom governa o poleiro. Nenhuma das stackedit, Dillinger ou typora suportou seções recolhíveis por meio de <details>tags HTML . Atom faz e parece melhor do que o resto para inicializar.
David Parks
35

Este se mostrou confiável por algum tempo: http://tmpvar.com/markdown.html

Motin
fonte
Foi um bom começo, mas este não mostra regras horizontais ... abandonadas antes de mais testes.
12124 Ben
Bom para uma verificação rápida.
Nikos Alexandris
35

Esta é uma pergunta bastante antiga, no entanto, como eu me deparei com ela enquanto pesquisava na Internet, talvez minha resposta seja útil para outras pessoas. Acabei de encontrar uma ferramenta CLI muito útil para renderizar a remarcação com sabor do GitHub: grip . Ele usa a API do GitHub, tornando-o muito bem.

Francamente, o desenvolvedor do grip , tem uma resposta mais elaborada sobre essas questões muito semelhantes:

aleimba
fonte
2
Obrigado! É bom não tem que quebrar o meu fluxo de trabalho e abra um editor diferente ou ir a um site diferente
oneWorkingHeadphone
1
Essa deve ser a resposta aceita - é perfeita! Basta pressionar a tecla Alt-Alt entre o editor e o navegador, e ele renderizará automaticamente a remarcação, e será exatamente como no GitHub. Finalmente uma solução aceitável.
Upio 28/08/19
30

Normalmente, apenas o edito no site do GitHub diretamente e clique em "Visualizar" logo acima da janela de edição.

Talvez esse seja um novo recurso que foi adicionado desde que este post foi feito.

Justin Harris
fonte
8
O problema com esta solução é que o GitHub (até agora) mostra diferenças em linha das alterações, o que torna uma visualização bastante inutilizável se você quiser ter uma impressão de como as alterações são e não o que realmente mudou.
B12Toaster
2
@ B12Toaster Você pode criar um novo arquivo no repositório usando o site do GitHub (sem salvá-lo), nomeá-lo xxx.mde colar seu código lá. A extensão do arquivo é .mdpara que você possa visualizar suas alterações. Você atualizará o utilitário que terminar, copie o conteúdo do arquivo e cole-o sobre o readme.mdarquivo original .
Mahmoud
Uma questão adicional é que ele não exibe tudo com precisão. Um exemplo concreto: se você estiver centralizando uma imagem na parte superior, <div align='center'><img ...></div>ela não será mostrada centralizada na visualização, ela será alinhada à esquerda. Você precisa salvá-lo para vê-lo com precisão, o que torna a visualização não confiável na minha opinião.
AFOC
28

O Visual Studio Code tem a opção de editar e visualizar alterações no arquivo md. Como o VS Code é independente de plataforma, isso funcionaria para Windows, Mac e Linux.

Para alternar entre visualizações, pressione Ctrl + Shift + V no editor. Você pode visualizar a visualização lado a lado (Ctrl + KV) com o arquivo que está editando e ver as alterações refletidas em tempo real enquanto edita.

Além disso...

P: O VS Code suporta o GitHub Flavored Markdown?

R: Não, o VS Code segmenta a especificação CommonMark Markdown usando a biblioteca markdown-it. O GitHub está se movendo em direção à especificação CommonMark.

Mais detalhes aqui

Nikhil Agrawal
fonte
3
Agradável!! Eu não tenho que instalar o atom !!
Aerin
1
A propósito, eu queria testar o link para os títulos usados ​​pelo GitHub ( stackoverflow.com/a/45860695/5362795 ) e descobri que ele também é suportado pelo VS Code!
Nagev 17/02
5

Eu uso um arquivo HTML hospedado localmente para visualizar os readmes do GitHub.

Examinei várias opções existentes, mas decidi criar minhas próprias para atender aos seguintes requisitos:

  • Único arquivo
  • URL hospedado localmente (intranet)
  • Nenhuma extensão do navegador necessária
  • Nenhum processamento hospedado localmente no servidor (por exemplo, sem PHP)
  • Leve (por exemplo, sem jQuery)
  • Alta fidelidade: use o GitHub para renderizar o Markdown e o mesmo CSS

Eu mantenho cópias locais dos meus repositórios GitHub em diretórios irmãos sob um diretório "github".

Cada diretório repo contém um arquivo README.md:

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

O diretório github contém o arquivo HTML "preview":

.../github/
           readme.html

Para visualizar um leia-me, eu navego no github / readme.html, especificando o repositório na string de consulta:

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

Como alternativa, você pode copiar o readme.html no mesmo diretório que o README.md e omitir a string de consulta:

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

Se o readme.html estiver no mesmo diretório que o README.md, você nem precisará fornecer o readme.html por HTTP: basta abri-lo diretamente do seu sistema de arquivos.

O arquivo HTML usa a API do GitHub para processar o Markdown em um arquivo README.md. Há um limite de taxa : no momento da redação, 60 solicitações por hora .

Funciona para mim nas versões atuais de produção do Chrome, IE e Firefox no Windows 7.

Fonte

Aqui está o arquivo 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 do desenvolvedor

  • Normalmente, envolvo meu código em um IIFE, mas, neste caso, não vi a necessidade e pensei em mantê-lo conciso
  • Eu não me incomodei em apoiar o IE de nível anterior
  • Por uma questão de concisão, omiti o código de tratamento de erros (você acredita em mim ?!)
  • Gostaria de receber dicas de programação JavaScript

Ideias

  • Estou pensando em criar um repositório GitHub para esse arquivo HTML e colocar o arquivo no ramo gh-pages, para que o GitHub o sirva como uma página da web "normal". Eu ajustaria o arquivo para aceitar uma URL completa - do README (ou qualquer outro arquivo Markdown) - como a string de consulta. Estou curioso para saber se a hospedagem do GitHub contornaria o limite de solicitações da API do GitHub e se ocorrer algum problema entre domínios (usando uma solicitação Ajax para obter o Markdown de um domínio diferente do domínio que serve a página HTML) .

Versão original (obsoleta)

Eu preservei esse registro da versão original por valor de curiosidade. Esta versão teve os seguintes problemas resolvidos na versão atual:

  • Foi necessário o download de alguns arquivos relacionados
  • Ele não suportava ser descartado no mesmo diretório que o arquivo README.md
  • Seu HTML era mais quebradiço; mais suscetível a alterações no GitHub

O diretório github contém o arquivo HTML "preview" e os arquivos relacionados:

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

Eu baixei os arquivos de fonte CSS e octicons do 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)

Renomeei os arquivos CSS para omitir a longa sequência de dígitos hexadecimais nos nomes originais.

Editei o github.css para se referir às cópias locais dos arquivos de fontes octicons.

Examinei o HTML de uma página do GitHub e reproduzi o suficiente da estrutura HTML em torno do conteúdo leia-me para fornecer uma fidelidade razoável; por exemplo, a largura restrita.

O CSS do GitHub, a fonte octicons e o "contêiner" HTML para o conteúdo leia-me estão movendo destinos: vou precisar fazer o download periodicamente de novas versões.

Eu brinquei com o uso de CSS de vários projetos do GitHub. Por exemplo:

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

mas finalmente decidiu usar o CSS do próprio GitHub.

Fonte

Aqui está o arquivo 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
fonte
3

Para Githubou Bitbuckettema, poderia usar o editor on-line mattstow , url: http://writeme.mattstow.com

Eric Wang
fonte
3

Para usuários do Visual Studio (não VS CODE).

Instale a extensão Markdown EditorCaptura de tela

Dessa forma, quando você abrir um README.md, terá uma visualização ao vivo no lado direito.

insira a descrição da imagem aqui

Guilherme de Jesus Santos
fonte
2

Basta pesquisar na web para ver muitos exemplos: https://stackedit.io/

resultados
fonte
2

Markdown Preview , o plug-in do Sublime Text mencionado em um comentário anterior não é mais compatível com o ST2, mas suporta apenas o Sublime Text 3 (desde a primavera de 2018).

O que é interessante: ele suporta GFM, GitHub Flavored Markdown , que pode fazer um pouco mais do que o Markdown normal. Isso é relevante se você quiser saber .mdexatamente como serão os seus s no GH. (Incluindo essas informações, porque o OP não adicionou a tag GFM e outras pessoas que procuram uma solução também podem não estar cientes disso).

Você pode usá-lo com a API do GitHub se estiver online, mas você deve obter um token de acesso pessoal para esse fim, porque as chamadas à API sem autenticação são limitadas. Há mais informações sobre a análise de GFM nos documentos do plug-in.

Kay
fonte
1

Se você estiver usando Pycharm (ou outro IDE Jetbrains como Intellij, RubyMine, PHPStorm, etc), existem vários plugins gratuitos para suporte ao Markdown diretamente no seu IDE que permitem a visualização em tempo real durante a edição. O plugin Markdown Navigator é bastante bom. Se você abrir um arquivo .md no IDE, as versões recentes oferecerão a instalação de plug-ins de suporte e a lista.

randalv
fonte
1

SublimeText 2/3

Instale o pacote: Markdown Preview

Opções:

  • Visualizar no navegador.
  • Exporte para html.
  • Copiar para área de transferência.
alditis
fonte
Isso funciona bem porque suporta github, gitlab e remarcações genéricas. Embora seja difícil de instalar.
Abel Callejo
0

Use o Jupyter Lab .

Para instalar o Jupyter Lab, digite o seguinte em seu ambiente:

pip install jupyterlab

Após a instalação, navegue até o local do seu arquivo de remarcação, clique com o botão direito do mouse no arquivo, selecione "Abrir com" e clique em "Visualização de remarcação".

k0L1081
fonte
0

Para o Visual Studio Code, eu uso

Markdown Preview Extensão aprimorada.

Olusola Omosola
fonte
0

O MarkdownViewerPlusPlus é um plug-in "Notepad ++" [...] para exibir um arquivo Markdown renderizado on-the-fly

  • Painel acoplável (alternar) com um HTML renderizado do arquivo / guia atualmente selecionado
  • Compatível com CommonMark (0,28)
  • Rolagem sincronizada
  • Integração CSS personalizada
  • Exportação de HTML e PDF
  • Bloco de notas Unicode + plug-in [...] "
rob2universe
fonte
0

Você pode usar o editor de site estático : com o GitLab 13.0 (maio de 2020) , ele vem com um painel WYSIWYG.

WYSIWYG para o editor de site estático

O Markdown é uma sintaxe poderosa e eficiente para a criação de conteúdo da Web, mas mesmo autores experientes do conteúdo do Markdown podem se esforçar para lembrar algumas das opções de formatação usadas com menos frequência ou escrever tabelas do zero com moderação complexa.
Existem alguns trabalhos melhor realizados com um rich text, editor "O que você vê é o que obtém" (WYSIWYG).

O GitLab 13.0 traz para o Static Site Editor uma experiência de autoria do WYSIWYG Markdown com opções de formatação para opções comuns de formatação, como cabeçalhos, negrito, itálico, links, listas, citações de bloco e blocos de código.

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

O editor WYSIWYG também remove a tarefa onerosa de editar tabelas no Markdown, permitindo editar visualmente linhas, colunas e células da tabela da mesma maneira que edita uma planilha. Para aqueles que escrevem com mais facilidade no Markdown bruto, há até uma guia para alternar entre os modos de edição WYSIWYG e de texto sem formatação.

Consulte a documentação e o problema .

Novamente, você o usaria apenas para escrever o seu README: assim que parecer bom, você poderá reportá-lo ao seu projeto original.
Mas o ponto é: você não precisa mais de nenhum plugin de visualização de descontos de terceiros.

VonC
fonte
-1

Para aqueles que desejam desenvolver em seus iPads, eu gosto de Textastic. Você pode editar e visualizar os arquivos README.md sem uma conexão à Internet, depois de baixar o documento da nuvem.

ztalbot
fonte