English {#english}
Navigating the Reorganized CrabPascal Docs
Phase 1 of this blog series covered fundamentals — CLI, lexer, sprints, and how to contribute. If you read Contributing to CrabPascal: Get Involved, you already know where the repo lives and how to open a PR. Phase 2 is different: we walk the Mintlify documentation site the way a new teammate would, mapping each article to the pages you actually need in daily work.
The live docs live at crabpascal.mintlify.app. The source is under mintlify/ in the Bitbucket repo. Think of Mintlify as the canonical handbook; Dev.to posts are the guided tour.
Why the docs were reorganized
CrabPascal grew from a v1.5 experimental interpreter (October 2025) to v2.22.0 with sprint-driven releases, Horse E2E tests, and honest build-exe. Old folders like documentation/00-INICIO/ still exist in git history, but Mintlify groups content by job to be done:
| You want to… | Start here |
|---|---|
| Install and run | Quickstart |
| See current capabilities | Project status |
| Understand architecture | Architecture |
| Follow releases | Changelog |
Historical reports from v1.5–v2.8 remain under Histórico with archive banners — useful for context, not for "what works today."
The home page is your compass
Open the Mintlify index. It shows v2.22.0 at a glance: real diagnostic spans, System.* RTL, Unicode strings, dual-mode run/build, and Horse HTTP parity. Four cards link to quickstart, changelog, sprint roadmap, and technical-debt backlog.
Essential CLI commands are listed once:
crab-pascal check programa.dpr # diagnostics with line/column
crab-pascal run programa.dpr # interpreter / runtime
crab-pascal build-exe programa.dpr # native binary via C toolchain
Bookmark this page. When someone asks "is feature X done?", check status + changelog before diving into Rust sources.
The documentation map: question-driven navigation
The page essentials/documentation-map is the "I want X, go to Y" cheat sheet. It answers scenarios without forcing you to memorize folder names:
-
New to the project? →
getting-started/leia-primeiro→ status → quickstart -
Need to test REST APIs? →
usage/postman-guide - Contributing code? → status → technical docs → architecture → challenges
- AI agent onboarding? → status → technical → AI context pages
The map distinguishes STATUS (snapshot now) from CHANGELOG (timeline), and TECNICO (how code works) from ARQUITETURA (why decisions were made). That separation saves hours when debugging parity gaps.
Comece aqui: the landing narrative
getting-started/comece-aqui is the human-friendly welcome: what CrabPascal is, hello-world, example folders (ping-pong, killer-app, crud), and the VS Code extension link. It bridges marketing tone and practical next steps.
After contributing (post 031), your next move depends on role:
User path: comece-aqui → quickstart → usage guides
Contributor: documentation-map → architecture → sprint reviews
Teacher: examples/ + resources/ compiler course
Practical workflow this week
- Skim the documentation map — pick your scenario row.
- Read project status for honest green/red items.
- Clone the repo and open
mintlify/docs.jsonto see how pages are wired in the sidebar. - When you edit docs, update living pages first; add archive notes to superseded content.
Docs that drift from Cargo.toml version erode trust faster than a missing feature. The Mintlify site is how we keep Phase 2 honest.
Next in series
Post 033 — Read This First: Three Onboarding Paths walks the three entry trails (leia-primeiro, comece-aqui, quickstart) so you can onboard teammates in fifteen minutes instead of fifteen tabs.
Português {#portugus}
Navegando a documentação Mintlify reorganizada
A Fase 1 desta série no blog cobriu fundamentos — CLI, lexer, sprints e como contribuir. Se você leu Contributing to CrabPascal: Get Involved, já sabe onde fica o repositório e como abrir um PR. A Fase 2 muda o foco: percorremos o site Mintlify como um colega novo faria, ligando cada artigo às páginas que você realmente usa no dia a dia.
A documentação publicada está em crabpascal.mintlify.app. O fonte fica em mintlify/ no Bitbucket. Trate o Mintlify como manual canônico; os posts no Dev.to são o tour guiado.
Por que a documentação foi reorganizada
O CrabPascal evoluiu de um interpretador experimental v1.5 (outubro/2025) para v2.22.0, com releases por sprint, testes E2E Horse e build-exe honesto. Pastas antigas como documentation/00-INICIO/ ainda existem no histórico, mas o Mintlify agrupa conteúdo pela tarefa que você quer fazer:
| Você quer… | Comece aqui |
|---|---|
| Instalar e executar | Quickstart |
| Ver o que funciona hoje | Status do projeto |
| Entender arquitetura | Arquitetura |
| Acompanhar versões | Changelog |
Relatórios históricos v1.5–v2.8 ficam em Histórico, com banner de arquivo — ótimos para contexto, não para saber o que o binário atual faz.
A home é sua bússola
Abra o index Mintlify. Ele mostra v2.22.0 de relance: spans reais no check, RTL System.*, strings Unicode, run/build dual-mode e paridade Horse. Quatro cards levam ao quickstart, changelog, roadmap de sprints e backlog de débito técnico.
Os comandos essenciais aparecem uma vez:
crab-pascal check programa.dpr # diagnósticos com linha/coluna
crab-pascal run programa.dpr # interpretador / runtime
crab-pascal build-exe programa.dpr # binário nativo via toolchain C
Salve nos favoritos. Quando alguém perguntar "a feature X já existe?", consulte status + changelog antes de mergulhar no Rust.
Mapa da documentação: navegação por pergunta
A página essentials/documentation-map é o "quero X, vou em Y". Responde cenários sem decorar nomes de pasta:
-
Novo no projeto? →
getting-started/leia-primeiro→ status → quickstart -
Testar APIs REST? →
usage/postman-guide - Contribuir código? → status → docs técnicas → arquitetura → desafios
- Agente de IA? → status → técnico → páginas de contexto IA
O mapa separa STATUS (foto atual) de CHANGELOG (linha do tempo), e TÉCNICO (como o código funciona) de ARQUITETURA (por que decidimos assim). Essa distinção economiza horas ao debugar gaps de paridade.
Comece aqui: a narrativa de entrada
getting-started/comece-aqui é o boas-vindas humano: o que é o CrabPascal, hello-world, pastas de exemplo (ping-pong, killer-app, crud) e link da extensão VS Code. Une tom de apresentação e próximos passos práticos.
Depois de contribuir (post 031), o caminho depende do papel:
Usuário: comece-aqui → quickstart → guias de uso
Contribuidor: documentation-map → arquitetura → reviews de sprint
Professor: examples/ + curso de compiladores em resources/
Fluxo prático esta semana
- Percorra o mapa da documentação — escolha a linha do seu cenário.
- Leia o status do projeto com honestidade sobre verde/vermelho.
- Clone o repo e abra
mintlify/docs.jsonpara ver como as páginas entram na sidebar. - Ao editar docs, atualize primeiro páginas vivas; marque conteúdo superseded como arquivo.
Documentação desalinhada da versão em Cargo.toml quebra confiança mais rápido que feature faltando. O site Mintlify é como mantemos a Fase 2 honesta.
Próximo da série
Post 033 — Read This First: Three Onboarding Paths percorre as três trilhas de entrada (leia-primeiro, comece-aqui, quickstart) para onboardar colegas em quinze minutos, não quinze abas.
Published on dev.to/@crabpascal · Código em CrabPascal
Top comments (0)