Escrevendo Artigos

01Introdução ↩ índice

Neste artigo iremos sugerir um template para criação de artigos em Markdown¹, que podem ser facilmente renderizados utilizando o VS Code.

O nosso objetivo é trazer uma alternativa grátis e que possa ser utilizada tanto online quanto offline, suportada por diversas plataformas e ferramentas.

02Pré-requisitos ↩ índice

Utilizaremos os seguintes requisitos de software para escrever os artigos:

Conhecimento (não mandatório) em:

03Documento ↩ índice

Estrutura ↩

O artigo será estruturado em 4 partes: Título, Índice, Conteúdo e Referências. Já o conteúdo poderá ser subdividido em Capítulo, Tópico e Detalhe.

Título ↩

O Título é uma frase que identifica o artigo e deve ser único entre os seus demais artigos, para evitar sobreposições. Também deve-se colocar a identificação do autor e a data em que o mesmo foi redigido, bem como revisões posteriores e suas datas.

# $$\color{Blue}\Huge<<título1>>\ \newline\color{Blue}\Huge<<título2>>$$

# $$ \color{Blue}\Huge As\ leis\ \newline fundamentais\ \newline da estupidez\ \newline humana $$

Num artigo é importante o registro de revisões.

|**Name**|**Date**|**Remarks**|**Version**|
| :- | :- | :- | :- |
|[AuthorName]|[Date]|Initial Requirements Specification|1|
|[AuthorName]|[Date]|[Remarks]|[#]|
|||||
|||||

Índice ↩

O índice é uma lista das partes de um artigo, organizada pela ordem em que as partes aparecem. Ele é relevante para um acesso rápido aos tópicos do artigo.

- [<<n.n Capítulo/Tópico/Detalhe>>](#_tocnnn)

- [1. Introdução](#_toc001)
- [2. Pré-requisitos](#_toc002)
- [3. Documento](#_toc003)
  - [3.1 Estrutura](#_toc0031)
    - [3.1.1 Título](#_toc00311)
    - [3.1.2 Índice](#_toc00312)
- [4. Referências](#_toc004)

A ligação ao Capítulo/Tópico/Detalhe é efetuada na declaração do mesmo, através de um hyperlink (ex.: _toc001). Utilizaremos hyperlinks para evitar problemas com acentuação e permitir apontamentos com o mesmo nome.

# <a name="_tocnnn"></a><<Capítulo/Tópico/Detalhe>>[↩︎](#_tocnnn)

# <a name="_toc001"></a>Introdução[↩︎](#_toc000)
# <a name="_toc002"></a>Pré-requisitos[↩︎](#_toc000)
# <a name="_toc003"></a>Documento[↩︎](#_toc000)
## <a name="_toc0031"></a>Estrutura[↩︎](#_toc003)
### <a name="_toc00311"></a>Título[↩︎](#_toc0031)
### <a name="_toc00312"></a>Índice[↩︎](#_toc0031)
 ...

Convencionamos que:

Os hyperlinks serão numerados em ordem sequencial conforme a estrutura. Por exemplo: se o capítulo for _toc001, o primeiro tópico filho será _toc0011, o segundo _toc0012, e assim por diante. Da mesma forma, se o tópico tiver detalhes, eles seguem a sequência: os filhos de _toc0011 serão _toc00111, _toc00112, etc.

<a name="_tocnnn"></a><<Capítulo/Tópico/Detalhe>>

Na declaração do Capítulo/Tópico/Detalhe teremos um apontamento para o nível anterior, ou seja:

detalhe  --> tópico
tópico   --> capítulo
capítulo --> índice

[↩︎](#_tocnnn)

Outra convenção: o hyperlink do índice será _toc000, e todos os capítulos irão apontar para ele na sua declaração.

# <a name="_toc001"></a>Introdução[↩︎](#_toc000)

Conteúdo ↩

Conteúdo é basicamente tudo o que você consome ou cria em termos de informação, entretenimento ou educação. Pode ser um texto, imagem, vídeo, áudio, gráfico, arte etc. É algo que tem valor para quem recebe, seja para informar, entreter, educar ou inspirar. Pense em um artigo de blog, um post nas redes sociais, um podcast, ou até um meme engraçado — todos são tipos de conteúdo.

Capítulo ↩

Capítulo é uma especialização do Conteúdo, a fim de criar itens que ajudam na compreensão do Conteúdo.

Tópico ↩

Tópico é uma especialização do Capítulo, a fim de criar itens que ajudam na compreensão do Capítulo.

Detalhe ↩

Detalhe é uma especialização do Tópico, a fim de criar itens que ajudam na compreensão do Tópico.

Texto ↩

É o assunto a ser desenvolvido, podendo ser texto, imagem, vídeo, áudio, gráfico, arte etc. Para isso usamos a linguagem Markdown¹ para realizar a sua formatação. Alguns padrões foram estabelecidos (todos podem ser testados no Editor ao vivo):

Links ↩

[<<nome do link>>](<<link>>)

[Markdown](https://en.wikipedia.org/wiki/Markdown)

![<<nome da mídia>>](<<nome da mídia com extensão>>)

![PointofView](PointofView.png)

[<<nome do item>>](#_tocnnn)

[Índice](#_toc000)

(#_tocnnn) é o identificador criado na declaração do item, como descrito em Índice.

[![<<Nome do vídeo>>](http://img.youtube.com/vi/<<vídeo ID>>/0.jpg)](https://www.youtube.com/watch?v=<<vídeo ID>>)

[![As cinco leis da estupidez humana de Cipolla](http://img.youtube.com/vi/oYpiYoqXCbA/0.jpg)](https://www.youtube.com/watch?v=oYpiYoqXCbA)

Podemos usar esta técnica para outros tipos de mídias também.

Referência de citação ↩

<<referência>>[^<<ID da referência>>]
...
[^<<ID da referência>>]: <<descrição>>

![](PointofView.png)[^2]
...
[^2]: **Koblin, Jonas**, "Cipolla’s 5 Laws of Human Stupidity", [Sprouts Schools](https://sproutsschools.com), 25/10/2024, [https://sproutsschools.com/cipollas-5-laws-of-human-stupidity/](https://sproutsschools.com/cipollas-5-laws-of-human-stupidity/).

[↩︎](#_tocnnn)

[↩︎](#_toc001)

>Texto
>[^<<ID da referência>>]
...
[^<<ID da referência>>]: <<descrição>>

>"Só sei que nada sei"
>[^1]

“Só sei que nada sei”¹

Bloco de citação ↩

Cinco tipos de alerta, no padrão do GitHub. A sintaxe é sempre a mesma — muda apenas a palavra-chave:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

Metadados ↩

Os metadados ficam no topo do arquivo (front matter) e são utilizados para a indexação do documento.

---
title: "Guia Completo de Markdown"
description: "Aprenda tudo sobre Markdown com este guia completo e detalhado."
keywords: ["Markdown", "Guia", "Tutoriais"]
author: "Seu Nome"
layout: post
categories: [programação, tutoriais]
tags: [Markdown, GitHub, Documentação]
date: 2024-11-13
published: true
permalink: /guia-completo-markdown/
excerpt: "Este guia cobre todos os aspectos do Markdown, desde o básico até tópicos avançados."
last_modified_at: 2024-11-13
---

PlantUML ↩

Podemos inserir uma renderização PlantUML dentro do Markdown.

```plantuml
@startuml
skinparam handwritten true
note as N1 #white
  **Tag:** <<//ID tag//>>     **Prioridade:** <<//grau//>>

  **Descrição:** <<//user story//>>

  **Prazo:** <<//DD/MM/YYYY//>>

  **Responsável:** <<persona>>
end note
@enduml
```

LaTeX ↩

Podemos inserir uma renderização LaTeX dentro do Markdown.

$$\large \boxed{\text{Flow Efficiency \%} = \frac{\text{Tempo de Trabalho Real}}{\text{Tempo Total de Processamento}}* 100}$$

Referências bibliográficas ↩

As referências bibliográficas seguem os formatos abaixo, de acordo com o tipo de fonte:

04Ferramentas ↩ índice

Três utilitários para aplicar o template sem sair desta página. Tudo roda no seu navegador; nada é enviado para fora.

Editor ao vivo ↩

Escreva Markdown à esquerda e veja o resultado à direita. Os alertas do GitHub (> [!NOTE] etc.) também são renderizados. O rascunho fica salvo neste navegador.

Gerador de índice ↩

Cole os títulos do artigo, um por linha, usando # para Capítulo, ## para Tópico e ### para Detalhe (níveis mais profundos também funcionam). O gerador numera os hyperlinks _toc e cria os links ↩︎ para o nível anterior, como descrito em Índice.

Montador de referências ↩

Escolha o tipo de fonte e preencha os campos. A nota sai no formato das Referências bibliográficas, pronta para colar no fim do artigo.

05Referências ↩ índice

1. 1
   “Markdown”, Wikipedia, 30/10/2024, https://en.wikipedia.org/wiki/Markdown. ↩
2. 2
   “PlantUML at a Glance”, PlantUML, 30/10/2024, https://plantuml.com/. ↩
3. 3
   “The LaTeX Project”, LaTeX, 30/10/2024, https://www.latex-project.org/. ↩
4. 4
   “Graphviz”, Graphviz, 30/10/2024, https://graphviz.org/. ↩