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

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?

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.

( 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 .

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.

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 `` `.

• 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 .

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 .

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

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.

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

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.