---
description: How to add a new guide to the Educação section.
load-when: Adding a guide / how-to / reference page under /educacao.
---

# Add a guide

<scope>
Guides live under `docs/`. Each guide is a single Markdown file. Sidebar autogenerates from the folder structure.
</scope>

<instructions>
<step n="1">
**Decide the slug.** Pick a kebab-case slug for the URL (e.g. `claude-code-overview`). The file becomes `docs/<slug>.md` and the URL becomes `/educacao/<slug>`.
</step>

<step n="2">
**Create the file.** `docs/<slug>.md` with frontmatter:

```markdown
---
title: Título do guia
description: Resumo de uma linha para meta description e cards sociais.
---

# Título do guia

Conteúdo em Markdown.
```

For nested guides, group under a folder (e.g. `docs/claude-code/getting-started.md`). Each folder becomes a sidebar category.
</step>

<step n="3">
**Verify locally.** `npm run start`. Open `/educacao/<slug>` and confirm the guide renders, the sidebar entry appears, and any code blocks highlight.
</step>

<step n="4">
**Update `static/llms.txt`.** Add a line under `## Educação` linking to the new entry's `.md` source: `- [<title>](https://gazperi.com/educacao/<slug>.md): <one-line summary>`. Keeps LLM index in sync.
</step>
</instructions>

<conventions>
- Markdown only. No MDX unless the guide needs React components — and if it does, use `.mdx` instead of `.md`.
- No HTML in the body unless necessary.
- Title in frontmatter and in the H1 should match.
- Description ≤ 160 chars (fits meta description and OG description).
- Voice: PT-BR, follow `DOCS/brand-voice/` rules.
</conventions>

<antipattern>
- Skipping the `description` frontmatter — falls back to a generated snippet that often misrepresents the page in social previews.
- Forgetting to update `static/llms.txt` — site stays browser-readable but the LLM index drifts.
- Creating a `.mdx` file when plain `.md` would do — adds JSX parser overhead with no payoff.
</antipattern>