Comentários em Markdown

Qual é a syntax para armazenar um comentário em um arquivo de remarcação, por exemplo, um comentário CVS $ Id $ no topo do arquivo? Não encontrei nada no projeto de remarcação .

Acredito que todas as soluções propostas anteriormente (além daquelas que exigem implementações específicas) resultam na inclusão dos comentários no HTML de saída, mesmo que eles não sejam exibidos.

Se você quiser um comentário que seja estritamente para si mesmo (os leitores do documento convertido não poderão vê-lo, mesmo com “ver fonte”) você pode (ab) usar os labels de link (para uso com links de estilo de referência) que são disponível na especificação do Markdown principal:

http://daringfireball.net/projects/markdown/syntax#link

Isso é:

[comment]: <> (This is a comment, it will not be included) [comment]: <> (in the output file unless you use it in) [comment]: <> (a reference style link.) 

Ou você poderia ir mais longe:

 [//]: <> (This is also a comment.) 

Para melhorar a compatibilidade da plataforma (e salvar um pressionamento de tecla), também é possível usar # (que é um destino de hiperlink legítimo) em vez de <> :

 [//]: # (This may be the most platform independent comment) 

Para portabilidade máxima, é importante inserir uma linha em branco antes e depois desse tipo de comentário, porque alguns analisadores de Markdown não vinculam as definições ao texto regular. A pesquisa mais recente com a Babelmark mostra que linhas em branco antes e depois são importantes. Alguns analisadores exibirão o comentário se não houver uma linha em branco antes, e alguns analisadores excluirão a linha a seguir se não houver linha em branco depois.

Em geral, essa abordagem deve funcionar com a maioria dos analisadores de Markdown, já que faz parte da especificação principal. (mesmo se o comportamento quando vários links são definidos, ou quando um link é definido, mas nunca usado, não é estritamente especificado).

Eu uso tags HTML padrão, como

  

Observe o traço triplo. A vantagem é que ele funciona com pandoc ao gerar saída TeX ou HTML. Mais informações estão disponíveis no grupo pandoc-discuss .

Esta pequena pesquisa prova e refina a resposta de Magnus

A syntax mais independente de plataforma é

 (empty line) [comment]: # (This actually is the most platform independent comment) 

Ambas as condições são importantes:

  1. Usando # (e não <> )
  2. Com uma linha vazia antes do comentário . Linha vazia após o comentário não tem impacto no resultado.

A especificação estrita de Markdown CommonMark só funciona como pretendido com esta syntax (e não com <> e / ou uma linha vazia)

Para provar isso, usaremos o Babelmark2, escrito por John MacFarlane. Essa ferramenta verifica a renderização de determinado código-fonte em 28 implementações de Markdown.

( + – passou no teste, - – não passou ? – deixa algum lixo que não é mostrado no HTML renderizado).

  • Nenhuma linha vazia, usando <> 13+, 15-
  • Linha vazia antes do comentário, usando <> 20+, 8-
  • Linhas vazias ao redor do comentário, usando <> 20+, 8-
  • Nenhuma linha vazia, usando # 13+ 1? 14-
  • Linha vazia antes do comentário, usando # 23+ 1? 4-
  • Linhas vazias ao redor do comentário, usando # 23+ 1? 4-
  • Comentário HTML com 3 hífens 1+ 2? 25 – da resposta do chl (note que esta é uma syntax diferente)

Isso prova as afirmações acima.

Essas implementações falham todos os 7 testes. Não há chance de usar comentários excluídos em renderização com eles.

  • cebe / markdown 1.1.0
  • Cebe / markdown MarkdownExtra 1.1.0
  • cebe / markdown GFM 1.1.0
  • s9e \ TextFormatter (Fatdown / PHP)

Se você estiver usando o Jekyll ou octopress, o seguinte também funcionará.

 {% comment %} These commments will not include inside the source. {% endcomment %} 

As tags Liquid {% comment %} são analisadas primeiro e removidas antes mesmo de o processador MarkDown chegar a ela. Os visitantes não verão quando tentarem visualizar a fonte do navegador.

Uma alternativa é colocar comentários em tags HTML estilizadas. Dessa forma, você pode alternar sua visibilidade conforme necessário. Por exemplo, defina uma class de comentário em sua folha de estilo CSS.

.comment { display: none; }

Então, o seguinte MARKDOWN aprimorado

We do NOT support comments

aparece da seguinte forma em um BROWSER

We do support comments

Isso funciona no GitHub:

 [](Comment text goes here) 

O HTML resultante parece com:

  

Que é basicamente um link vazio. Obviamente, você pode ler isso na origem do texto processado, mas você pode fazer isso no GitHub de qualquer maneira.

Veja também Critic Markup, suportado por um número crescente de ferramentas Markdown.

http://criticmarkup.com/

 Comment {>> < <} Lorem ipsum dolor sit amet.{>>This is a comment< <} Highlight+Comment {== ==}{>> < <} Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget nulla.==}{>>confusing< <} Mauris massa sem, tempor sed cursus et, semper tincidunt lacus. 

Que tal colocar os comentários em um bloco R não-eval e não ecológico? ou seja,

 ```{r echo=FALSE, eval=FALSE} All the comments! ``` 

Parece funcionar bem para mim.

Divulgação: eu escrevi o plugin.

Como a pergunta não especifica uma implementação de markdown específica, gostaria de mencionar o Plugin de Comentários para python-markdown , que implementa o mesmo estilo de comentário de pandoc mencionado acima.

  

Não funciona no Pandoc Markdown (Pandoc 1.12.2.1). Comentários ainda apareciam em html. O seguinte funcionou:

 Blank line [^Comment]: Text that will not appear in html source Blank line 

Em seguida, use a extensão + nota de rodapé. É essencialmente uma nota de rodapé que nunca é referenciada.

Os usuários do Vim Instant-Markdown precisam usar

  

Para o pandoc, uma boa maneira de bloquear comentários é usar um yaml metablock, como sugerido pelo autor do pandoc . Tenho notado que isso dá um realce de syntax mais adequado dos comentários em comparação com muitas outras soluções propostas, pelo menos no meu ambiente ( vim , vim-pandoc e vim-pandoc-syntax ).

Eu uso os comentários do bloco yaml em combinação com os comentários em linha do html , já que os comentários html não podem ser nesteds . Infelizmente, não há como bloquear comentários dentro do yaml metablock , então cada linha deve ser comentada individualmente. Felizmente, deve haver apenas uma linha em um parágrafo suavizado.

No meu ~/.vimrc , eu configurei atalhos personalizados para comentários de bloco:

 nmap b }oO...{ji#O---2 nmap v {jddx}kdd 

Eu uso , como o meu -key, assim ,b e ,v comentar e descomentar um parágrafo, respectivamente. Se eu precisar comentar vários parágrafos, mapeario j,b para uma macro (geralmente Q ) e executarei (por exemplo, ( 3Q ). O mesmo funciona para descomentar.

kramdown – o mecanismo de remarcação baseado em Ruby que é o padrão para o Jekyll e, portanto, para o GitHub Pages – tem suporte a comentários embutidos através de sua syntax de extensão :

 {::comment} This text is completely ignored by kramdown - a comment in the text. {:/comment} Do you see {::comment}this text{:/comment}? {::comment}some other comment{:/} 

Isso tem o benefício de permitir comentários em linha, mas a desvantagem de não ser portável para outros mecanismos do Markdown.

Podes tentar

 []( Your comments go here however you cannot leave // a blank line so fill blank lines with // Something )