Imprime Markdown com elegância

A forma mais rápida de experimentar o mdprint é começar a escrever no editor na página inicial. Carrega com um documento de exemplo que exercita todas as funcionalidades - tabelas, código, matemática, diagramas - para veres imediatamente como fica uma página acabada. Apaga o exemplo e escreve o teu próprio conteúdo, ou cola-o de onde quer que o tenhas escrito.

Se já tens um ficheiro Markdown no teu computador, tens duas formas de o carregar. A primeira é arrastá-lo do gestor de ficheiros e largá-lo no painel do editor. Aparecerá um destaque à volta da zona de largar enquanto arrastas. Solta o ficheiro e o editor enche-se com o seu conteúdo. A segunda é clicar no botão Importar na barra de ferramentas e selecionar o ficheiro no seletor. Ambos os métodos leem o ficheiro localmente - nada é enviado.

O mdprint aceita ficheiros .md, .markdown e .txt. A extensão .txt é útil para documentos escritos em Markdown mas guardados com uma extensão genérica por outra ferramenta. Se tentares importar um ficheiro com outra extensão, o mdprint mostrará um erro e deixará o teu conteúdo atual intacto.

Se nunca escreveste Markdown, as regras são poucas o suficiente para aprenderes em cinco minutos. Escreves texto simples e quatro caracteres fazem a maior parte do trabalho. O símbolo # no início de uma linha cria um título - um # para o maior, seis ###### para o menor. Os símbolos * e _ à volta de uma palavra põem-na em itálico com um de cada lado e em negrito com dois. O símbolo - ou * no início de uma linha cria um tópico. Recua dois espaços para aninhar um tópico debaixo de outro.

