Caderno Parahyba

Ferramentas e documentação técnica de classe mundial construída com MyST Markdown.

🎯 Visão Geral

O Caderno Parahyba é um projeto de documentação moderna que utiliza MyST Markdown para criar livros e documentação técnica interativa. O projeto demonstra as capacidades completas do MyST, incluindo:

📚 Documentação Organizada: Livros estruturados semanticamente em books/
🔬 Conteúdo Científico: Equações matemáticas, citações, referências cruzadas e figuras
🎨 Componentes Visuais: Cards, grids, tabs, diagramas Mermaid e layouts responsivos
🚀 Notebooks Interativos: Integração completa com Jupyter, execução in-page (Thebe/Pyodide)
📤 Exportação Flexível: HTML estático, JATS XML
⚡ Gestão Moderna: uv para gerenciamento rápido de dependências Python
🛠️ CLI Integrada: Ferramenta de linha de comando para build, dev server e qualidade de código

📁 Estrutura do Projeto

caderno/
├── .github/
│   └── instructions/             # Instruções para AI agents
│       ├── uv.instructions.md    # Uso do UV
│       └── ___.instructions.md   # Regras gerais
├── books/                        # Diretório raiz do MyST
│   ├── myst.yml                  # Configuração do projeto MyST
│   ├── index.md                  # Landing page principal
│   └── guia-myst/                # Guia MyST Moderno
│       ├── index.md              # Introdução do guia
│       ├── 01-fundamentos.md     # Sintaxe básica
│       ├── 02-notebooks-intro.ipynb
│       ├── 03-notebooks-build.ipynb
│       ├── 03-notebooks-client.ipynb
│       ├── 04-visualizacao.md    # Gráficos e diagramas
│       ├── 05-componentes-ui.md  # Cards, grids, tabs
│       ├── 06-cientifico.md      # Teoremas, provas
│       ├── 07-referencias.md     # Bibliografia
│       ├── 08-plugins.md         # Extensões
│       ├── qrcode.mjs            # Plugin JS customizado
│       └── references.bib        # BibTeX
├── _build/                       # Diretório de build (auto-gerado)
├── cli.py                        # CLI customizada (Typer)
├── pyproject.toml                # Dependências Python (uv)
└── README.md                     # Este arquivo

🚀 Início Rápido

Pré-requisitos

Python 3.12+: Download

uv: Gerenciador de pacotes Python rápido

# Windows
pip install uv

# Ou com pipx
pipx install uv

Instalação

# Clonar repositório
git clone <repository-url>
cd caderno

# Instalar todas as dependências (prod + dev)
uv sync

Desenvolvimento

Usando a CLI customizada (recomendado)

# Iniciar servidor de desenvolvimento (hot-reload)
uv run python cli.py start

# Build completo
uv run python cli.py build

# Build HTML estático
uv run python cli.py build --html

# Build com execução de notebooks
uv run python cli.py build --execute

# Verificar qualidade do código
uv run python cli.py check

# Formatar código
uv run python cli.py format

# Limpar builds
uv run python cli.py clean

# Ver informações do ambiente
uv run python cli.py info

Usando comandos MyST diretos

# Entrar no diretório books
cd books

# Iniciar servidor
uv run myst start

# Build
uv run myst build --html

Acesse:

Site principal: http://localhost:3000
Guia MyST: http://localhost:3000/guia-myst

O servidor suporta hot-reload - edições são refletidas automaticamente no navegador.

📚 Conteúdo Disponível

🏠 Landing Page

Página inicial moderna com cards, grids e navegação para os livros do projeto.

📘 Guia MyST Moderno

Um guia completo e prático sobre MyST Markdown:

01-fundamentos.md - Diretivas, matemática, código, admonições
02-notebooks-intro.ipynb - Introdução a notebooks executáveis
03-notebooks-build.ipynb - Notebooks com build-time execution
03-notebooks-client.ipynb - Notebooks com client-side execution (Thebe)
04-visualizacao.md - Matplotlib, Plotly, Altair, Mermaid
05-componentes-ui.md - Cards, grids, tabs, dropdowns
06-cientifico.md - Teoremas, provas, algoritmos
07-referencias.md - Bibliografia e citações (BibTeX)
08-plugins.md - JavaScript plugins, executable plugins

