├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Gustavo Mendel 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

drawing

2 | 3 | # O Guia Definitivo de MarkDown para Iniciantes 4 | 5 | ##### Por Gustavo Mendel 6 | 7 | Com a popularização do **GitHub** e com o surgimento de uma leva de novos desenvolvedores, a demanda por aprender *Markdown* aumentou significativamente. *Markdown* é uma linguagem de marcação, parecida com o HTML. 8 | 9 | Ela é muito utilizada na criação dos famosos **READMEs** para seus respectivos repositórios no **GitHub**, podendo deixá-los mais 'apresentáveis'. Então, por esse motivo que trago aqui um guia simples porém definitivo para aprender o tão popular *Markdown* e utilizá-lo no **README** do seu projeto. 10 | 11 | 12 | ## README E SUA IMPORTÂNCIA 13 | 14 | Todo projeto no GitHub terá seus códigos, seus arquivos e suas pastas. Um projeto bem estruturado precisa informar ao leitor **à razão de existência do projeto, qual sua finalidade, os recursos que oferece, em qual ou quais linguagens foi escrito, as ferramentas utilizadas, como contribuir** e várias outras informações necessárias que se acharem pertinentes. 15 | E para isso existe um arquivinho bem simples chamado **'README.md' ou 'readme.md'** em todo repositório minimamente organizado no GitHub. Perceba que o arquivo possui o sufixo **'.md'**, essa é a extensão dos arquivos **Markdown**. Ao criar o **README.md** em seu repositório, ao rolar um pouco para baixo a página inicial, todo o conteúdo do README.md formatado em Markdown será exibido. Ele deverá conter todas as informações do projeto. 16 | Para ver o conteúdo sem formatação, procure um ícone de um lápis, ou até clique no arquivo em si **_README.md_**, assim você será encaminhado para a edição do arquivo. 17 | 18 | ## Alguns pontos e detalhes a serem adicionados em seu arquivo readme.md para melhorar seu projeto: 19 | *Fica claro aqui, que são todas opcionais, cabe a você desenvolvedor analisar e escolher quais colocar em seu repositório. Lembrando que nem todos pontos a seguir cabem em todos os repositórios, depende do que ele se trata, se é um jogo, um programa, um código-fonte de um website. Saiba escolher o que colocar.* 20 | 21 | ___ 22 | 23 | 1. **Introdução** 24 | > *Uma breve apresentação sobre o que é o seu projeto, o que ele faz, e algumas informações úteis para serem ditas inicialmente.* 25 | 2. **Índice** 26 | > *É interessante ter um índice com os links para os tópicos que vão ser abordados em seu texto, assim como o índice deste tutorial.* 27 | 3. **Habilidaes adiquiridas ou requisitadas para o projeto** 28 | > *Se teu projeto visa a aprendizagem, o seu próprio estudo ou até base para estudos de outras pessoas, é interessante colocar quais habilidades são requeridas para estudar/rodar o seu código, ou habilidades que vão ser adquiridas se seguirem os seus estudos.* 29 | 4. **Como executar** 30 | > *Se tens um programa que faz alguma coisa, um jogo, um código em determinada linguagem, é interessante adicionar a informação de como executar seus códigos, quais programas precisa no computador do usuário, comando para executar os códigos, algumas informações de quais arquivos precisa ter, entre diversos outros.* 31 | 5. **Contribuindo** 32 | > *Se teu projeto é OpenSource, é natural que outros programadores desejem melhorar algum código dele, adicionando novos recursos, corrigindo algum bug, implementando alguma tecnologia, entre diversos outros. para isso ele deverá fazer pulls requests em seu código, seria muito interessante implementar algumas informações de como contribuir com o projeto, como fazer um Fork, como fazer o pull request, e até algumas preferências pessoais suas de como queres o pull request.* 33 | 6. **Créditos e Licença** 34 | > *É interessante também em alguns casos concluir com os créditos do repositório ou até mesmo da licença utilizada nele.* 35 | ___ 36 | 37 | **_Note que não são todos os pontos a colocar, tão pouco são obrigatórios, pensei apenas em ajudar os iniciantes que estão criando teus repositórios no momento, e alguns pontos que são muito importantes para projetos simples. Claro que projetos mais avançados requerem muito mais pontos a ser colocados, e depende muito de um para outro. O foco destas dicas é pensando nos projetos mais básicos e iniciantes._** 38 | 39 | # A Sintaxe do MarkDown 40 | 41 | 1. [Títulos](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#títulos) 42 | 2. [Ênfase](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#ênfase) 43 | 3. [Linha Horizontal](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#linha-horizontal) 44 | 4. [Citações](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#citações) 45 | 5. [Listas](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#listas) 46 | 6. [Códigos](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#códigos) 47 | 7. [Links](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#links) 48 | 8. [Imagens](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#adicionando-imagens) 49 | 9. [Links em imagens](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#links-em-imagens) 50 | 10. [Tabelas](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#tabela) 51 | 11. [HTML Embutido](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#html-embutido) 52 | 12. [Créditos](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#créditos) 53 | 54 | ## Títulos 55 | 56 | Inicialmente temos os 'Headings', ou Títulos. Eles se apresentam hierarquicamente variando o tamanho da fonte. Ou seja, o título número 1 é mais importante que o título número 2, que por sua vez é mais importante que o número 3, e assim por diante. 57 | Existem 6 títulos, que vai do título 1 (mais importante e por conseguinte maior e mais destacado) até o título 6 (menos importante e por conseguinte menor e menos destacado). 58 | 59 | A sintaxe é simples: 60 | ``` 61 | # Título 1 62 | ## Título 2 63 | ### Título 3 64 | #### Título 4 65 | ##### Título 5 66 | ###### Título 6 67 | ``` 68 | 69 | Varia de acordo com o número de '#'. 70 | Exemplos: 71 | 72 | # Aqui um título 1 73 | ## Aqui um título 2 74 | ### Aqui um título 3 75 | #### Aqui um título 4 76 | ##### Aqui um título 5 77 | ###### Aqui um título 6 78 | 79 | ## Ênfase 80 | 81 | Você pode adicionar ênfase ao seu texto, como por exemplo o **negrito**, o *itálico*, ou até mesmo **_negrito e itálico_**. 82 | Lembre-se que além da aparência do seu texto, existe a semântica a ser seguida. Textos em negrito devem ser lidos com força, intensidade, e já o itálico significa uma ênfase maior. 83 | 84 | #### Negrito 85 | 86 | Sintaxe do **negrito:** 87 | 88 | ``` 89 | Este é **negrito** 90 | This is __strong__ 91 | ``` 92 | 93 | #### Itálico 94 | 95 | Sintaxe do *itálico:* 96 | 97 | ``` 98 | Este é *itálico* 99 | This is _italic_ 100 | ``` 101 | 102 | #### Negrito e itálico 103 | 104 | Sintaxe do **_negrito e itálico:_** 105 | 106 | ``` 107 | **_strong and em_** 108 | ``` 109 | 110 | #### Riscado 111 | 112 | Sintaxe do texto ~~riscado~~: 113 | 114 | ``` 115 | ~~riscado~~ 116 | ``` 117 | 118 | ## Linha horizontal 119 | 120 | Você pode adicionar linhas horizontais para deixar o texto mais organizado e apresentável. 121 | Usando três hifens, três asteriscos ou três underscore: 122 | 123 | ``` 124 | Hifens 125 | 126 | --- 127 | 128 | Asteriscos 129 | 130 | *** 131 | 132 | Underscore 133 | 134 | ___ 135 | ``` 136 | 137 | Learning Center: 138 | 139 | Hifens 140 | 141 | --- 142 | 143 | Asteriscos 144 | 145 | *** 146 | 147 | Underscore 148 | 149 | ## Citações 150 | 151 | Para criar uma citação em bloco, adicione um '>' na frente de um parágrafo. 152 | 153 | As citações em bloco podem conter vários parágrafos. Adicione um '>' nas linhas em branco entre os parágrafos 154 | 155 | Sintaxe: 156 | 157 | ``` 158 | Para citações em uma linha: 159 | > Esta é uma citação 160 | 161 | Em várias linhas: 162 | > Citação 1 163 | > 164 | > Citação 2 165 | ``` 166 | 167 | Resultado: 168 | 169 | Para citações em uma linha: 170 | > Esta é uma citação 171 | 172 | Em várias linhas: 173 | > Citação 1 174 | > 175 | > Citação 2 176 | 177 | As cotações em bloco podem ser aninhadas. Adicione um '>>' na frente do parágrafo que você deseja aninhar. 178 | Por exemplo: 179 | ``` 180 | > Citação 1 181 | > 182 | >> Citação 2 183 | ``` 184 | E assim temos: 185 | > Citação 1 186 | > 187 | >> Citação 2 188 | 189 | As citações de bloco podem conter outros elementos no formato Markdown. Nem todos os elementos podem ser usados, você precisará experimentar para ver quais funcionam. 190 | Exemplo: 191 | 192 | ``` 193 | > ##### The quarterly results look great! 194 | > 195 | > - Revenue was off the chart. 196 | > - Profits were higher than ever. 197 | > 198 | > *Everything* is going **well**. 199 | ``` 200 | 201 | Resultado: 202 | > ##### The quarterly results look great! 203 | > 204 | > - Revenue was off the chart. 205 | > - Profits were higher than ever. 206 | > 207 | > *Everything* is going **well**. 208 | 209 | ## Listas 210 | 211 | Você pode organizar listas, podendo ser ordenadas ou não. 212 | 213 | **_Listas Ordenadas_** 214 | 215 | Usando (número)(ponto) você pode ordenar as listas numericamente, como por exemplo: 216 | 217 | ``` 218 | 1. Primeiro 219 | 2. Segundo 220 | 3. Terceiro 221 | 4. Quarto 222 | ``` 223 | 224 | Vai gerar o seguinte resultado: 225 | 226 | 1. Primeiro 227 | 2. Segundo 228 | 3. Terceiro 229 | 4. Quarto 230 | 231 | Itens da lista de aninhamento 232 | 233 | Para aninhar itens de linha em uma lista ordenada, recue os itens quatro espaços ou uma guia. 234 | 235 | ``` 236 | 1. Primeiro item 237 | 2. Segundo item 238 | 3. Terceiro item 239 | 1. Indentado item 240 | 2. Indentado item 241 | 4. Quarto item 242 | ``` 243 | Irá gerar: 244 | 245 | 1. Primeiro item 246 | 2. Segundo item 247 | 3. Terceiro item 248 | 1. Indentado item 249 | 2. Indentado item 250 | 4. Quarto item 251 | 252 | **_Listas não Ordenadas_** 253 | 254 | Para criar uma lista não ordenada, adicione traços (-), asteriscos (*) ou sinais de adição (+) na frente de 255 | itens de linha. 256 | 257 | ``` 258 | - Exemplo 1 259 | 260 | * Exemplo 2 261 | 262 | + Exemplo 3 263 | ``` 264 | 265 | Vai gerar: 266 | 267 | - Exemplo 1 268 | 269 | * Exemplo 2 270 | 271 | + Exemplo 3 272 | 273 | **_Lista de tarefas_** 274 | 275 | Podemos criar também uma lista de tarefas, com a CheckBox preenchida ou não. Vejamos o exemplo: 276 | 277 | ~~~ 278 | - [ ] Esta é uma CheckBox não marcada 279 | - [x] Esta é uma CheckBox marcada 280 | ~~~ 281 | 282 | Learning Center: 283 | 284 | - [ ] Esta é uma CheckBox não marcada 285 | - [x] Esta é uma CheckBox marcada 286 | 287 | ## Códigos 288 | 289 | É possível exibir um código sem que ele seja formatado em *Markdown*, ou seja, ele será exibido exatamente como foi escrito, sem formatação Markdown. 290 | Existe o trecho simples, composto apenas por uma linha. Usamos uma crase para abrir e outra para fechar o trecho a ser destacado como trecho de código: 291 | ``` 292 | ` este é um exemplo ` 293 | ``` 294 | Resultado: 295 | 296 | `este é um exemplo` 297 | 298 | E também há a demarcação de bloco de código composto por várias linhas. Para isso utilize três crases ( ´´´ ) ou três tils ( ~~~ ) para abrir e três para fechar o bloco, desta forma: 299 | 300 | ``` 301 | ``` 302 | Este é nosso 303 | Querido Exemplo 304 | 305 | **Teste** 306 | 307 | Nota que não irá formatar o negrito! 308 | ``` 309 | ``` 310 | 311 | Resultado: 312 | ``` 313 | Este é nosso 314 | Querido Exemplo 315 | **Teste** 316 | Note que o trecho não ficará em negrito! 317 | ``` 318 | 319 | Para se ativar o realce da sintaxe do código, deve-se especificar em qual linguagem ele foi escrito logo após os três primeiros tils ou crases. Isso irá realçar a sintaxe, melhorando assim a legibilidade do código. 320 | 321 | Por exemplo: 322 | ``` 323 | ~~~python 324 | s = "Sintaxe do Python" 325 | print s 326 | ~~~ 327 | ``` 328 | ~~~python 329 | s = "Sintaxe do Python" 330 | print s 331 | ~~~ 332 | 333 | Para saber quais linguagens são suportadas por este mecanismo clique [aqui](https://pygments.org/languages/) e veja a listagem do Pygments. 334 | 335 | **_Nota:_** Para interligar um código dentro do outro, assim como eu fiz de exemplo para vocês: Abra o primeiro trecho de código com as três crases, e feche de imediato. Dentro desse código use a indentação de 4 espaços, e assim poderá abrir outro código sem formatar. 336 | 337 | ## Links 338 | Para embutir links às palavras, coloque-as entre colchetes [ ] e entre parênteses ( ) a URL. Por exemplo: 339 | 340 | ``` 341 | Clique [aqui](https://github.com) para acessar à página do GitHub. 342 | ``` 343 | Resultado: 344 | Clique [aqui](https://github.com) para acessar à página do GitHub. 345 | 346 | Lembre-se que você poderá criar links para outros repositórios no Github, ou para arquivos no repositório local, especificando opcionalmente a posição na página do arquivo. Por exemplo, clique [aqui](https://github.com/gustavo-mendel/guia-definitivo-de-markdown/blob/master/README.md#a-sintaxe-do-markdown) para acessar o título 'Sintaxe' neste mesmo arquivo. Tais recursos deixam seu *README* bem mais apresentável e interativo. 347 | Para exibir links contendo apenas a URL escreva o link entre '< >'. Exemplo: 348 | 349 | 350 | ## Adicionando imagens 351 | A sintaxe é um pouco parecida à anterior, apenas adicione uma exclamação (!) no início, entre colchetes [ ] o título da imagem e entre parênteses ( ) a URL. 352 | ~~~ 353 | ![Alt ou título da imagem](URL da imagem) 354 | ~~~ 355 | 356 | ## Links em imagens 357 | Você pode adicionar um link a uma imagem contendo uma URL da seguinte forma: 358 | 359 | ``` 360 | Clique na imagem para acessar o Google. 361 | [![Logo_Google_2013_Official svg](https://user-images.githubusercontent.com/5532...](https://google.com.br) 362 | ``` 363 | 364 | Clique na imagem para acessar o Google. 365 | 366 | [![Logo_Google_2013_Official svg (1) (7)](https://user-images.githubusercontent.com/55323701/82508957-fad58000-9adc-11ea-899a-b43ba9f83fd8.png)](https://google.com.br) 367 | 368 | ## Tabela 369 | 370 | Escolha os títulos das colunas e use `|` para delimitar as colunas. Depois, utilize hífen `-` na segunda linha para indicar que acima estão os títulos das colunas, usando novamente o `|` para delimitar colunas. Veja um exemplo abaixo: 371 | 372 | ~~~ 373 | Teste | Exemplo 374 | ------- | ------ 375 | Teste 1 | Exemplo 1 376 | Teste 2 | Exemplo 2 377 | Teste 3 | Exemplo 3 378 | Teste 4 | Exemplo 4 379 | ~~~ 380 | 381 | No Learning Center irá aparecer: 382 | 383 | Teste | Exemplo 384 | ------- | ------ 385 | Teste 1 | Exemplo 1 386 | Teste 2 | Exemplo 2 387 | Teste 3 | Exemplo 3 388 | Teste 4 | Exemplo 4 389 | 390 | Para especificar o tipo de alinhamento que deseja ter nas tabelas, utilize dois pontos `:` ao lado do campo horizontal de hifens `---`, na segunda linha da sua tabela. Veja abaixo: 391 | 392 | * Alinhado a esquerda: usar `:` no lado esquerdo (alinhamento padrão) 393 | * Alinhado a direita: usar `:` no lado direito 394 | * Centralizado: usar `:` dos dois lados 395 | 396 | Exemplo: 397 | ~~~ 398 | Alinhado a esquerda | Centralizado | Alinhado a direita 399 | :--------- | :------: | -------: 400 | Exemplo | Exemplo | Exemplo 401 | ~~~ 402 | 403 | Learning Center: 404 | 405 | Alinhado a esquerda | Centralizado | Alinhado a direita 406 | :--------- | :------: | -------: 407 | Exemplo | Exemplo | Exemplo 408 | 409 | ## HTML Embutido 410 | 411 | Você pode utilizar HTML no seu Markdown. Geralmente funciona muito bem. 412 | 413 | Vejamos: 414 | 415 | ``` 416 |
417 |
Lista definitiva
418 |
É algo que as pessoas usam às vezes.
419 | 420 |
Markdown no HTML
421 |
*Não* funciona **muito bem**. Use as tags do HTML
422 |
423 | ``` 424 | 425 |
426 |
Lista definitiva
427 |
É algo que as pessoas usam às vezes.
428 |
Markdown no HTML
429 |
*Não* funciona **muito bem**. Use as tags do HTML
430 |
431 | 432 | ## ~~Extra:~~ Emojis 433 | 434 | O MarkDown também permite colocar alguns emojis em seus textos, não abuse deles para não parecer um circo de diversões, só em alguns casos bem específicos. 435 | 436 | :nome_do_emoji: 437 | 438 | Alguns exemplos: 439 | 440 | ``` 441 | :smile: :fire: :file_folder: :space_invader: :computer: 442 | ``` 443 | 444 | :smile: :fire: :file_folder: :space_invader: :computer: 445 | 446 | Para conferir uma lista com os emojis e suas sintaxes, clique aqui: [EMOJIS](https://gist.github.com/rxaviers/7360908) 447 | 448 | ## Créditos 449 | 450 | Copyright (C) 2020 by Gustavo Mendel 451 | --------------------------------------------------------------------------------