Trabalhando com README.md em github.com [fechado]

106

Não estou muito familiarizado com a linguagem de marcação leve usada pelo github ao atualizar arquivos README.

Onde estão os recursos que posso ler sobre como escrever a sintaxe de marcação apropriada para os arquivos README / wiki da minha biblioteca de código aberto?

E há uma ferramenta que eu possa "revisar meus documentos localmente em meu navegador" antes de enviar o README atualizado para meu repositório github?

Calvin Cheng
fonte

Respostas:

127

A marcação em questão é coincidentemente chamada de Markdown , criada por John Gruber, autor do blog Daring Fireball . A fonte original do Markdown pode ser encontrada em Daring Fireball - Markdown .

Existem muitos dialetos Markdown, a documentação do Github pode ser encontrada na página Github Flavored Markdown .

boa dica dessa página:

pressione M em qualquer página do Github com um editor Markdown para revelar o cheatsheet.

Você também pode usar a página Github Markdown Live Preview para testar seus documentos Markdown.

Atualização 08/11/2012 : Esforços estão em andamento para padronizar a sintaxe do Markdown. Veja The Future of Markdown - Jeff Atwood, Coding Horror e W3C Markdown Community Group .

Atualização 09-09-2014 : CommonMark, um padrão e especificações de redução de preço foi lançado.

Patrick Klingemann
fonte
8
Obrigado pela dica 'M'!
Jedidja,
2
O Github Markdown Live Preview não renderiza tabelas ...
Rubens Mariuzzo
2
Se você preferir um screencast de vídeo, criei um explicando Markdown aqui: mikemclin.net/markdown-syntax-language
Mike McLin
2
@Mike McLin Excelente vídeo explicando a sintaxe e os conceitos por trás! Ótima introdução para o novato do markdown como eu :)
Brock
1
A visualização ao vivo do markdown também não parece obedecer às regras do github sobre sublinhados no meio das palavras, por exemplo, my_setup_script.py não irá colocar em itálico 'setup' no github, mas sim no previewer. É útil, mas apenas para que as pessoas saibam.
user2428107
11

( Postando novamente esta resposta com algumas edições.)

Um pouco tarde para o jogo, mas escrevi uma pequena CLI em Python. É chamado de Grip (Github Readme Instant Preview) . Acrescentando à resposta de Patrick, isso permitirá que você "revise meus documentos localmente em meu navegador".

Instale-o com:

$ pip install grip

E para usá-lo, basta:

$ grip

Em seguida, visite localhost:5000para visualizar o readme.mdarquivo nesse local.

Você também pode especificar seu próprio arquivo:

$ grip CHANGES.md

E mude a porta:

$ grip 8080

Ou combine os dois anteriores:

$ grip CHANGES.md 8080

Você pode até renderizar Markdown com sabor do GitHub (ou seja, como os comentários e problemas são renderizados), opcionalmente com o contexto de repo para referências de hiperlink automático para outros problemas:

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

Para resumir, veja o resto das opções e seus detalhes usando a ajuda da CLI:

$ grip -h

Recursos notáveis:

  • Renderiza as páginas para que apareçam exatamente como no GitHub
  • Blocos cercados
  • API Python
  • Navegar entre os arquivos vinculados
  • Exportar um documento renderizado para um arquivo

Espero que isto ajude. Dê uma olhada .

Joe
fonte
5

Há um bom editor online / ao vivo aqui:

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

Também há um Previewbotão no GitHub.

Veja na imagem a seguir que este botão aparece quando eu clico em Editar README.md.

insira a descrição da imagem aqui

IMHO o editor ao vivo é melhor do que o atual disponível no GitHub.

ATUALIZAR

Depois de pesquisar pelo MarkdownVisual Studio, descobri que, se você estiver usando o VS, você pode instalar o Web Essentials e ter Markdownsuporte direto do Visual Studio. Isso é legal!

Tem:

  • Destaque de sintaxe => Colorização completa para sintaxe Markdown
  • Intellisense para linguagens embutidas ( W00T ) => O recurso de linguagem embutida do GitHub é totalmente suportado pelo suporte para a sintaxe da linguagem `` `.

insira a descrição da imagem aqui

  • Janela de visualização => Ver uma janela de visualização lado a lado do HTML renderizado
  • Compilar para HTML => Clique com o botão direito em qualquer arquivo Markdown e selecione Compilar Markdown para HTML. Isso irá gerar um arquivo .html aninhado no arquivo Markdown e permanecerá sincronizado conforme o arquivo Markdown muda.
  • Folha de estilo personalizada => Você pode adicionar uma folha de estilo específica da solução para controlar os estilos da janela de visualização.

Detalhes sobre isso aqui .

Leniel Maccaferri
fonte
4

Observe que desde fevereiro de 2014, com " Rendered Prose Diffs ", você também pode ver a versão renderizada de um diff em um arquivo markdown:

Solicitações de commits e pull, incluindo arquivos de prosa, agora apresentam visualizações renderizadas e de origem .

https://f.cloud.github.com/assets/17715/1999080/7f0c15a2-853e-11e3-95dc-1d7737e1ec20.png

As alterações não textuais aparecem com um sublinhado pontilhado discreto. Passe o mouse sobre o texto para ver o que mudou:

https://f.cloud.github.com/assets/17715/2005588/714cb5ea-86ef-11e3-9e92-a0d11ba6084f.png

VonC
fonte
1

Outra opção - o novo editor de texto do Github, Atom, irá renderizar a marcação com sabor do github conforme você o edita. Veja https://atom.io/

Não tenho certeza se será grátis (como na cerveja) a longo prazo.

user2428107
fonte
1

A partir de hoje, você pode visualizar, conforme edita o arquivo.

insira a descrição da imagem aqui

Rubi
fonte
0

Não achei as outras ferramentas boas o suficiente - eu queria:

  1. Capacidade de editar offline
  2. Não apenas a marcação regular, mas a marcação real do Github

Isso é o que eu finalmente decidi: 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.

Então eu alias:

alias gm='gfms -a -p 8070'

O uso da -popção atinge a API do Github e usa o CSS atual do Github para que não haja nenhuma surpresa.

schimmy
fonte