Recursos incluídos:

Plugin JavaScript customizado (qrcode.mjs)
Bibliografia gerenciada (references.bib)
Exemplos de visualização com múltiplas bibliotecas
Demonstrações de componentes UI modernos

🛠️ Tecnologias

Ferramenta	Versão	Propósito
MyST Markdown	≥1.6.6	Sistema de autoria científica extensível
Python	≥3.12	Ambiente de execução
uv	Latest	Gerenciador de pacotes Python ultra-rápido
Jupyter	≥1.0.0	Notebooks interativos
Ruff	≥0.14.6	Linter e formatter Python
Pyrefly	≥0.42.2	Type checker Python
Typer	≥0.20.0	Framework para CLI
Rich	≥14.2.0	Output colorido no terminal

Bibliotecas de Visualização

Matplotlib ≥3.8.0 - Gráficos científicos clássicos
Plotly ≥5.18.0 - Gráficos interativos
Altair ≥5.0.0 - Gramática de gráficos declarativa
NumPy ≥1.26.0 - Computação numérica
Pandas ≥2.2.0 - Análise de dados
SciPy ≥1.12.0 - Computação científica

📖 Comandos Essenciais

CLI Customizada (Recomendada)

# Desenvolvimento
uv run python cli.py start           # Servidor com hot-reload
uv run python cli.py build           # Build padrão
uv run python cli.py build --html    # Build HTML estático
uv run python cli.py build --execute # Build com execução de notebooks
uv run python cli.py clean           # Limpar builds

# Qualidade de Código
uv run python cli.py check           # Verificar com Ruff + Pyrefly
uv run python cli.py check --fix     # Verificar e corrigir
uv run python cli.py format          # Formatar código
uv run python cli.py format --check  # Apenas verificar formatação

# Informações
uv run python cli.py info            # Versões do ambiente
uv run python cli.py --help          # Ajuda completa

Comandos MyST Diretos

cd books                             # Entrar no diretório MyST

# Desenvolvimento
uv run myst start                    # Servidor com hot-reload
uv run myst build --html             # Build HTML
uv run myst build --all              # Build todos exports
uv run myst clean                    # Limpar builds

# Validação
uv run myst build --check-links      # Verificar links quebrados
uv run myst build --strict           # Build com erro em warnings

Gerenciamento de Dependências

# Instalação
uv sync                              # Instalar todas dependências
uv sync --group dev                  # Instalar apenas dev
uv sync --no-dev                     # Instalar apenas produção

# Atualização
uv sync --upgrade                    # Atualizar todas
uv add mystmd --upgrade              # Atualizar MyST
uv add numpy --upgrade               # Atualizar pacote específico

# Adição de pacotes
uv add matplotlib                    # Adicionar produção
uv add --group dev pytest            # Adicionar dev

🎨 Personalização

Adicionar Novo Livro

Criar estrutura do livro:

mkdir books/meu-livro
cd books/meu-livro

Criar index.md:

---
title: Meu Livro
---

# Conteúdo do Livro

Adicionar ao books/myst.yml:

project:
  toc:
    - file: index.md
    - file: meu-livro/index.md
      title: "Meu Livro"
      children:
        - file: meu-livro/capitulo1.md

Configurar Exportações

No frontmatter de qualquer documento ou no books/myst.yml:

project:
  exports:
    - format: html
      output: exports/documento.html
    - format: jats
      output: exports/documento.jats.xml

Personalizar Tema

No books/myst.yml:

site:
  template: book-theme  # ou article-theme
  options:
    logo: ./logo.png
    logo_text: "Meu Projeto"
    hide_toc: false
    hide_outline: false

🐛 Solução de Problemas

Servidor não inicia

# Limpar builds e cache
uv run python cli.py clean