O código é tratado com aspas invertidas. Uma aspa invertida de cada lado de uma frase formata-a como `código inline`. Três aspas invertidas numa linha sozinha iniciam um bloco de código e mais três fecham-no. Se puseres um nome de linguagem logo a seguir às três aspas invertidas de abertura (```python, ```typescript, ```sql), o bloco de código recebe realce de sintaxe nessa linguagem. Sem indicação de linguagem, o realçador tenta adivinhar a partir do conteúdo, o que costuma funcionar para linguagens populares.

Ligações e imagens usam ambos parênteses retos e parênteses. Uma ligação é [o texto que vês](o URL). Uma imagem é a mesma coisa com um ponto de exclamação à frente: . Quando imprimes para PDF, os URLs de imagens que apontam para servidores acessíveis publicamente serão obtidos e embutidos. Imagens na tua máquina local ou atrás de autenticação não serão renderizadas - larga-as diretamente no editor como URLs de dados base64 se precisares delas inline.

Tabelas são a única parte do Markdown que parece chata na fonte mas renderiza de forma limpa. Uma linha de cabeçalho, uma linha separadora de traços, e uma ou mais linhas de dados, todas separadas por barras. As colunas não precisam de estar alinhadas na fonte - o renderizador trata do espaçamento. Adiciona dois pontos a uma ou ambas as pontas dos traços na linha separadora para controlar o alinhamento: :--- para esquerda, ---: para direita, :---: para centrado.

Equações matemáticas usam sintaxe TeX entre cifrões. Um cifrão simples de cada lado dá-te matemática inline: $a^2 + b^2 = c^2$. Dois cifrões em linhas próprias dão uma equação em display, centrada na sua própria linha e maior. Todos os comandos matemáticos LaTeX que esperarias - \frac, \int, \sum, \sqrt, letras gregas, matrizes, o conjunto de símbolos AMS - funcionam porque o mdprint usa KaTeX, que implementa a mesma sintaxe.

Diagramas usam sintaxe Mermaid dentro de um bloco de código delimitado com a etiqueta de linguagem mermaid. O diagrama mais simples é um fluxograma: abre com graph LR (esquerda para a direita) ou graph TD (de cima para baixo), depois escreve nós ligados por setas. O Mermaid também suporta diagramas de sequência (fluxo de mensagens entre atores ao longo do tempo), gráficos de Gantt (cronogramas de projetos com dependências), diagramas de classe (relações entre objetos) e diagramas de estado (máquinas de estados). A documentação do Mermaid tem exemplos para cada tipo.

As notas de rodapé permitem manter a prosa legível enquanto anexas citações detalhadas ou apartes. Marca uma nota no teu texto com [^1] (o número pode ser qualquer um - são renumeradas na saída). Algures no documento, define a nota com [^1]: o conteúdo da nota. O mdprint reúne todas as notas no fim do documento impresso e adiciona referências de volta que ligam cada nota ao local onde aparece no texto.

Se o teu documento é longo, deixa o texto literal [[toc]] na fonte onde queres que apareça um índice. O mdprint substitui-o por uma lista aninhada de ligações para cada H2 e H3 no documento. No PDF impresso, esse mesmo índice torna-se um esquema de navegação que os leitores de PDF podem usar.

Abre o painel de Definições a partir da barra de ferramentas para controlar como o teu PDF é gerado. O tamanho de página tem duas opções: A4 (padrão fora da América do Norte) ou Letter (padrão na América do Norte). A orientação alterna entre vertical e horizontal - horizontal é útil para documentos com tabelas ou diagramas largos. As margens oferecem três predefinições: estreitas dão mais área útil para conteúdo denso, normais são o meio-termo convencional e largas deixam espaço para anotações manuscritas numa cópia impressa.

O editor tem os seus próprios temas claro e escuro, independentes do resto da página. O interruptor na barra de ferramentas alterna entre eles. A pré-visualização e a saída impressa permanecem no modo claro em qualquer caso, porque fundos claros é o que imprime bem em papel.

Se usas regularmente o mesmo conjunto de opções, a tua última seleção é lembrada localmente e aplicada automaticamente da próxima vez que abrires o mdprint no mesmo navegador.

O botão Imprimir abre o diálogo de impressão nativo do teu navegador. A partir daí, todos os sistemas operativos modernos oferecem Guardar como PDF como destino - Chrome, Firefox, Safari e Edge suportam-no em macOS, Windows e Linux. Passar pelo diálogo de impressão dá-te o máximo de controlo: podes escolher qualquer impressora, pré-visualizar cada página, mudar a orientação por página se o teu controlador permitir e, em algumas impressoras, mudar tabuleiros de papel ou agrafagem.

O botão Descarregar PDF salta o diálogo de impressão e gera um ficheiro PDF diretamente no navegador, depois aciona uma descarga. Usa as tuas Definições atuais (tamanho de página, orientação, margens) para formatar a saída. Esta via é mais rápida quando sabes exatamente o que queres e não precisas da flexibilidade do diálogo de impressão. Funciona renderizando a página como uma imagem de alta resolução e colocando essa imagem no PDF, por isso o resultado corresponde sempre ao que vês no ecrã. O compromisso: como a página passa a ser uma imagem, o texto neste PDF não é selecionável nem pesquisável.

As duas vias diferem no que acaba dentro do ficheiro. Guardar como PDF, através do botão Imprimir, mantém o texto como texto: continua selecionável e pesquisável, fica nítido em qualquer zoom e os diagramas mantêm-se vetoriais. Já Descarregar PDF é um instantâneo de imagem com um clique, por isso é rápido e exato ao pixel, mas o texto não é selecionável. Usa Guardar como PDF quando queres texto selecionável ou o resultado mais nítido em qualquer zoom; usa Descarregar PDF quando queres apenas uma cópia rápida e exata do que está no ecrã sem abrir o diálogo de impressão.

Quebras de página em locais estranhos. O mdprint evita quebrar dentro de blocos de código, tabelas e diagramas, mas não tenta adivinhar na prosa. Se um título cair no fundo de uma página com o conteúdo da secção na seguinte, a solução mais fácil é acrescentar algumas frases antes ou depois para empurrar o título. Não há sintaxe manual de quebra de página em V1 - acrescentá-la está na lista V2.

As imagens não aparecem no PDF. A causa mais comum é um URL de imagem que aponta para o teu sistema de ficheiros local (file://) ou para um servidor que não permite acesso cross-origin. Embute a imagem como URL de dados diretamente na fonte Markdown ou envia-a para um alojamento de imagens que permita leitura pública. Imgur, os servidores user-content do GitHub e a maioria dos CDN funcionam.

A matemática não renderiza. Verifica a fonte por cifrões não escapados em texto normal - um $ perdido pode iniciar uma zona matemática que engole o resto do parágrafo. Se precisas de um cifrão literal na prosa, escapa-o: \$. Se a sintaxe matemática está correta mas a equação ainda não renderiza, o comando LaTeX pode não estar na lista suportada do KaTeX - a documentação do KaTeX tem uma referência completa.

O diagrama está em branco. O Mermaid é estrito quanto à sintaxe. Os erros mais comuns são um espaço em falta após graph LR, um identificador de nó com um espaço (usa camelCase ou underscores) ou uma seta a apontar para um nó indefinido. Abre a consola de programador do teu navegador - o Mermaid regista uma mensagem de erro específica quando a análise falha.

As tabelas envolvem de forma estranha. Se uma tabela é mais larga do que a página, o mdprint reduzirá a escala para caber. Para tabelas muito largas, muda para orientação horizontal nas Definições, ou reestrutura a tabela como lista. O PDF não lida com scroll horizontal como a web.

Usa os atalhos de teclado. Cmd+P (ou Ctrl+P no Windows e Linux) abre o diálogo de impressão. Cmd+S (Ctrl+S) aciona Descarregar PDF. Os próprios atalhos do navegador para procurar (Cmd+F), recarregar (Cmd+R) e zoom (Cmd+mais/menos) funcionam todos normalmente - não entram em conflito com o mdprint.

Começa cada documento com um H1. O primeiro H1 torna-se no nome de ficheiro PDF sugerido, no título do documento para acessibilidade e no título proeminente no topo da página impressa. Se começares com H2 ou inferior, o nome do ficheiro recai para 'document.pdf' e terás de o renomear manualmente depois da descarga.

Embute imagens como URLs de dados quando a privacidade importa. Se não quiseres que um leitor de PDF vá buscar imagens a um servidor remoto ao abrir o teu ficheiro, converte a imagem para URL de dados base64 e embute-a diretamente. A maioria dos sistemas operativos tem uma ferramenta integrada ou específica para esta conversão. O ficheiro resultante é maior, mas totalmente autocontido.

Usa listas de tarefas para checklists impressas. Se produzes uma checklist em papel - lista de bagagem, lista de envio, procedimento passo a passo - usa a sintaxe de listas de tarefas do Markdown com - [ ]. As caixas imprimem como quadrados que podes assinalar com uma caneta.

Combina mermaid e código em documentação técnica. Um padrão comum é mostrar um fluxograma de um processo, seguido do código real que o implementa. O Markdown deixa fazer ambos no mesmo ficheiro, e o mdprint renderiza-os de uma forma que imprime limpamente lado a lado.

Cmd+P ou Ctrl+P - abrir o diálogo de impressão.

Cmd+S ou Ctrl+S - descarregar como PDF.

Cmd+B ou Ctrl+B dentro do editor - pôr em negrito o texto selecionado.

Cmd+I ou Ctrl+I dentro do editor - pôr em itálico o texto selecionado.

Cmd+/ ou Ctrl+/ dentro do editor - alternar comentário para a linha atual (comentário HTML em contexto Markdown).

Esc dentro do editor em ecrã inteiro - sair do ecrã inteiro.