manual-frontmatter.md (9180B)
1 # Manual de Front Matter — Disciplinas e Assuntos 2 3 Este manual documenta todos os campos de front matter (YAML) reconhecidos pelos 4 templates `single.html`, `disc-extras.html` e `baseof.html`, cobrindo tanto 5 páginas de **disciplina** (`_index.md` dentro de `content/txts/<disciplina>/`) 6 quanto páginas de **assunto** (arquivos `.md` individuais dentro de uma 7 disciplina). 8 9 --- 10 11 ## 1. Estrutura de pastas esperada 12 13 ``` 14 content/ 15 └── txts/ 16 └── direito-constitucional/ ← disciplina (_index.md) 17 ├── _index.md 18 ├── principios-fundamentais.md ← assunto 19 ├── controle-de-constitucionalidade.md 20 └── ... 21 ``` 22 23 - A **disciplina** é a seção (`Section = "txts"`), identificada pelo `_index.md`. 24 - O **assunto** é uma página regular dentro dela. 25 - O slug da disciplina (`$discSlug`) é inferido automaticamente pelo Hugo a 26 partir do caminho da URL — não é um campo do front matter. 27 28 --- 29 30 ## 2. Campos comuns (disciplina E assunto) 31 32 Estes campos são lidos pelo partial `disc-extras.html`, que é compartilhado 33 entre os dois tipos de página. Funcionam exatamente da mesma forma nos dois 34 contextos. 35 36 ### `guide` (string, markdown) 37 38 Texto do guia de estudo. Renderizado com `markdownify` dentro de um `<details>` 39 colapsável rotulado **"guia de estudo"**. 40 41 ```yaml 42 guide: | 43 ## Como estudar este conteúdo 44 1. Leia o texto completo antes dos exercícios. 45 2. Preste atenção nas notas de rodapé. 46 3. Faça o quiz ao final. 47 ``` 48 49 - Aceita qualquer sintaxe Markdown (listas, negrito, links, etc). 50 - Se omitido, o colapsável de guia simplesmente não aparece. 51 52 ### `files` (lista de objetos) 53 54 Materiais em formato de texto/link. Aparecem sob o rótulo **"textos"** dentro 55 do colapsável "materiais", com ícone ↗. 56 57 ```yaml 58 files: 59 - name: "Resumo em PDF" 60 url: "https://exemplo.com/resumo.pdf" 61 - name: "Artigo de referência" 62 url: "https://exemplo.com/artigo" 63 ``` 64 65 - Cada item **exige** `name` e `url`. 66 - Abre em nova aba (`target="_blank"`). 67 68 ### `videos` (lista de objetos) 69 70 Mesma estrutura de `files`, exibidos sob o rótulo **"vídeos"**, ícone ▶. 71 72 ```yaml 73 videos: 74 - name: "Aula sobre o tema" 75 url: "https://youtube.com/watch?v=xxxx" 76 ``` 77 78 ### `audios` (lista de objetos) 79 80 Mesma estrutura de `files`, exibidos sob o rótulo **"áudios"**, ícone ♪. 81 82 ```yaml 83 audios: 84 - name: "Podcast explicativo" 85 url: "https://youtube.com/watch?v=yyyy" 86 ``` 87 88 ### Comportamento do bloco "materiais" 89 90 - O colapsável "materiais" **só aparece** se `files`, `videos` ou `audios` 91 tiver pelo menos um item. 92 - O contador no cabeçalho (`N itens`) soma os três juntos. 93 - A ordem de exibição é sempre: textos → vídeos → áudios. 94 95 ### Regra geral de visibilidade 96 97 O bloco de colapsáveis inteiro (`disc-extras-wrap`) só é renderizado se 98 **pelo menos um** destes campos estiver presente: `guide`, `files`, `videos` 99 ou `audios`. Se nenhum existir, nada é exibido — sem erro, sem espaço vazio. 100 101 --- 102 103 ## 3. Campos exclusivos de página de **assunto** 104 105 Estes campos só são lidos por `single.html`, ou seja, só fazem sentido em 106 páginas de assunto individuais (não no `_index.md` da disciplina, a menos 107 que o template de listagem da seção também os leia explicitamente). 108 109 ### `title` (string, obrigatório) 110 111 Título do assunto. Usado em: 112 - `<h1 class="text-title">` 113 - `<title>` da aba do navegador (`{{ .Title }} · {{ .Site.Title }}`) 114 - Breadcrumb final (`<span class="breadcrumb">`) 115 116 ```yaml 117 title: "Princípios Fundamentais" 118 ``` 119 120 ### `references` (lista de strings) 121 122 Referências bibliográficas do assunto. Cada item vira um `<p>` dentro do 123 bloco **"referências"**, exibido ao final da página. 124 125 ```yaml 126 references: 127 - "MENDES, Gilmar. Curso de Direito Constitucional. 2023." 128 - "BARROSO, Luís Roberto. O Direito Constitucional e a Efetividade..." 129 ``` 130 131 - Só aparece se o campo existir e não estiver vazio. 132 - Não aceita objetos — apenas strings simples. 133 134 ### Quiz inline (automático — não é campo de front matter) 135 136 Se existir uma página em `content/quizzes/<disciplina>/<mesmo-slug>.md` 137 que **não** tenha `simulado: true` nem `"simulado"` no nome do arquivo, o 138 assunto automaticamente ganha uma seção de exercícios inline 139 ("exercícios deste assunto"), com quiz interativo carregado via JavaScript. 140 141 Não é necessário declarar nada no front matter do assunto para isso 142 funcionar — a ligação é feita pelo casamento de nomes de arquivo 143 (`File.BaseFileName`) entre `txts/<disciplina>/<slug>.md` e 144 `quizzes/<disciplina>/<slug>.md`. 145 146 Campo relevante **no quiz**, não no assunto: 147 148 ```yaml 149 # dentro do arquivo de quiz correspondente 150 simulado: false # false ou omitido = elegível a aparecer inline 151 # true = tratado como simulado, não aparece inline 152 ``` 153 154 --- 155 156 ## 4. Campos exclusivos de página de **disciplina** (`_index.md`) 157 158 Não há campos exclusivos de disciplina identificados nos templates 159 analisados — `_index.md` usa os mesmos `guide` / `files` / `videos` / 160 `audios` da seção 2. O `title` da disciplina também é obrigatório e é o que 161 aparece: 162 163 - No breadcrumb de todos os assuntos filhos (`{{ .Title }}` do 164 `range $.Site.Sections`). 165 - No link de "voltar" para a disciplina a partir de qualquer assunto. 166 167 ```yaml 168 title: "Direito Constitucional" 169 ``` 170 171 > ⚠️ **Atenção:** o campo `references` é lido apenas em `single.html`. 172 > Se o `_index.md` da disciplina usa um template de listagem diferente 173 > (`list.html` ou similar) que não chama esse trecho, `references` não 174 > terá efeito ali. Da mesma forma, o partial `disc-extras.html` só é 175 > aplicado ao `_index.md` se o template de listagem da seção também o 176 > chamar explicitamente — o comportamento não é automático fora de 177 > `single.html`. 178 179 --- 180 181 ## 5. Exemplo completo — disciplina 182 183 `content/txts/direito-constitucional/_index.md` 184 185 ```yaml 186 --- 187 title: "Direito Constitucional" 188 189 guide: | 190 ## Como estudar Direito Constitucional 191 1. Comece pela teoria da constituição. 192 2. Depois avance para direitos fundamentais. 193 3. Organização do poder por último. 194 195 files: 196 - name: "Ementa da disciplina" 197 url: "https://exemplo.com/ementa.pdf" 198 - name: "Bibliografia completa" 199 url: "https://exemplo.com/bibliografia" 200 201 videos: 202 - name: "Aula introdutória" 203 url: "https://youtube.com/watch?v=xxxx" 204 205 audios: 206 - name: "Podcast sobre a matéria" 207 url: "https://youtube.com/watch?v=yyyy" 208 --- 209 ``` 210 211 ## 6. Exemplo completo — assunto 212 213 `content/txts/direito-constitucional/principios-fundamentais.md` 214 215 ```yaml 216 --- 217 title: "Princípios Fundamentais" 218 219 guide: | 220 ## Como estudar este assunto 221 1. Leia o texto completo antes dos exercícios. 222 2. Preste atenção nas notas de rodapé. 223 3. Faça o quiz ao final. 224 225 files: 226 - name: "Resumo em PDF" 227 url: "https://exemplo.com/resumo.pdf" 228 229 videos: 230 - name: "Aula sobre o tema" 231 url: "https://youtube.com/watch?v=xxxx" 232 233 audios: 234 - name: "Podcast explicativo" 235 url: "https://youtube.com/watch?v=yyyy" 236 237 references: 238 - "MENDES, Gilmar. Curso de Direito Constitucional. 2023." 239 - "BARROSO, Luís Roberto. O Direito Constitucional e a Efetividade..." 240 --- 241 242 Conteúdo do assunto em Markdown... 243 ``` 244 245 ## 7. Exemplo mínimo (sem extras) 246 247 Válido tanto para disciplina quanto para assunto — nenhum colapsável 248 aparece, apenas título e conteúdo: 249 250 ```yaml 251 --- 252 title: "Controle de Constitucionalidade" 253 --- 254 255 Conteúdo do assunto... 256 ``` 257 258 --- 259 260 ## 8. Tabela de referência rápida 261 262 | Campo | Tipo | Onde funciona | Obrigatório | Efeito visual | 263 |--------------|-------------------|------------------------|-------------|------------------------------------------| 264 | `title` | string | disciplina e assunto | Sim | `<h1>`, título da aba, breadcrumb | 265 | `guide` | string (markdown) | disciplina e assunto | Não | Colapsável "guia de estudo" | 266 | `files` | lista `{name,url}`| disciplina e assunto | Não | Seção "textos" em "materiais" | 267 | `videos` | lista `{name,url}`| disciplina e assunto | Não | Seção "vídeos" em "materiais" | 268 | `audios` | lista `{name,url}`| disciplina e assunto | Não | Seção "áudios" em "materiais" | 269 | `references` | lista de strings | apenas assunto | Não | Bloco "referências" ao final | 270 | `simulado` | boolean | apenas no quiz vinculado | Não | Controla se o quiz aparece inline | 271 272 --- 273 274 ## 9. Erros comuns a evitar 275 276 - **Esquecer `name` ou `url` em `files`/`videos`/`audios`** → o link é 277 renderizado quebrado ou vazio, sem erro visível no build. 278 - **Usar `references` no `_index.md` da disciplina** esperando que apareça 279 — só funciona em páginas processadas por `single.html`. 280 - **Nomear o arquivo de quiz de forma diferente do assunto** → o quiz 281 inline não é encontrado, pois o casamento é feito por 282 `File.BaseFileName` idêntico entre `txts` e `quizzes`. 283 - **Marcar `simulado: true` sem querer** → o quiz deixa de aparecer 284 embutido na página do assunto e só fica acessível no "modo completo".