Comentários em Markdown


1402

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


10
Lendo nas entrelinhas, parece que você deseja anexar metadados ao seu Markdown. Por esse motivo, sugiro usar um pré-processador que permita adicionar um cabeçalho. Para um exemplo, consulte Front Matter de Jekyll . Para outro exemplo, veja como o Basho usa o Middleman para sua documentação . (Nota: Esta não é uma resposta direta à pergunta, o que é por isso que estou compartilhando-o como um comentário.)
David J.


Aqui está uma referência de diferentes tipos de comentários com diferentes analisadores no Babelmark .
Ulysse BN

Respostas:


1456

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 não sejam exibidos.

Se você deseja um comentário estritamente para si mesmo (os leitores do documento convertido não devem poder vê-lo, mesmo com a "fonte de visualização"), você pode (ab) usar os rótulos dos links (para uso com os links de estilo de referência) que são disponível na especificação principal do Markdown:

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ê pode ir além:

[//]: <> (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 máxima portabilidade, é importante inserir uma linha em branco antes e depois desse tipo de comentário, porque alguns analisadores do Markdown não funcionam corretamente quando as definições se encaixam no texto comum. A pesquisa mais recente com a Babelmark mostra que as linhas em branco antes e depois são importantes. Alguns analisadores produzirão o comentário se não houver uma linha em branco antes, e alguns analisadores excluirão a seguinte linha se não houver uma linha em branco depois.

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


145
[//]: # "Comment"e [//]: # (Comment)parece funcionar em uma variedade mais ampla de implementações, porque #é um URI relativo válido. O GitHub, por exemplo, rejeita <>e a linha inteira fica visível. Também é importante notar que os rótulos dos links geralmente precisam ser separados de outro conteúdo por uma linha em branco.
Zenexer

6
Para ser mais independente de plataforma, também precisa de uma linha vazia antes do comentário. Veja os testes: stackoverflow.com/a/32190021/2790048
Nick Volynkin

6
Isso pode ser usado para comentários de várias linhas?
crypdick

4
@RovingRichard Sim, pelo menos no Pandoc, isso funciona para comentários com várias linhas, se não houver linhas em branco no bloco comentado (quebras de linha únicas são boas). Eu uso a abordagem de Magnus para comentários em bloco e a abordagem HTML de chl para comentários em linha (embora geralmente apenas 2 traços). Dessa forma, posso bloquear os parágrafos de comentários que já contenham comentários em HTML embutidos.
Joelostblom 02/03

4
Apenas para sua informação, mas se você estiver criando um sumário usando Pandoc, isso gerará um aviso sobre referências de links duplicadas. (Estes são apenas avisos, o sumário ainda será criado).
Karl Giesing

995

Eu uso tags HTML padrão, como

<!---
your comment goes here
and here
-->

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


73
Se bem entendi, o traço triplo faz com que o pandoc ignore o comentário ao analisar o arquivo de remarcação. Mas se você usar outro mecanismo de remarcação, o comentário aparecerá no HTML gerado (e, portanto, ficará visível em "visualizar código-fonte"). Então você tem que ter cuidado com o que você colocar em que o comentário;)
cberzan

5
Você pode explicar como Pandoc trata os traços triplos de maneira diferente do duplo? Quando eu experimentei com eles, eles pareciam ser tratados da mesma maneira. Além disso, o guia do usuário da Pandoc apenas diz "O HTML bruto é passado inalterado nas saídas HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown e Textile, e suprimido em outros formatos". Os traços triplos não parecem ter privilégios mais altos que os duplos.
DKIM

1
@dkim Comentários com traço triplo são ignorados e descartados da saída HTML. Esse não é o caso dos comentários de traço duplo inseridos no arquivo HTML. Este ainda é o caso da versão mais recente do Pandoc (1.10).
chl

32
Se o traço triplo for significativo, não serão comentários "HTML padrão".
Tripleee

17
Nota para os Googlers: isso infelizmente não funciona no GitHub Markdown, e acabei usando a solução da Magnus.
Daniel Buckmaster

198

Esta pequena pesquisa prova e refina a resposta de Magnus

A sintaxe 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 . A linha vazia após o comentário não tem impacto no resultado.

A especificação estrita do Markdown CommonMark funciona apenas como pretendido com esta sintaxe (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 um código-fonte específico em 28 implementações do Markdown.

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

Isso prova as afirmações acima.

Essas implementações falham em todos os 7 testes. Não há chance de usar comentários excluídos na 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)

3
Excelente, ferramenta de teste completa! Parece que você está certo que # funciona para todos, exceto o GFM e <> funciona para o GFM, mas não para alguns outros. Pena que a GFM é uma caixa de canto e também um sabor muito popular.
hobs

1
Parece que s9e \ TextFormatter funciona em # 21 de janeiro de 2016. O Cebe ainda não lida com isso.
Troy Daniels

1
Estranhamente, se o comentário contém (...)por si só, ele o quebra. Pelo menos no Visual Studio Code 1.19.
Royi

1
e, portanto, para os usuários do vim que desejam comentar todos os arquivos de uma vez:%s/^\(.*\)$/[comment]: # (\1)/g
Simon C.

O que diz sobre a redução de preço que o Bablemark2 existe?
TC Proctor

54

Se você estiver usando 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 que o processador MarkDown chegue até elas. Os visitantes não verão quando tentarem visualizar a fonte do navegador.


2
Jinja2 = {#comentários multilinhas aqui#}
John Mee

29

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

.comment { display: none; }

Em seguida, o seguinte MARKDOWN aprimorado

We do <span class="comment">NOT</span> support comments

aparece da seguinte maneira em um NAVEGADOR

We do support comments


5
Copiar / colar provavelmente acabará copiando o texto "comentado" e o texto normal, portanto, tenha cuidado ao usá-lo. Poderia facilmente produzir resultados inesperados para alguém copiar um bloco de texto.
Eilon

4
@Eilon também a acessibilidade para isso seria terrível
Ethan

Os mecanismos de suporte à acessibilidade ignoram corretamente a exibição: nenhum texto.
aredridel

28

Isso funciona no GitHub:

[](Comment text goes here)

O HTML resultante se parece com:

<a href="Comment%20text%20goes%20here"></a>

O que é basicamente um link vazio. Obviamente, você pode ler isso na fonte do texto renderizado, mas pode fazê-lo no GitHub de qualquer maneira.


6
Definitivamente é, mas na verdade é a única resposta até agora que sempre funciona no GitHub, por exemplo, em listas.
jomo

Cheguei à mesma solução. É o único que posso trabalhar para comentários em linha, por exemplo some text [](hidden text) blah blah.
C24w

3
Isso não funciona mais no github a partir de 2019/03/08, ele processa como é[](Comment text goes here)
dogmatic69

19

Os usuários do Vim Instant-Markdown precisam usar

<!---
First comment line...
//
_NO_BLANK_LINES_ARE_ALLOWED_
//
_and_try_to_avoid_double_minuses_like_this_: --
//
last comment line.
-->

18

Consulte também Marcação crítica, suportada 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.

5
Eu acho que um dos problemas com esses "pseudo" padrões é que eles não são portáteis. Em alguns sites, eles funcionam perfeitamente; em outros, não.
Willem Van Onsem

14

Que tal colocar os comentários em um bloco R sem avaliação e sem eco? ou seja,

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

Parece funcionar bem para mim.


2
Além disso, sinta-se à vontade para fazer coisas como cat("# Some Header")nos blocos de código "comentados" e usá results = "asis"-los, e você pode adicionar seções inteiras comentadas ao seu código que podem ser ativadas / desativadas alternando eval = FALSE, pois a avaliação R é feita antes do compilação pandoc. Obrigado pela ideia!
22416 MichaelChirico


11
<!--- ... --> 

Não funciona no Pandoc Markdown (Pandoc 1.12.2.1). Os comentários ainda apareceram 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.


Eu gosto mais disso porque não gera nenhuma saída. Para Bitbucket este prefixo é suficiente: [#]: .
ceving 02/03

7

O seguinte funciona muito bem

<empty line>
[whatever comment text]::

esse método aproveita a sintaxe para criar links por referência,
já que a referência de link criada com [1]: http://example.orgnão será renderizada, da mesma forma, qualquer um dos itens a seguir também não será renderizado

<empty line>
[whatever]::
[whatever]:whatever
[whatever]: :
[whatever]: whatever

Essa (primeira variante testada) funciona para pandocinstâncias on-line atuais do Gitlab e GitHub .
doak

5

Para o pandoc, uma boa maneira de bloquear o comentário é usar um metamock do yaml, conforme sugerido pelo autor do pandoc . Tenho notado que isto dá destaque de sintaxe mais adequada das observações em relação a muitas das outras soluções propostas, pelo menos no meu ambiente ( vim, vim-pandoc, e vim-pandoc-syntax).

Eu uso comentários do bloco yaml em combinação com comentários html-inline, pois os comentários html não podem ser aninhados . Infelizmente, não há como bloquear comentários no metablock yaml , portanto, cada linha deve ser comentada individualmente. Felizmente, deve haver apenas uma linha em um parágrafo compactado.

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

nmap <Leader>b }o<Esc>O...<Esc>{ji#<Esc>O---<Esc>2<down>
nmap <Leader>v {jddx}kdd

Eu uso ,como meu <Leader>tecla, de modo ,be ,vcomentário e parágrafo a uncomment, respectivamente. Se eu precisar comentar vários parágrafos, mapeio j,bpara uma macro (geralmente Q) e corro <number-of-paragraphs><name-of-macro>(por exemplo ( 3Q)). O mesmo funciona para descomentar.


5

O kramdown - o mecanismo de marcação baseado em Ruby que é o padrão para o Jekyll e, portanto, o GitHub Pages - possui suporte a comentários interno por meio da sintaxe 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átil para outros mecanismos Markdown.


4

Podes tentar

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

4

Você pode fazer isso (bloco YAML):

~~~
# This is a
# multiline
# comment
...

Tentei apenas com saída de látex, confirme para os outros.


Também funciona com saída HTML.
precisa saber é

Não tenho certeza se a confirmação de Daniel da saída html está correta. Fiz isso com um arquivo de saída html e executei "pandoc --bibliography paper.bib -o paper.html paper.md" e o HTML mostrou as linhas de comentário.
markgalassi 11/03
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.