Commenti in Markdown

Qual è la sintassi per la memorizzazione di un commento in un file markdown, ad esempio un commento CVS $ Id $ nella parte superiore del file? Non ho trovato nulla nel progetto markdown .

Ritengo che tutte le soluzioni precedentemente proposte (tranne quelle che richiedono implementazioni specifiche) comportino l'inclusione dei commenti nell'HTML di output, anche se non vengono visualizzati.

Se vuoi un commento che sia strettamente per te (i lettori del documento convertito non dovrebbero essere in grado di vederlo, anche con "visualizza sorgente") potresti (ab) usare le etichette dei collegamenti (da usare con i collegamenti di stile di riferimento) che sono disponibile nelle specifiche core Markdown:

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

Questo è:

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

Oppure potresti andare oltre:

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

Per migliorare la compatibilità della piattaforma (e salvare una sequenza di tasti) è anche possibile utilizzare #(che è un target di collegamento ipertestuale legittimo) invece di <>:

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

Per la massima portabilità è importante inserire una riga vuota prima e dopo questo tipo di commenti, poiché alcuni parser Markdown non funzionano correttamente quando le definizioni vengono rimosse con il testo normale. La ricerca più recente con Babelmark mostra che le righe vuote prima e dopo sono entrambe importanti. Alcuni parser genereranno il commento se prima non ci sono righe vuote e alcuni parser escluderanno la riga seguente se non ci sono righe vuote dopo.

In generale, questo approccio dovrebbe funzionare con la maggior parte dei parser Markdown, poiché fa parte delle specifiche di base. (anche se il comportamento quando sono definiti più collegamenti o quando un collegamento è definito ma mai utilizzato, non è specificato).

Uso tag HTML standard, come

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

Nota il trattino triplo. Il vantaggio è che funziona con pandoc durante la generazione di output TeX o HTML. Ulteriori informazioni sono disponibili sul gruppo di discussione pandoc .

Questa piccola ricerca dimostra e affina la risposta di Magnus

La sintassi più indipendente dalla piattaforma è

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

Entrambe le condizioni sono importanti:

1. Usare #(e non <>)
2. Con una riga vuota prima del commento . La riga vuota dopo il commento non ha alcun impatto sul risultato.

La specifica rigorosa Markdown CommonMark funziona solo come previsto con questa sintassi (e non con <>eo una riga / vuoto)

Per dimostrarlo utilizzeremo Babelmark2, scritto da John MacFarlane. Questo strumento controlla il rendering di un particolare codice sorgente in 28 implementazioni Markdown.

( +- superato il test, -- non superato, ?- lascia un po 'di immondizia che non viene mostrato in HTML renderizzato).

• Nessuna riga vuota, usando<> 13+, 15-
• Riga vuota prima del commento, usando<> 20+, 8-
• Linee vuote attorno al commento, usando<> 20+, 8-
• Nessuna linea vuota, usando# 13+ 1? 14-
• Riga vuota prima del commento, usando # 23+ 1? 4-
• Linee vuote attorno al commento, usando# 23+ 1? 4-
• Commento HTML con 3 trattini 1+ 2? 25- dalla risposta del chl (nota che questa è una sintassi diversa)

Ciò dimostra le affermazioni di cui sopra.

Queste implementazioni falliscono tutti e 7 i test. Non c'è alcuna possibilità di utilizzare i commenti esclusi nel rendering con loro.

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

Se stai usando Jekyll o octopress, funzionerà anche il seguente.

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

I tag Liquid {% comment %}vengono prima analizzati e rimossi prima che anche il processore MarkDown riesca ad accedervi. I visitatori non vedranno quando provano a visualizzare la fonte dal loro browser.

Un'alternativa è inserire commenti all'interno di tag HTML stilizzati. In questo modo, puoi attivare la loro visibilità secondo necessità. Ad esempio, definisci una classe di commenti nel tuo foglio di stile CSS.

.comment { display: none; }

Quindi, il seguente MARKDOWN migliorato

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

appare come segue in un BROWSER

We do support comments

Questo funziona su GitHub:

[](Comment text goes here)

Il codice HTML risultante è simile a:

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

Che è fondamentalmente un link vuoto. Ovviamente puoi leggerlo nella fonte del testo renderizzato, ma puoi farlo comunque su GitHub.

Gli utenti di Vim Instant-Markdown devono utilizzare

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

Vedi anche Critic Markup, supportato da un numero crescente di strumenti 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.

Che ne dici di mettere i commenti in un blocco R non-valutazione, non-eco? vale a dire,

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

Sembra funzionare bene per me.

Divulgazione: ho scritto il plugin.

Poiché la domanda non specifica un'implementazione specifica di markdown, vorrei menzionare il plug -in Commenti per python-markdown , che implementa lo stesso stile di commento pandoc menzionato sopra.

<!--- ... --> 

Non funziona in Pandoc Markdown (Pandoc 1.12.2.1). I commenti sono ancora apparsi in html. Di seguito ha funzionato:

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

Quindi utilizzare l'estensione + nota a piè di pagina. È essenzialmente una nota a piè di pagina a cui non viene mai fatto riferimento.

Quanto segue funziona molto bene

<empty line>
[whatever comment text]::

quel metodo sfrutta la sintassi per creare collegamenti tramite riferimento
poiché il riferimento di collegamento creato con [1]: http://example.orgnon verrà reso, allo stesso modo anche uno dei seguenti non verrà reso

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

Per pandoc, un buon modo per bloccare il commento è usare un metablock yaml, come suggerito dall'autore pandoc . Ho notato che questo dà più adeguata evidenziazione della sintassi dei commenti rispetto a molte delle altre soluzioni proposte, almeno nel mio ambiente ( vim, vim-pandoc, e vim-pandoc-syntax).

Uso i commenti di blocco yaml in combinazione con i commenti html-inline, poiché i commenti html non possono essere nidificati . Sfortunatamente, non c'è modo di bloccare i commenti all'interno del metablock di yaml , quindi ogni riga deve essere commentata singolarmente. Fortunatamente, ci dovrebbe essere solo una riga in un paragrafo a capo morbido.

Nel mio ~/.vimrc, ho impostato scorciatoie personalizzate per i commenti di blocco:

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

Io uso ,il mio <Leader>tasto, quindi ,be ,vcommento e rimuovere il commento di un paragrafo, rispettivamente. Se ho bisogno di commentare più paragrafi, mi associo j,ba una macro (di solito Q) ed eseguo <number-of-paragraphs><name-of-macro>(ad esempio ( 3Q). Lo stesso vale per il commento.

kramdown - il motore di markdown basato su Ruby che è l'impostazione predefinita per Jekyll e quindi GitHub Pages - ha il supporto commenti incorporato attraverso la sua sintassi di estensione :

{::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{:/}

Ciò ha il vantaggio di consentire commenti in linea, ma il rovescio della medaglia è di non essere portatile con altri motori Markdown.

Puoi provare

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

Puoi farlo (blocco YAML):

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

Ho provato solo con output in lattice, per favore conferma per altri.