Markdown - Tradução para Português do Respectivo Manual

Introdução

Markdown é uma ferramenta de conversão de texto para HTML para produtores de conteúdos para a web. Markdown permite-lhe escrever em formato de texto fácil de ler e fácil de escrever que depois é convertido para XHTML (ou HTML) estruturalmente válido.

Assim, "Markdown" é duas coisas: (1) uma síntaxe de formatação em forma textual e (2) uma ferramenta de software, escrita em Perl, que converte o texto assim formatado em HTML. Ver a entrada sobre Síntaxe para detalhes relativos à sintaxe de formatação de Markdown. Pode experimentá-la usando o sítio on-line Dingus.

O objectivo principal da concepção da Markdown é fazê-la tão legível quanto possível. A ideia é que um documento formatado com Markdown possa ser publicado tal como é, como texto puro, sem que pareça ter sido marcado com marcadores ou instruções de formatação. Embora a síntaxe de Markdown tenha influenciado vários filtros texto para HTML existentes, a maior fonte de inspiração da Markdown é o formato da mensagem de correio em texto puro.

A forma de sentir a síntaxe de formatação Markdown é simplesmente olhar para um documento formatado com Markdown. Por exemplo, pode ver a versão original (em inglês) com Markdown deste artigo nesta página aqui:http://daringfireball.net/projects/markdown/index.text.

Markdown é software livre, disponível sob uma licença do tipo BSD open source. Se gostar de usar Markdown, por favor considere fazer uma pequena contribuição para desenvolvimento adicional. Ver a página da Licença (em inglês) para mais informação.

Panorâmica

• Filosofia
  

  O fundamento da Markdown é ser fácil de escrever e fácil de ler.

  A legibilidade é, contudo, enfatizada acima de qualquer outra coisa. Um texto formatado com Makdown deve poder ser publicado tal como está, como texto puro, sem que pareça ter sido marcado com marcadores ou instruções de formatação. Embora a síntaxe da Markdown tenha influenciado vários filtros existentes de texto para HTML - incluindo Setext, atx, Textile, reStructuredText, Grutatext e EtText - a principal fonte de inspiração para a síntaxe de Markdown é o formato de mensagem de correio em texto puro.

  
  

  Com esta finalidade, a síntaxe de Markdown é completamernte constituída por caracteres de pontuação cuidadosamente escolhidos para parecerem aquilo que significam. Isto é, os asteríscos à volta de uma palavra de facto parecem dar-lhe *enfâse*. As listas em Markdown parecem-se com listas. Mesmo blocos de citações parecem-se com passagens de texto citado, desde que tenha usado e-mail.

  
  

  HTML em Linha

  
  

  A síntaxe da Markdown pretende ter uma só finalidade: ser usada como formatação na escrita para a web.

  
  

  Markdown não é um substituto do HTML ou algo perto disso. A sua síntaxe é muito pequena, correspondendo a um sub-conjunto muito pequeno dos marcadores de HTML. Na minha opinião os marcadores de HTML são fáceis de inserir. A ideia de Markdown é ser fácil de ler, escrever e alterar prosa. o HTML é um formato de publicação, o Markdown é um formato de escrita. Assim a síntaxe de formatação de Markdown só trata das questões que podem ser transmitidas em texto puro.

  
  

  Para marcação que não seja coberta pela síntaxe de Markdown, terá que simplesmente inserir o respectivo HTML por si mesmo. Não há necessidade de o prefaciar ou delimitar para indicar que está a comutar de Markdown para HTML e vice versa, use simplesmente os respectivos marcadores.

  
  

  A única restrição é que os elementos de blocos em HTML - isto é, <div>, <table>, <pre>, <p>, etc - devem ser separados do conteúdo que os rodear por linhas em branco e que o abertura e fecho do marcador do bloco não sejam recortados usando tabulação ou espaços. A Markdown é suficientemente inteligente para não adicionar marcadores <p> extras (indesejados) à volta de marcadores de nível de bloco em HTML.

  
  

  Por exemplo, para adicionar uma tabela HTML a um artigo em Markdown basta:

  
  
  

  ------------------------------------------
       Isto é um parágrafo normal em Markdown.
       
       <table>
         <tr>
           <td>Só para efeito de demonstração</td>
         </tr>
       </table>
       
       Isto é mais um parágrafo normal.
       -----------------------------------------------
       

  
  
  

  Note-se que a síntaxe de formatação Markdown não é processada dentro de marcadores HTML de nível de bloco, isto é não pode usar o estilo de *enfatização* de Markdown dentro de um bloco HTML.

  
  

  Marcadores de HTML de nível em linha - isto é &tl;span>, &tl;cite> ou &tl;del> - podem ser usados em qualquer lado apropriado em Markdown isto é em: parágrafos, itens de lista ou cabeçalhos. Se desejar pode se preferir usar os marcadores HTML <a> ou <img> em vez da síntaxe para ligações ou imagens em Markdown.

  
  

  Ao contrário do que sucede nos marcadores de nível de bloco do HTML a síntaxe Markdown é processada dentro de marcadores de nível em linha.

  
  

  Escape automático para caracteres especiais

  
  

  Em HTML, há dois caracteres que necessitam de tratamento especial: < e &. O caracter de menor que é usado na abertura de um marcador e o e comercial é usado para identificar entidades HTML. Se desejar usar os mesmos como caracteres literais necessita de os fazer escapar como entidades isto é &lt; e &amp;.

  
  

  Os e comerciais são particularmente desagradáveis para com os ecritores da web. Se desejar escrever sobre a "AT&T" necessita escrever algo como "AT&amp;T". Também necessita de escapar os e comerciais que surjam em URL. Assim se desejar ligar-se a:

  
  

  
   http://images.google.com/images?num=30&q=larry+bird
   

  
  

  Necessitará de codificar esse URL como:
  

  
   http://images.google.com/images?num=30&q=larry+bird
    

  
  
  

  no atributo href do sua âncora. Falta ainda dizer, que isto é fácil de esquecer, e é uma das principais razões para ocorrerem erros de validação de HTML em sítios normalmente com marcação correcta.

  
  

  Markdown permite-lhe usar estes caracteres de forma natural tratando de os escapar por si. Se usar um e comercial como parte de uma entidade HTML, ele mantêm-se inalterado, caso contrário é traduzido como &amp;.

  
  

  Assim se desejar incluir o símbolo de direitos autorais num artigo pode escrever:
  

  &copy

  
  

  e o Markdown não lhe tocará. No entanto se escrever:

  
  

  AT&T

  
  

  Markdown tratará de o traduzir como AT&amp;T.

  
  

  Visto Markdown suportar HTML em linha se usar um sinal de menor que como delimitador de marcador HTML, o Markdown irá traá-lo como tal. Mas se escrever algo similar a:

  
  

  4 < 5

  
  

  Markdown irá traduzí-lo como:

  
  

  4 < 5

  
  

  Contudo dentro de span e blocos em código Markdown, sinais de maior e menor que e e comercial são sempre codificados automaticamente. Isto simplifica o uso de Markdown para escrever sobre código HTML. (Em oposição ao HTML puro, que é um formato terrível para escrever-se sobre síntaxe HTML, visto cada simples < e cada & nos exemplos de código terem de ser escapados.)




• Elementos de Bloco