O que é o MkDocs

MkDocs é um gerador de sites estáticos. Ele converte arquivos Markdown para HTML, e é comumente usado para gerar documentação técnica para projetos de software.

O que é Markdown

Markdown é uma linguagem de marcação simples, que permite que documentos HTML semânticamente corretos sejam gerados a partir de um arquivo plain text.

Elementos básicos do Markdown

Alguns dos elementos mais utilizados em documentos Markdown são:

1. Parágrafos
2. Cabeçalhos
3. Listas
4. Links
5. Imagens
6. Citações
7. Código

Parágrafos

Em Markdown, um parágrafo é um bloco de texto separado de outros elementos por pelo menos uma linha em branco. Por exemplo, o documento a seguir é composto por dois parágrafos:

eu sou um parágrafo.

e eu sou outro parágrafo.

Cabeçalhos

Cabeçalhos são definidos usando # antes de uma linha. A quantidade de #s define o nível do cabeçalho: quanto mais #s, maior o nível do cabeçalho. Semânticamente, um documento deve ser estruturado com cabeçalhos saindo do menor nível (1) até o maior (6).

O documento a seguir demonstra o uso de cabeçalhos.

# titulo

## subtitulo

parágrafo dentro do subtitulo

### sub-subtitulo

outro parágrafo

## outro subtitulo

Listas

Uma lista pode ser ordernada ou não. Para listas ordenadas, basta prefixar cada linha com o número da mesma. Para listas não ordenadas, prefixamos com * ou -.

É importante notar que linhas grandes podem ser divididas, mas o começo da linha subsequente deve ser indentada para o mesmo nível da anterior.

Quanto queremos inseri

Lista ordenada:

1. lista
2. ordenada

Lista não ordenada:

• lista
• não
• ordenada

Quando queremos inserir duas listas consecutivas, precisamos separá-las com algum elemento. O uso de um comentário HTML é adequado nessa situação.

O documento a seguir demonstra o uso de listas.

1. primeiro item de uma lista ordenada.
2. segundo item de uma lista ordenada.
3. terceiro item de uma lista ordenada.
   como essa linha está indentada, ela faz parte do item anterior.

<!-- comentário para separar as listas -->

* primeiro item de uma lista ordenada.
* segundo item de uma lista ordenada.
* terceiro item de uma lista ordenada.
  como essa linha está indentada, ela faz parte do item anterior.

Links

Links são inseridos com uma combinação de parênteses e colchetes. O texto entre colchetes é o texto que vai ser apresentado no documento convertido, e o texto entre parênteses é a URL que será aberta quando o link for acessado.

Links podem ser usados dentro de outros componentes do Markdown, como parágrafos, listas, cabeçalhos e citações.

Esse é um exemplo de um link.

O documento a seguir demonstra o uso de links.

este é um parágrafo [com um link embutido](https://example.com/seu-link-vai-aqui).

1. essa é uma lista ordenada [com um link embutido](https://example.com/seu-link-vai-aqui).

Imagens

Imagens são similares aos links, mas prefixadas com um ponto de exclamação (!). Ao contrário dos links, elas (geralmente) não podem ser utilizadas dentro de outros elementos.

Esse é um exemplo de imagem:

O documento a seguir demonstra o uso de imagens.

agora eu vou inserir uma imagem.

![texto alternativo da imagem](https://example.com/link-da-imagem)

Citações

Citações são inseridas prefixando linhas com >. Esse é um exemplo de uma citação:

Markdown é muito legal!

O documento a seguir demonstra o uso de citações.

> Markdown é muito legal!

Código

Também é possível colocar código no Markdown.

Basta colocar 3 aspas simples seguidas do nome da linguagem e depois inserir o código. Para fechar, use mais 3 aspas simples.

Exemplo em C++

Exemplo em C++

#include <bits/stdc++.h>

using namespace std;

int main(int argc, char** argv) { 
    cout << "Olá, mundo!" << endl; 
} 

Exemplo em Python

print('Olá, mundo!')