Comentários em Markdown

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 .

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

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 .

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

• Não há linhas vazias, usando<> 13+, 15-
• Linha vazia antes do comentário, usando<> 20+, 8-
• Linhas vazias ao redor do comentário, usando<> 20+, 8-
• Não há linhas vazias, 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 sintaxe diferente)

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)

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.

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

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.

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

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.

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.

Divulgação: escrevi o plugin.

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

<!--- ... --> 

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.

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

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.

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.

Podes tentar

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

Você pode fazer isso (bloco YAML):

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

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