> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/overleaf-learn-latex-pt/artigos-aprofundados/30-how-to-write-in-markdown-on-overleaf.md).
# Como escrever em Markdown no Overleaf
**Atualização pós-publicação** (adicionado em 13 de maio de 2017): Somos gratos a Vít Novotný, o autor/mantenedor do `markdown` pacote, por nos escrever com alguns comentários úteis sobre o artigo original. Temos o prazer de publicar esta versão atualizada, que toma nota de, e inclui, os seus conselhos e sugestões.
### Hã, o quê?
[Markdown](https://kirkstrobeck.github.io/whatismarkdown.com/) é uma linguagem de marcação leve (percebeu? 😉) que permite escrever algo em texto simples com algumas *muito* regras simples e depois transformá-lo em saídas formatadas, por ex., HTML. É muito popular entre desenvolvedores de software e programadores, justamente por causa da sua simplicidade (e, diga-se, também é perfeita para tomar notas!).
Por exemplo, para escrever rapidamente uma lista de compras:
```
# Lista de compras
*Lembre-se* de trazer o máximo que pudermos durante as próximas [promoções](http://acme-marg.com)!
## Comida
- feijão cozido
- esparguete
## Papelaria
- bloco de notas
- lápis
```
E obterá como saída HTML, usando uma ferramenta como [pandoc](http://pandoc.org/):
```html
Lista de compras
Lembre-se de trazer o máximo que pudermos durante as próximas promoções!
Comida
Papelaria
```
Simples e fácil! Pode encontrar outra sintaxe para o Markdown [aqui](https://daringfireball.net/projects/markdown/syntax).
### Então o que é que isto significa para mim?
Muitos utilizadores de LaTeX ficam satisfeitos com os seus belos documentos compostos em LaTeX, mas não conseguem evitar sentir uma ponta de inveja dos utilizadores de Markdown — porque, bem, a marcação LaTeX *pode* pode tornar-se bastante verbosa por vezes. Sim, listas, estamos a olhar para *vocês*...
A boa notícia é que o fantástico novo [`markdown` pacote LaTeX](https://ctan.org/pkg/markdown) permite escrever sintaxe Markdown nos seus documentos LaTeX (ou seja, entradas mais simples) e ainda assim obter PDFs lindamente compostos! Basta carregar o `markdown` pacote no seu documento e envolver o seu material Markdown dentro de um `markdown` ambiente:
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\begin{markdown}
# Lista de compras
*Lembre-se* de trazer o máximo que pudermos durante as próximas [promoções](http://acme-marg.com)!
## Comida
- feijão cozido
- esparguete
## Papelaria
- bloco de notas
- lápis
\end{markdown}
\end{document}
```
Ou, se preferir colocar o seu material Markdown num `*.md` ficheiro:
```latex
\documentclass{article}
\usepackage{markdown}
\begin{document}
\markdownInput{example.md}
\end{document}
```
Ótimo! Isto certamente deixará os tipos de programador muito contentes, porque agora podem simplesmente copiar a sua `.md` documentação!
### Ainda posso usar comandos LaTeX se escrever em Markdown?
Sim, ainda pode usar comandos LaTeX no seu material Markdown! Basta passar o `hybrid` opção para `markdown`:
```latex
\usepackage[hybrid]{markdown}
...
- bloco de notas (daqueles com o grande $E=mc^2$ na capa)
```
### Como posso usar caracteres literais como '#' e '\_' (sublinhados)?
#### Escrever um '#'
Não pode digitar o caractere '#' *dentro do `markdown` ambiente*. Nem sequer `\#` funciona. Precisa de definir um comando como `\newcommand{\texthash}{\#}`, e depois usar `\texthash` no preâmbulo dos teus `markdown` ambiente. De modo semelhante para os sublinhados, especialmente quando há mais do que um na mesma linha, por ex., `$y = m_1 + n_2$`. Por vezes pode ser mais fácil terminar o atual `markdown` ambiente e escrever as linhas problemáticas no modo normal do LaTeX, e depois iniciar outro `markdown` ambiente.
#### Escrever '\_' (sublinhado) e '\`' (acento grave)
**Atualização** (adicionado em 13 de maio de 2017): Desde `markdown` a versão 2.5, pode definir `underscores = false` e `codeSpans = false` para desativar sublinhados e acentos graves. Isto torna possível escrever índices matemáticos e aspas no modo híbrido sem escape. Temos asteriscos para ênfase, portanto a única coisa realmente perdida são os exemplos de código inline. Obrigado, Vít, pela dica!
#### Ambientes a evitar...
E embora possa usar acentos graves para escrever texto literal inline, ou indentar a linha com quatro espaços para um bloco literal, não use `lstlisting` nem `minted` ambientes LaTeX dentro de `markdown` ambientes. Simplesmente não o faça.
#### Usar HTML num ambiente markdown
E não, não pode usar HTML dentro do `markdown` ambiente LaTeX (embora isto seja algo comum no Markdown habitual). Desculpe.
**Atualização** (adicionado em 13 de maio de 2017): A partir de `markdown` v2.3, existe uma `html` opção que não apresenta as etiquetas HTML literalmente se estiverem presentes no seu material markdown, embora também não formate efetivamente o conteúdo das etiquetas — isto é. `Olá!` apenas apresentará Olá! em fonte normal. Mas entidades HTML como `©` serão renderizadas como ©. Obrigado a Vít por chamar a atenção para isto.
### Opções sugeridas para o pacote markdown
Um conjunto de `markdown` opções do pacote que poderá achar útil é:
```latex
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses,hybrid]{markdown}
```
Essas opções permitem o uso da
* sintaxe de notas de rodapé do Markdown (como `[^1]`);
* listas de definição e `#` para listas numeradas;
* "verdadeiras" reticências (…).
Aqui está um [exemplo completo](https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm) na galeria do Overleaf, e aqui está [outro](https://www.overleaf.com/articles/how-to-write-using-rich-text-format-and-markdown-in-latex-and-overleaf/dbqrxvftzskw).
### Hiperligações e notas de rodapé: como?
No exemplo do Overleaf, a hiperligação é uma nota de rodapé. Como faço para que seja uma hiperligação hyperref?
`markdown` é personalizável, por isso pode definir como gostaria que diferentes elementos fossem renderizados. Adicionar isto ao preâmbulo fará exatamente isso:
```latex
\markdownSetup{renderers={
link = {\href{#2}{#1}}
}}
```
**Atualização** (adicionado em 13 de maio de 2017): `rendererPrototypes` foi usado na versão inicial. Recomenda-se que os utilizadores normais usem `renderers` para as suas próprias definições, uma vez que `rendererPrototypes` serve para os criadores de pacotes fornecerem predefinições. Se modificar `rendererPrototypes`, corre o risco de outro pacote substituir as suas definições. Obrigado a Vít por chamar a atenção para isto!
### Incluir imagens (atualizado em 8 de novembro de 2022)
* **Nota**: O próximo exemplo usa um arquivo gráfico (`example-image.pdf`) fornecido pelo `mwe` pacote. Esses ficheiros gráficos são distribuídos pelo TeX Live e, portanto, armazenados nos servidores do Overleaf, tornando-os disponíveis como marcadores de posição de imagem, como no exemplo abaixo.
As imagens podem ser incluídas em markdown escrevendo marcação no seguinte formato:
```latex
```
Esperamos que os nomes dos parâmetros `alt-text`, `nome-do-arquivo` e `"legenda da imagem"` descrevam o que fazem. Aqui está um exemplo para demonstrá-los:
```latex
\documentclass{article}
\usepackage[hybrid]{markdown}
% O pacote mwe fornece imagens de exemplo. Carregá-lo é
% não essencial, porque essas imagens estão no caminho de busca do LaTeX.
% Aqui, carregamo-lo por clareza neste exemplo.
\usepackage{mwe}
\begin{document}
\begin{markdown}
Este exemplo mostra como importar um arquivo gráfico. Aqui estamos usando uma
imagem de exemplo fornecida pelo pacote `mwe`.
% Use \setkeys{Gin} se precisar alterar o tamanho de exibição de uma imagem
\setkeys{Gin}{width=.5\linewidth}
\end{markdown}
\end{document}
```
[Abra este exemplo no Overleaf.](https://www.overleaf.com/docs?engine=pdflatex\&snip_name=Using+images+in+markdown\&snip=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%5Bhybrid%5D%7Bmarkdown%7D%0A%25+The+mwe+package+provides+example+images.+Loading+it+is%0A%25+not+essential+because+those+images+are+in+LaTeX%27s+search+path.+%0A%25+Here%2C+we+load+it+for+clarity+in+this+example.%0A%5Cusepackage%7Bmwe%7D%0A%5Cbegin%7Bdocument%7D%0A%5Cbegin%7Bmarkdown%7D%0AThis+example+shows+how+to+import+a+graphics+file.+Here+we+are+using+an%0Aexample+image+provided+by+the+%60mwe%60+package.%0A%0A%25+Use+%5Csetkeys%7BGin%7D+if+you+need+to+change+an+image%27s+display+size%0A%0A%5Csetkeys%7BGin%7D%7Bwidth%3D.5%5Clinewidth%7D%0A%21%5BThis+is+alt+text+to+describe+my+image.%5D%28example-image.jpg+%22An+example+image+provided+by+the+%5Ctexttt%7Bmwe%7D+package.%22%29%0A%5Cend%7Bmarkdown%7D%0A%5Cend%7Bdocument%7D)
Este exemplo produz a seguinte saída:
#### Observação sobre a largura da imagem
Como a maioria dos pacotes, `markdown` carrega outros pacotes, incluindo [`keyval`](https://ctan.org/pkg/keyval?lang=en) e [`graphicx`](https://ctan.org/pkg/graphicx?lang=en), para fazer uso dos comandos e recursos que eles fornecem. Aqui, a largura da imagem é definida usando o `\setkeys` comando, que é fornecido por `keyvals`. `Gin` é uma "família" de chaves definida pelo `graphicx` pacote.
* **Nota**: Como um comando LaTeX, aqui `\setkeys`é usado *dentro* o `markdown` do ambiente, a `hybrid` opção do pacote markdown é necessária.
#### Alterar identificadores de posicionamento de floats (mais avançado)
A sintaxe markdown para inclusão de figuras não permite especificar diretamente os identificadores de posicionamento de floats, mas pode ajustá-los redefinindo como a figura é renderizada:
```latex
\markdownSetup{renderers={
image = {\begin{figure}[hbt!]
\centering
\includegraphics{#3}%
\ifx\empty#4\empty\else
\caption{#4}%
\fi
\end{figure}}
}}
```
Para mais informações, consulte a [documentação Markdown](https://mirror.apps.cam.ac.uk/pub/tex-archive/macros/generic/markdown/markdown.html).
### É possível criar tabelas usando markdown em LaTeX? 😀
Infelizmente, não. As tabelas são suportadas apenas em [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) e o pacote LaTeX `markdown` atualmente não tem suporte para isso.
**Atualização** (adicionado em 13 de maio de 2017): Com base numa dica de Vít, é possível usar a extensão de sintaxe `contentBlocks` desde a versão 2.4, ou ajustar o `inputFencedCode` renderizador, para transformar rapidamente algum texto em estilo CSV numa tabela.
### Mais funcionalidades do pacote Markdown...?
Como mencionado anteriormente, é uma forma interessante de tomar notas e, quando combinada com algumas boas classes de documentos LaTeX ou configurações de pacotes, permite-lhe ter um belíssimo caderno ao fim da própria aula. Por exemplo, poderia usá-lo com as [classes Tufte](https://www.overleaf.com/gallery/tagged/tufte):
```latex
\documentclass{tufte-handout}
\usepackage[footnotes,definitionLists,hashEnumerators,smartEllipses, hybrid]{markdown}
\begin{document}
\markdownInput{PHY303-lecture-12Nov2016.md}
\end{document}
```
E a sintaxe curta e simples, que torna a escrita de listas muito mais conveniente, significa que agora temos uma *realmente rápida* forma de escrever [apresentações Beamer](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw) e [cartazes](https://www.overleaf.com/latex/examples/writing-beamer-slides-with-markdown/dnrwnjrpjjhw)!
Divirta-se!
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://overleaf-pro.ayaka.space/latex/overleaf-learn-latex-pt/artigos-aprofundados/30-how-to-write-in-markdown-on-overleaf.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.