# Verificar se a porta 3000 está livre
# Se estiver em uso, o MyST usará outra porta automaticamente

Links quebrados

Use paths relativos: ./capitulo.md
Ou use cross-references com labels: [texto](#label)
Verifique com: cd books; uv run myst build --check-links

Build lento

# Limpar cache completo
cd books
uv run myst clean --all

# Build incremental sem execução
uv run python cli.py build --html

Notebooks não executam

# Verificar kernel instalado
uv run jupyter kernelspec list

# Instalar/reinstalar kernel
uv sync

# Executar notebooks explicitamente
uv run python cli.py build --execute

Erros de importação Python

# Verificar ambiente
uv run python cli.py info

# Reinstalar dependências
uv sync --reinstall

Plugin JavaScript não carrega

Verifique o path em myst.yml: plugins: ["./plugin.mjs"]
Plugin deve exportar: export const plugin = { name: "...", ... }
Console do navegador mostra erros de plugins

🏗️ Arquitetura do Projeto

Fluxo de Trabalho

┌─────────────────┐
│  Markdown (.md) │
│  Notebooks (.ipynb) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   MyST Parser   │ ← books/myst.yml (config)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  AST + Plugins  │ ← qrcode.mjs (custom plugin)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Render Engine  │
└────────┬────────┘
         │
         ├─→ HTML (books/_build/html/)
         ├─→ JATS XML
         └─→ PDF (via LaTeX)

Diretórios Importantes

books/ - Raiz do projeto MyST (executar comandos aqui)
books/_build/ - Output compilado (não versionar)
books/guia-myst/ - Conteúdo do guia
.github/instructions/ - Regras para AI agents
cli.py - CLI customizada com Typer

Configuração em Camadas

Global: books/myst.yml - Configuração do projeto inteiro
Frontmatter: Metadados por documento (YAML no topo do arquivo)
CLI: Flags de build e execução

🎓 Recursos de Aprendizado

🤝 Contribuindo

Contribuições são bem-vindas! Para contribuir:

Fork o projeto
Crie uma branch: git checkout -b feature/nova-feature
Commit suas mudanças: git commit -am 'Adiciona nova feature'
Push para a branch: git push origin feature/nova-feature
Abra um Pull Request

Diretrizes

Siga as instruções em .github/instructions/
Use uv run python cli.py check antes de commitar
Formate código com uv run python cli.py format
Teste localmente com uv run python cli.py start

📄 Licença

Conteúdo: CC-BY-4.0
Código: MIT

📚 Recursos

MyST Guide: https://mystmd.org/guide
uv Docs: https://docs.astral.sh/uv/
MyST Sandbox: https://mystmd.org/sandbox
Thebe Docs: https://thebe.readthedocs.io/

Criado com ❤️ usando MyST Markdown | Documentação | GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
books		books
.gitignore		.gitignore
.python-version		.python-version
README.md		README.md
cli.py		cli.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Caderno Parahyba

🎯 Visão Geral

📁 Estrutura do Projeto

🚀 Início Rápido

Pré-requisitos

Instalação

Desenvolvimento

Usando a CLI customizada (recomendado)

Usando comandos MyST diretos

📚 Conteúdo Disponível

🏠 Landing Page

📘 Guia MyST Moderno

🛠️ Tecnologias

Bibliotecas de Visualização

📖 Comandos Essenciais

CLI Customizada (Recomendada)

Comandos MyST Diretos

Gerenciamento de Dependências

🎨 Personalização

Adicionar Novo Livro

Configurar Exportações

Personalizar Tema

🐛 Solução de Problemas

Servidor não inicia

Links quebrados

Build lento

Notebooks não executam

Erros de importação Python

Plugin JavaScript não carrega

🏗️ Arquitetura do Projeto

Fluxo de Trabalho

Diretórios Importantes

Configuração em Camadas

🎓 Recursos de Aprendizado

Documentação Oficial

Exemplos e Templates

Comunidade

🤝 Contribuindo

Diretrizes

📄 Licença

📚 Recursos

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages