commit 839690762cd2bb4a091853a0d976bf342f7f0ec6
parent 1ce1a16430093234f7acf271a3c144e6ffff6083
Author: Sivaldo <gxixtx@xsxixvxaxlxdxoxdxaxvxix.xcxoxm>
Date: Sat, 19 Sep 2026 19:26:58 -0300
chore: adicionar manual de frontmatter
Diffstat:
1 file changed, 284 insertions(+), 0 deletions(-)
diff --git a/static/manual-frontmatter.md b/static/manual-frontmatter.md
@@ -0,0 +1,284 @@
+# Manual de Front Matter — Disciplinas e Assuntos
+
+Este manual documenta todos os campos de front matter (YAML) reconhecidos pelos
+templates `single.html`, `disc-extras.html` e `baseof.html`, cobrindo tanto
+páginas de **disciplina** (`_index.md` dentro de `content/txts/<disciplina>/`)
+quanto páginas de **assunto** (arquivos `.md` individuais dentro de uma
+disciplina).
+
+---
+
+## 1. Estrutura de pastas esperada
+
+```
+content/
+└── txts/
+ └── direito-constitucional/ ← disciplina (_index.md)
+ ├── _index.md
+ ├── principios-fundamentais.md ← assunto
+ ├── controle-de-constitucionalidade.md
+ └── ...
+```
+
+- A **disciplina** é a seção (`Section = "txts"`), identificada pelo `_index.md`.
+- O **assunto** é uma página regular dentro dela.
+- O slug da disciplina (`$discSlug`) é inferido automaticamente pelo Hugo a
+ partir do caminho da URL — não é um campo do front matter.
+
+---
+
+## 2. Campos comuns (disciplina E assunto)
+
+Estes campos são lidos pelo partial `disc-extras.html`, que é compartilhado
+entre os dois tipos de página. Funcionam exatamente da mesma forma nos dois
+contextos.
+
+### `guide` (string, markdown)
+
+Texto do guia de estudo. Renderizado com `markdownify` dentro de um `<details>`
+colapsável rotulado **"guia de estudo"**.
+
+```yaml
+guide: |
+ ## Como estudar este conteúdo
+ 1. Leia o texto completo antes dos exercícios.
+ 2. Preste atenção nas notas de rodapé.
+ 3. Faça o quiz ao final.
+```
+
+- Aceita qualquer sintaxe Markdown (listas, negrito, links, etc).
+- Se omitido, o colapsável de guia simplesmente não aparece.
+
+### `files` (lista de objetos)
+
+Materiais em formato de texto/link. Aparecem sob o rótulo **"textos"** dentro
+do colapsável "materiais", com ícone ↗.
+
+```yaml
+files:
+ - name: "Resumo em PDF"
+ url: "https://exemplo.com/resumo.pdf"
+ - name: "Artigo de referência"
+ url: "https://exemplo.com/artigo"
+```
+
+- Cada item **exige** `name` e `url`.
+- Abre em nova aba (`target="_blank"`).
+
+### `videos` (lista de objetos)
+
+Mesma estrutura de `files`, exibidos sob o rótulo **"vídeos"**, ícone ▶.
+
+```yaml
+videos:
+ - name: "Aula sobre o tema"
+ url: "https://youtube.com/watch?v=xxxx"
+```
+
+### `audios` (lista de objetos)
+
+Mesma estrutura de `files`, exibidos sob o rótulo **"áudios"**, ícone ♪.
+
+```yaml
+audios:
+ - name: "Podcast explicativo"
+ url: "https://youtube.com/watch?v=yyyy"
+```
+
+### Comportamento do bloco "materiais"
+
+- O colapsável "materiais" **só aparece** se `files`, `videos` ou `audios`
+ tiver pelo menos um item.
+- O contador no cabeçalho (`N itens`) soma os três juntos.
+- A ordem de exibição é sempre: textos → vídeos → áudios.
+
+### Regra geral de visibilidade
+
+O bloco de colapsáveis inteiro (`disc-extras-wrap`) só é renderizado se
+**pelo menos um** destes campos estiver presente: `guide`, `files`, `videos`
+ou `audios`. Se nenhum existir, nada é exibido — sem erro, sem espaço vazio.
+
+---
+
+## 3. Campos exclusivos de página de **assunto**
+
+Estes campos só são lidos por `single.html`, ou seja, só fazem sentido em
+páginas de assunto individuais (não no `_index.md` da disciplina, a menos
+que o template de listagem da seção também os leia explicitamente).
+
+### `title` (string, obrigatório)
+
+Título do assunto. Usado em:
+- `<h1 class="text-title">`
+- `<title>` da aba do navegador (`{{ .Title }} · {{ .Site.Title }}`)
+- Breadcrumb final (`<span class="breadcrumb">`)
+
+```yaml
+title: "Princípios Fundamentais"
+```
+
+### `references` (lista de strings)
+
+Referências bibliográficas do assunto. Cada item vira um `<p>` dentro do
+bloco **"referências"**, exibido ao final da página.
+
+```yaml
+references:
+ - "MENDES, Gilmar. Curso de Direito Constitucional. 2023."
+ - "BARROSO, Luís Roberto. O Direito Constitucional e a Efetividade..."
+```
+
+- Só aparece se o campo existir e não estiver vazio.
+- Não aceita objetos — apenas strings simples.
+
+### Quiz inline (automático — não é campo de front matter)
+
+Se existir uma página em `content/quizzes/<disciplina>/<mesmo-slug>.md`
+que **não** tenha `simulado: true` nem `"simulado"` no nome do arquivo, o
+assunto automaticamente ganha uma seção de exercícios inline
+("exercícios deste assunto"), com quiz interativo carregado via JavaScript.
+
+Não é necessário declarar nada no front matter do assunto para isso
+funcionar — a ligação é feita pelo casamento de nomes de arquivo
+(`File.BaseFileName`) entre `txts/<disciplina>/<slug>.md` e
+`quizzes/<disciplina>/<slug>.md`.
+
+Campo relevante **no quiz**, não no assunto:
+
+```yaml
+# dentro do arquivo de quiz correspondente
+simulado: false # false ou omitido = elegível a aparecer inline
+ # true = tratado como simulado, não aparece inline
+```
+
+---
+
+## 4. Campos exclusivos de página de **disciplina** (`_index.md`)
+
+Não há campos exclusivos de disciplina identificados nos templates
+analisados — `_index.md` usa os mesmos `guide` / `files` / `videos` /
+`audios` da seção 2. O `title` da disciplina também é obrigatório e é o que
+aparece:
+
+- No breadcrumb de todos os assuntos filhos (`{{ .Title }}` do
+ `range $.Site.Sections`).
+- No link de "voltar" para a disciplina a partir de qualquer assunto.
+
+```yaml
+title: "Direito Constitucional"
+```
+
+> ⚠️ **Atenção:** o campo `references` é lido apenas em `single.html`.
+> Se o `_index.md` da disciplina usa um template de listagem diferente
+> (`list.html` ou similar) que não chama esse trecho, `references` não
+> terá efeito ali. Da mesma forma, o partial `disc-extras.html` só é
+> aplicado ao `_index.md` se o template de listagem da seção também o
+> chamar explicitamente — o comportamento não é automático fora de
+> `single.html`.
+
+---
+
+## 5. Exemplo completo — disciplina
+
+`content/txts/direito-constitucional/_index.md`
+
+```yaml
+---
+title: "Direito Constitucional"
+
+guide: |
+ ## Como estudar Direito Constitucional
+ 1. Comece pela teoria da constituição.
+ 2. Depois avance para direitos fundamentais.
+ 3. Organização do poder por último.
+
+files:
+ - name: "Ementa da disciplina"
+ url: "https://exemplo.com/ementa.pdf"
+ - name: "Bibliografia completa"
+ url: "https://exemplo.com/bibliografia"
+
+videos:
+ - name: "Aula introdutória"
+ url: "https://youtube.com/watch?v=xxxx"
+
+audios:
+ - name: "Podcast sobre a matéria"
+ url: "https://youtube.com/watch?v=yyyy"
+---
+```
+
+## 6. Exemplo completo — assunto
+
+`content/txts/direito-constitucional/principios-fundamentais.md`
+
+```yaml
+---
+title: "Princípios Fundamentais"
+
+guide: |
+ ## Como estudar este assunto
+ 1. Leia o texto completo antes dos exercícios.
+ 2. Preste atenção nas notas de rodapé.
+ 3. Faça o quiz ao final.
+
+files:
+ - name: "Resumo em PDF"
+ url: "https://exemplo.com/resumo.pdf"
+
+videos:
+ - name: "Aula sobre o tema"
+ url: "https://youtube.com/watch?v=xxxx"
+
+audios:
+ - name: "Podcast explicativo"
+ url: "https://youtube.com/watch?v=yyyy"
+
+references:
+ - "MENDES, Gilmar. Curso de Direito Constitucional. 2023."
+ - "BARROSO, Luís Roberto. O Direito Constitucional e a Efetividade..."
+---
+
+Conteúdo do assunto em Markdown...
+```
+
+## 7. Exemplo mínimo (sem extras)
+
+Válido tanto para disciplina quanto para assunto — nenhum colapsável
+aparece, apenas título e conteúdo:
+
+```yaml
+---
+title: "Controle de Constitucionalidade"
+---
+
+Conteúdo do assunto...
+```
+
+---
+
+## 8. Tabela de referência rápida
+
+| Campo | Tipo | Onde funciona | Obrigatório | Efeito visual |
+|--------------|-------------------|------------------------|-------------|------------------------------------------|
+| `title` | string | disciplina e assunto | Sim | `<h1>`, título da aba, breadcrumb |
+| `guide` | string (markdown) | disciplina e assunto | Não | Colapsável "guia de estudo" |
+| `files` | lista `{name,url}`| disciplina e assunto | Não | Seção "textos" em "materiais" |
+| `videos` | lista `{name,url}`| disciplina e assunto | Não | Seção "vídeos" em "materiais" |
+| `audios` | lista `{name,url}`| disciplina e assunto | Não | Seção "áudios" em "materiais" |
+| `references` | lista de strings | apenas assunto | Não | Bloco "referências" ao final |
+| `simulado` | boolean | apenas no quiz vinculado | Não | Controla se o quiz aparece inline |
+
+---
+
+## 9. Erros comuns a evitar
+
+- **Esquecer `name` ou `url` em `files`/`videos`/`audios`** → o link é
+ renderizado quebrado ou vazio, sem erro visível no build.
+- **Usar `references` no `_index.md` da disciplina** esperando que apareça
+ — só funciona em páginas processadas por `single.html`.
+- **Nomear o arquivo de quiz de forma diferente do assunto** → o quiz
+ inline não é encontrado, pois o casamento é feito por
+ `File.BaseFileName` idêntico entre `txts` e `quizzes`.
+- **Marcar `simulado: true` sem querer** → o quiz deixa de aparecer
+ embutido na página do assunto e só fica acessível no "modo completo".
