Guia de MARKDOWN - parte 01

---

Para acessar a CHEAT SHEET (FOLHA DE COLINHA) desse guia, acesse a pagina de BUGIGANGAS!

---

GITHUB FLAVORED MARKDOWN (GFM) ou MARKDOWN COM SABOR DO GITHUB, é uma linguagem de marcação leve e simples, usada para formatar texto de forma rápida e eficiente, sem a necessidade de aprender HTML. Possuindo nessa versão, a extensão ".md", ela é frequentemente utilizada para criar documentos legíveis e bem formatados em plataformas como GITHUB, blogs, sistemas de documentação etc.
Com o MARKDOWN, você pode adicionar títulos, listas, links, imagens e muito mais, usando uma sintaxe fácil de entender.

Guia de MARKDOWN - BÁSICO que fará você sobreviver no GITHUB, e que, nesta primeira parte, abordará estes temas:

• A formatação básica de texto: Títulos, estilos (negrito, itálico, etc.), citações, blocos de código, cores e linhas horizontais.


• A inclusão de elementos multimídia: Links, imagens e emojis.


• A organização do conteúdo: Listas (ordenadas, não ordenadas, tarefas), parágrafos e notas de rodapé.


• Os recursos específicos do GITHUB: Menções, alertas, comentários e ignorar formatação.

ATENÇÃO - Neste guia será apresentado alguns exemplos para facilitar a explicação, o primeiro exemplo, mostrará como é feita a codificação, e caso haja um segundo, mostrará como seria o resultado.

---

A formatação básica de texto:

1. Títulos:

O MARKDOWN permite criar títulos de seis níveis diferentes usando a sintaxe do HTML, de H1 (o maior) a H6 (o menor).

Para criar um título, você usa o símbolo # (cerquilha / hash) no início da linha, seguido de um espaço, e logo em seguida o texto que vai ser o título.

O número de símbolos # (cerquilha / hash) indica o nível do título

Exemplo:

OBSERVE:
Índice automático:
O GITHUB analisa os títulos em seus arquivos MARKDOWN e gera automaticamente um índice (ou sumário) no topo do arquivo. Isso facilita a navegação em documentos longos, permitindo que os leitores cliquem nos títulos para ir diretamente para as seções correspondentes.

2. Estilos de texto:

• Negrito:

Envolva o texto com dois ** (asteriscos) ou dois __ (sublinhados)

Exemplo:

**texto em negrito** ou __texto em negrito__



Isso aqui está em negrito: texto em negrito



• Itálico:

Envolva o texto com um * (asterisco) ou um _ (sublinhado)

Exemplo:

*texto em itálico* ou _texto em itálico_


Isso aqui está em itálico: texto em itálico



• Tachado:

Envolva o texto com dois ~~ (Til / Tilde)

Exemplo:

~~texto tachado~~


Isso aqui está tachado: texto tachado



• Subscrito:

Use a sintaxe HTML: _texto....

Exemplo:

Isso aqui está subscrito: <sub> texto subscrito </sub>


Isso aqui está subscrito: texto subscrito



• Sobrescrito:

Use a sintaxe HTML: ^texto...

Exemplo:

Isso aqui está sobrescrito: <sup> texto sobrescrito </sup>


Isso aqui está sobrescrito: texto sobrescrito



• Sublinhado:

Use a sintaxe HTML: <ins> texto... </ins>.

Exemplo:

Isso aqui está sublinhado: <ins> texto sublinhado </ins>


Isso aqui está sublinhado: texto sublinhado

OBSERVE:
O MARKDOWN foi criado com a intenção de ser integrável com HTML, permitindo assim, uma utilização de muitas tags HTML para estilizar conteúdos que a sintaxe padrão do MARKDOWN não suporta. Note que, muitas tags HTML podem ser usadas (mas lembre-se que não são todas as tags existentes) porque, é o GITHUB que irá renderizá-las corretamente.

3. Citações:

Use o símbolo > (maior que) no início da linha para indicar uma citação.
Você pode citar várias linhas, colocando > (maior que) no início de cada linha.

Exemplo:

4. Bloco de código:

• Código em linha:

Envolva o código com ` (acento grave).

Exemplo:

`console.log("Olá, mundo!");`


console.log("Olá, mundo!");



• Blocos de código:

Envolva o bloco de código com três ``` (acentos graves).
Você pode especificar a linguagem de programação após as três crases iniciais para habilitar o realce de sintaxe.

Exemplo:

```python
print("Olá, mundo!")
```


print("Olá, mundo!")

5. Cores:

