Guia de MARKDOWN:
- parte 01


Parte 01
Parte 02

Para acessar a CHEAT SHEET desse guia, acesse a pagina: BUGIGANGAS!


GITHUB FLAVORED MARKDOWN (GFM) ou MARKDOWN COM SABOR DO GITHUB, na tradução literal, é 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 na versão GFM, 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:


ATENÇÃO - Neste guia será apresentado alguns exemplos e seus resultados para facilitar a explicação, então fique atento aos detalhes.

A formatação básica de texto:
1. Títulos:

O MARKDOWN permite criar títulos de seis níveis diferentes baseado na 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: 


# Título H1
## Título H2
### Título H3
#### Título H4
##### Título H5
###### Título H6
                


Título H1


Título H2


Título H3


Título H4


Título H5


Título H6
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: <sub> texto... </sub>.
Exemplo: 

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

Isso aqui está subscrito: texto subscrito

  • Sobrescrito:
    Use a sintaxe HTML: <sup> texto... </sup>
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, e não o navegador, padrão do HTML.

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: 


> Isto é uma citação.
> Esta é a segunda linha da citação.
                


 Isto é uma citação.
Esta é a segunda linha da citação.

4. Blocos de códigos:

  • 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: 


Aqui VERMELHO em HEX: `#FF0000`
Aqui AZUL em RGB: `rgb(0, 0, 255)`
OBSERVE:
Isso só tem suporte em problemas, solicitações de pull e discussões.

6. Linhas horizontais (quebra temática):

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

Exemplo: 


Primeira linha aqui
***

Segunda linha aqui
---

Terceira linha aqui
___

Quarta linha aqui
<hr>
                    

Primeira linha aqui

Segunda linha aqui

Terceira linha aqui

Quarta linha aqui
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](/assets/loads/uploads/pingo-and-valente-pinscher-and-akita-0.png)
Use esse link para ver: [a página inicial](/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](URL da imagem)

"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: 


![meus dogs](/assets/loads/uploads/img-300x/300x-pingo-and-valente-pinscher-and-akita-1.png)
![minha outra dog](/assets/loads/uploads/img-150x/150x-princesa-the-pinscher.png)
OBSERVE:
Também existe o suporte para o elemento <picture> e <img> do html.

Exemplo: 

<picture>
    <source media="(max-width: 600px)"
    srcset="/assets/loads/uploads/img-300x/300x-pingo-and-valente-pinscher-and-akita-1.png">
    <img src="/assets/loads/uploads/img-150x/150x-pingo-and-valente-pinscher-and-akita-1.png">
</picture>

3. Emojis:

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

Exemplo: 


:smile: :laughing: :blush:
:smiley: :relaxed: :wink:
:heart: :brazil: :medal_military:
                

😄 😆 😊
😃 ☺️ 😉
❤️ 🇧🇷 🎖️

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. 

  2. Segundo item
    3. 

  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.
  • Listas de tarefas:
    Use [ ] (colchetes) para tarefas não concluídas e [x] (colchetes com x) para tarefas concluídas.
Exemplo: 

Lista de tarefas:
- [ ] Ser famoso
- [x] Fazer um site
                    

Lista de tarefas:
□ Ser famoso
■ Fazer um site

2. 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 

Primum praeceptum:<br>
Diliges Deum super omnia, et non habebis deos alienos. \
Secundum praeceptum:<br>
Nolite facere idola, neque simulacra colatis. \
Tertium praeceptum:<br>
Noli in vanum nomen Dei accipere. \
Quartum praeceptum:<br>
Sabbata et festivitates sanctas observa ex mandato. \
Quintum praeceptum:<br>
Honora patrem et matrem. \
Sextum praeceptum:<br>
Non occides. \
Septimum praeceptum:<br>
Non moechaberis. \
Octavum praeceptum:<br>
Non furtum facies. \
Nonum praeceptum:<br>
Falsum testimonium non dices. \
Decimum praeceptum:<br>
Non concupisces uxorem proximi tui.
                    

Primum praeceptum:
Diliges Deum super omnia, et non habebis deos alienos.

Secundum praeceptum:
Nolite facere idola, neque simulacra colatis.

Tertium praeceptum:
Noli in vanum nomen Dei accipere.

Quartum praeceptum:
Sabbata et festivitates sanctas observa ex mandato.

Quintum praeceptum:
Honora patrem et matrem.

Sextum praeceptum:
Non occides.

Septimum praeceptum:
Non moechaberis.

Octavum praeceptum:
Non furtum facies.

Nonum praeceptum:
Falsum testimonium non dices.

Decimum praeceptum:
Non concupisces uxorem proximi tui.

3. 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: 


As duas primeiras linhas ficam no texto normal,
e as duas ultimas são as que renderizam no final da página:

Aqui uma simples nota de rodapé[^1].
Uma nota de rodapé pode ter multiplas linhas[^2].

[^1]: Minha referência.
[^2]: Minha outra referência.
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 pelo 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: 


@B-Ariel

2. Alertas:

Use essa sintaxe: > [!TIPO]

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

Exemplo: 


> [!NOTE]
> Informações úteis que os usuários devem saber, mesmo quando estiverem lendo superficialmente o conteúdo.

> [!TIP]
> Conselhos úteis para fazer as coisas melhor ou mais facilmente.

> [!IMPORTANT]
> Informações importantes que os usuários precisam saber para atingir seus objetivos.

> [!WARNING]
> Informações urgentes que precisam de atenção imediata do usuário para evitar problemas.

> [!CAUTION]
> Aconselha sobre riscos ou resultados negativos de certas ações.

3. Ocultar conteúdo (comentar):

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

Exemplo: 


<!-- Isso é um comentário em HTML.
Mas funciona aqui no MARKDOWN também:

Este texto não será exibido na renderização da página, apenas no código fonte.
-->

4. Ignorar formatação:

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

Exemplo: 


O primeiro é um título, já o segundo, não:

# Olá, mundo!

\# Olá, mundo!


                    

O primeiro é um título, já o segundo, não:


Olá, mundo!

# Olá, mundo!

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