Envolva o código de cor (HEX, RGB ou HSL) com ` (acento grave).
O GITHUB exibirá uma pequena amostra da cor ao lado do código.

Exemplos:

OBSERVE:
Isso só tem suporte em problemas, solicitações de pull e discussões.

6. Linha horizontal (quebra temática):

Use três *** (asteriscos), --- (hífens / traços), ___(sublinhados) ou a tag HTML <hr> para criar a linha horizontal.

Exemplo:

OBSERVE:
São permitidos mais do que só três caracteres para fazer a quebra de linha.
Sendo também permitido o uso de espaço entre os caracteres.

---

A inclusão de elementos multimídia:

1. Links:

• Links embutidos:

Use a sintaxe: [texto do link](URL).

Exemplo:

Para ir para a Página inicial: [Clique aqui](https://b-ariel.github.io)


Para ir para a Página Inicial: Clique aqui



• Links de seção:

Use:
#nome-da-seção

Onde "nome-da-seção" é o texto do título da seção (com espaços substituídos por - (hífens / traços) e possuindo também, apenas letras minúsculas).

Exemplo:

Para ir na seção - "A formatação básica de texto": [Clique aqui](#a-formatação-básica-de-texto)


Para ir na seção - "A formatação básica de texto": Clique aqui
OBSERVE:
O GITHUB cria essas âncoras automaticamente.


• Links relativos:

Use:
[texto](caminho/para/arquivo)

para criar links para outros arquivos no mesmo repositório.

Exemplo:

Use esse link para ver: [meus dogs](Main/Images/pingo-and-valente(pinscher-and-akita).jpg)

Use esse link para ver: [a página inicial](Main/index.html)



Use esse link para ver: meus dogs

Use esse link para ver: a página inicial
OBSERVE:
O texto do link deve estar em uma única linha, e usar a / (barra), pois é um link relativo



• Âncoras personalizadas:

Use as tags HTML para ancorar:
<a name="endereço/do/link">...Texto Aqui</a>

Para assim criar âncoras personalizadas dentro do documento.
Em seguida, use:
[texto](#nome)

Isso cria um link para essa âncora.

Exemplo:

<a name="basic-text-formatting"></a>

Já qui fica o link - [Um link personalizado](#basic-text-formatting)


Já qui fica o link - Um link personalizado

OBSERVE:
As âncoras personalizadas não são consideradas pelo comportamento automático de nomenclatura e numeração de links de cabeçalho automáticos.

2. Imagens:

Use a sintaxe:

"texto alternativo" é uma descrição da imagem para acessibilidade.
E o GITHUB suporta URLs de imagens externas e links relativos para imagens no mesmo repositório.

Exemplo:

OBSERVE:
Também existe o suporte para o elemento <picture> e <img> do html.

Exemplo:

3. Emojis:

Digite : (dois-pontos) seguido do código do emoji.

Exemplo:

---

A organização do conteúdo:

1. Listas:

• Listas não ordenadas:

Use - (hífens / traços), * (asteriscos) ou sinais de + (mais) no início de cada linha.

Exemplo:

- Item 1
* Item 2
+ Item 3


• Item 1
• Item 2
• Item 3



• Listas ordenadas:

Use números seguidos de . (ponto) no início de cada linha.

Exemplo:

Assim:

1. Primeiro item
2. Segundo item
3. Terceiro item

OU ASSIM:

1. Primeiro item
1. Segundo item
1. Terceiro item


As duas opções ficam a mesma coisa:

1. Primeiro item
2. Segundo item
3. Terceiro item



• Listas aninhadas:

Recue os itens da lista aninhada com espaços.
O número de espaços determina o nível de aninhamento.


- Item 1
     - Item 1.1
     - Item 1.2
        - Item 1.2.1
        - Item 1.2.2
- Item 2




● Item 1
    ○ Item 1.1
    ○ Item 1.2
       ■ Item 1.2.1
       ■ Item 1.2.2
● Item 2

OBSERVE:
Você pode criar vários níveis de listas aninhadas usando o mesmo método.
Sendo que o primeiro nível aninhado, deve ter cinco espaços obrigatoriamente. Mas para cada nível aninhado a mais, você deve adicionar três espaços a mais que o anterior.

2. Listas de tarefas:

Use [ ] (colchetes) para tarefas não concluídas e [x] (colchetes com x) para tarefas concluídas.

Exemplo:

3. Parágrafos:

Para dar espaços entre parágrafos, basta fazer isso:

Incluir dois espaços no final da primeira linha;
Ou incluir uma \ (barra invertida) no final da primeira linha;
Ou usar a tag HTML <br> para criar uma quebra de linha;
Ou você deixar uma linha em branco entre duas linhas;

Exemplo

4. Notas de rodapé:

Para usar, use essa sintaxe:
[^numero]

Para assim criar a referência da nota de rodapé no texto.

Depois use a mesma sintaxe:
[^numero]
Para assim no texto da nota, definir o conteúdo desta mesma nota.

Exemplo:

OBSERVE:
O lugar em que a nota de rodapé fica no MARKDOWN, não influenciará a posição em que a nota será renderizada. Você pode escrever a nota logo após sua referência, e ela continuará sendo interpretada na parte inferior do MARKDOWN.

---

Os recursos específicos do GITHUB:

1. Menções:

Digite @ (arroba) seguido do nome de usuário ou da equipe que você deseja mencionar.
Isso enviará uma notificação para a pessoa ou equipe mencionada.

Exemplo:

2. Alertas:

Use essa sintaxe:
> [!TIPO]

Isso cria alertas, onde 'TIPO' pode ser 'NOTE', 'TIP', 'IMPORTANT', 'WARNING' ou 'CAUTION'.

Exemplo:

3. Ocultar conteúdo (comentar):

Envolva o conteúdo que você deseja ocultar com comentários da sintaxe do HTML:
<!-- Texto... -->

Exemplo:

4. Ignorar formatação:

Como usar:
Use uma \ (barra invertida) antes do caractere MARKDOWN que você deseja ignorar.

Exemplo:

---

EM CASOS DE DÚVIDA, SEMPRE BUSCAR A DOCUMENTAÇÃO OFICIAL!