` produz uma `div` de verdade. Em `.mdx`, uma tag com inicial maiúscula é lida como componente, e o HTML cru precisa ser válido para JSX. ## Markdown Além do GFM, você pode usar **HTML padrão**, com suporte a [Tailwind](https://tailwindcss.com): ```md

Uma caixa, montada na mão.

``` resultado:

Uma caixa, montada na mão.

As cores vêm do [react-mcu](https://github.com/abernier/react-mcu), geradas a partir da sua cor de destaque. Por isso `text-on-surface-variant` acima funciona em tema claro e escuro sem você fazer nada. As páginas seguintes documentam cada componente disponível. ]]> Você entrega ao DoDocs uma pasta de arquivos `.md`/`.mdx`. Ele devolve um site estático completo, com navegação lateral, busca, sumário, destaque de sintaxe, temas claro e escuro, e links de anterior e próximo. Você não escreve nenhuma linha de código de aplicação. O problema que o DoDocs resolve Como a estrutura de pastas vira o site Por onde começar ## O problema Documentação boa morre por atrito. Se publicar exige configurar um site, instalar um framework e manter um build, a documentação fica desatualizada, ou nem chega a existir. O DoDocs tira esse atrito do caminho. A documentação continua sendo Markdown puro, versionada no mesmo repositório do código, no mesmo commit da mudança que ela descreve. Publicar é adicionar uma GitHub Action e apontá-la para a pasta. ## A estrutura de pastas define o site Não existe arquivo de rotas nem índice para manter. Pastas viram seções da barra lateral e arquivos viram páginas: ``` docs/ ├── getting-started/ │ ├── introduction.md │ └── configuration.md └── writing/ └── markdown.md ``` Essa árvore é exatamente a barra lateral. Criar um arquivo cria uma página. Mover um arquivo move a página. Nada mais precisa ser tocado. A ordem, os agrupamentos e os nomes exibidos podem ser ajustados quando o padrão não serve, mas são ajustes opcionais, não obrigações. Veja [`nav_order` e `nav_labels`](/github-actions/introduction). ## Por onde começar - [Configuração](/getting-started/configuration): as opções que você passa para a Action. - [GitHub Actions](/github-actions/introduction): publicar no GitHub Pages. - [Escrevendo](/authoring/introduction): frontmatter, componentes e o que o Markdown aceita aqui. ## Sobre este projeto O DoDocs nasceu de um fork do [pmndrs/docs](https://github.com/pmndrs/docs), o gerador de documentação do [Poimandres](https://pmnd.rs), e hoje é um projeto independente. O código original é licenciado sob MIT, e a licença e o copyright estão preservados no repositório. O que mudou em relação ao original: - **Barra lateral que funciona para qualquer projeto.** Navegação recursiva em qualquer profundidade, com ordenação, agrupamento por rótulo e nomes de exibição configuráveis. Uma pasta sem página própria leva o leitor para a primeira página dentro dela, em vez de dar 404. - **Interface em português ou inglês.** O conteúdo nunca é traduzido, apenas a interface do site. - **Sem a bagagem do ecossistema original.** Saíram o servidor MCP, o índice das bibliotecas do Poimandres e os sandboxes React, que só serviam ao projeto de origem. O DoDocs é um gerador de documentação, e nada além disso. - **Mais simples de operar.** Uma imagem Docker publicada e um workflow reutilizável. Quem consome não instala nada, nem compila o gerador. ]]> O DoDocs oferece um [workflow reutilizável](https://docs.github.com/en/actions/sharing-automations/reusing-workflows#calling-a-reusable-workflow) que você chama do seu próprio repositório. Não há nada para instalar: a Action baixa a imagem pronta, constrói o site e publica no GitHub Pages. ## O workflow No seu repositório, crie `.github/workflows/docs.yml`: ```yml name: Docs on: push: branches: ['main'] workflow_dispatch: jobs: build: permissions: contents: read pages: write id-token: write uses: thiagocajadev/do-docs/.github/workflows/build.yml@main with: mdx: 'docs' # sua pasta de Markdown libname: 'Meu Projeto' # nome exibido no cabeçalho home_redirect: '/getting-started/introduction' locale: 'pt-BR' # 'en' (padrão) ou 'pt-BR' icon: '📘' github: 'https://github.com/acme/meu-projeto' theme_primary: '#1f6feb' deploy: needs: build runs-on: ubuntu-latest permissions: pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@v4 ``` Faça push na `main` e o site é publicado. A lista completa de opções está na [configuração](/getting-started/configuration). O GitHub Pages precisa estar habilitado no repositório, com a origem definida como **GitHub Actions** (`Settings` → `Pages` → `Source`). Sem isso, o workflow falha logo no começo. Veja o [`docs.yml` deste repositório](https://github.com/thiagocajadev/do-docs/blob/main/.github/workflows/docs.yml) para um exemplo real: é ele que publica o site que você está lendo. ## Ordem da barra lateral Por padrão, as pastas são listadas em ordem alfabética, e as páginas dentro de cada pasta seguem o `nav` do frontmatter. A entrada `nav_order` assume essa ordem. A forma mais simples é listar as pastas, e a primeira fica no topo: ```yml with: nav_order: | - javascript - typescript - csharp - sql ``` Para dividir a barra lateral em grupos com rótulo, use uma chave por grupo, e uma lista abaixo dela: ```yml with: nav_order: | Estrutura: - html - css Programação: - javascript - typescript - csharp Banco de Dados: - sql ``` Aninhar uma pasta sob a própria chave também ordena o conteúdo dela: ```yml with: nav_order: | Programação: - javascript: - setup - conventions - frameworks - typescript ``` Os nomes são os das pastas e páginas como aparecem na URL: `quick-reference`, não `Quick reference`. O que você deixar de fora mantém a ordem padrão e aparece depois do que você ordenou. Ou seja, uma pasta nova continua surgindo na barra lateral sem você tocar na configuração. Os links de **Anterior** e **Próximo** no rodapé das páginas seguem essa mesma ordem. ## Nomes exibidos Os nomes das pastas são capitalizados a partir do slug, o que erra em siglas: `sql` vira `Sql` e `css` vira `Css`. A entrada `nav_labels` define o nome exibido, indexado pelo slug: ```yml with: nav_labels: | sql: SQL css: CSS html: HTML javascript: JavaScript csharp: C# ``` Um slug que você não listar mantém a capitalização padrão. Só o texto da barra lateral muda: as URLs continuam usando o nome da pasta (`/sql/readme`). ## Pastas sem página própria Uma pasta que contém páginas mas não é uma página, como `sql/conventions/`, leva o leitor para a primeira página dentro dela. Isso vale tanto para o clique na barra lateral quanto para um link do Markdown apontando para a pasta (`[conventions/](../conventions/)`), que antes resultava em 404. ]]> O `Intro` é o parágrafo de abertura de uma página, renderizado maior que o corpo do texto. Serve para dizer, em duas ou três linhas, o que a página cobre. ```md Aponte o DoDocs para uma pasta de Markdown e ele devolve um site. ``` resultado: Aponte o DoDocs para uma pasta de Markdown e ele devolve um site. Aceita Markdown dentro: **negrito**, `código` e [links](https://github.com/thiagocajadev/do-docs). ]]> Toda opção pode ser passada como entrada da GitHub Action (em minúsculas) ou como variável de ambiente (em maiúsculas). São a mesma coisa, escrita de dois jeitos. Só três opções são obrigatórias. O resto tem padrão razoável. ## Essenciais | Entrada | Variável | O que faz | | --------------- | ----------------------- | --------------------------------------------------------------------- | | `mdx`\* | `MDX` | Caminho da pasta de Markdown, relativo à raiz do repositório: `docs` | | `libname`\* | `NEXT_PUBLIC_LIBNAME` | Nome exibido no cabeçalho | | `home_redirect`\* | `HOME_REDIRECT` | Página para onde a raiz (`/`) redireciona | | `locale` | `NEXT_PUBLIC_LOCALE` | Idioma da interface: `en` (padrão) ou `pt-BR`. Veja [Idioma](#idioma) | | `icon` | `ICON` | Emoji ou imagem usada como favicon: `📘` ou `/icon.png` | | `logo` | `LOGO` | Imagem usada nos metadados de compartilhamento | | `github` | `GITHUB` | URL do repositório, exibida no cabeçalho | ## Barra lateral | Entrada | Variável | O que faz | | ------------ | ------------ | ------------------------------------------------------------------ | | `nav_order` | `NAV_ORDER` | Ordem e agrupamento das pastas. Veja [GitHub Actions](/github-actions/introduction) | | `nav_labels` | `NAV_LABELS` | Nomes exibidos, para os slugs que a capitalização automática erra | ## Tema O tema inteiro é derivado de uma única cor de destaque, então na prática você só precisa mexer em `theme_primary`. | Entrada | Variável | Padrão | O que faz | | ----------------- | ----------------- | ----------- | -------------------------------------------- | | `theme_primary` | `THEME_PRIMARY` | `#323e48` | Cor de destaque da qual o tema é gerado | | `theme_scheme` | `THEME_SCHEME` | `tonalSpot` | Esquema de geração das cores | | `theme_contrast` | `THEME_CONTRAST` | `0` | Contraste, entre `-1` e `1` | | `theme_note` | `THEME_NOTE` | `#1f6feb` | Cor do alerta `NOTE` | | `theme_tip` | `THEME_TIP` | `#238636` | Cor do alerta `TIP` | | `theme_important` | `THEME_IMPORTANT` | `#8957e5` | Cor do alerta `IMPORTANT` | | `theme_warning` | `THEME_WARNING` | `#d29922` | Cor do alerta `WARNING` | | `theme_caution` | `THEME_CAUTION` | `#da3633` | Cor do alerta `CAUTION` | Os valores de `theme_scheme` são `content`, `expressive`, `fidelity`, `monochrome`, `neutral`, `tonalSpot` e `vibrant`. ## Build Você raramente precisa mexer nestas. A Action já as preenche. | Entrada | Variável | O que faz | | -------------------------------- | -------------------------------- | ------------------------------------------------------ | | `base_path` | `BASE_PATH` | Prefixo da URL final, quando o site não está na raiz | | `static_page_generation_timeout` | `STATIC_PAGE_GENERATION_TIMEOUT` | Segundos por página. Aumente para bases grandes | | `docker_tag` | — | Tag da imagem `ghcr.io/thiagocajadev/do-docs`. Padrão: `3` | | — | `DIST_DIR` | Pasta de saída | | — | `OUTPUT` | `export` gera site estático | | — | `MDX_BASEURL` | URL base usada para resolver imagens relativas | | — | `SOURCECODE_BASEURL` | URL base do link `sourcecode:` do frontmatter | | — | `NEXT_PUBLIC_URL` | URL final do site publicado | | — | `CONTRIBUTORS_PAT` | Token do GitHub, usado pelo componente `Contributors` | ## Idioma `locale` define o idioma da interface do DoDocs: a caixa de busca, o título "Nesta Página", os rótulos de anterior e próximo, o alternador de tema e o rodapé. Os valores aceitos são `en` (padrão) e `pt-BR`. Um valor desconhecido cai para o inglês, em vez de quebrar o build. Isso não afeta o seu conteúdo. O DoDocs renderiza o seu Markdown no idioma em que você escreveu. Cada site publicado tem um idioma só, definido no momento do build. ]]> Resume os pontos que a página aborda. Costuma vir logo depois do `Intro`, para o leitor decidir se é isso que ele procura. ```md Primeiro item Segundo item, com **destaque** ``` resultado: Primeiro item Segundo item, com **destaque** O `title` é opcional. Cada `KeypointsItem` vira um marcador, e aceita Markdown. ]]> O DoDocs é distribuído como imagem Docker. Para ver o seu site localmente, você roda a mesma imagem que a GitHub Action roda, então o que você vê é o que vai ao ar. ## Sem instalar nada Aponte o script de preview para a sua pasta: ```sh $ curl -sL https://raw.githubusercontent.com/thiagocajadev/do-docs/refs/heads/main/preview.sh | \ MDX="docs" \ ICON="📘" \ DOCKER_IMAGE="ghcr.io/thiagocajadev/do-docs:latest" \ sh ``` Ele constrói o site dentro do Docker e serve o resultado. Nada é instalado na sua máquina, e qualquer opção da [configuração](/getting-started/configuration) pode ser passada do mesmo jeito. Em `DOCKER_IMAGE`, você pode fixar qualquer versão publicada no [registro de containers](https://github.com/thiagocajadev/do-docs/pkgs/container/do-docs). ## Rodando o Docker direto Se preferir chamar a imagem você mesmo: ```sh $ docker run --rm --init \ -v "./docs":/app/docs \ -e MDX=docs \ -e DIST_DIR=docs/out \ -e OUTPUT=export \ -e NEXT_PUBLIC_LIBNAME="Meu Projeto" \ -e NEXT_PUBLIC_LOCALE=pt-BR \ -e HOME_REDIRECT=/getting-started/introduction \ ghcr.io/thiagocajadev/do-docs:3 pnpm run build ``` O site estático sai em `docs/out`, pronto para publicar em qualquer host. Os caminhos das variáveis são relativos a `/app`, **dentro** do container, onde a sua pasta foi montada como `docs`. Por isso `MDX=docs`, e não o caminho da sua máquina. ## Imagens ao lado da documentação Se as suas imagens ficam numa pasta irmã da documentação, referenciadas como `../assets/foto.png` no Markdown, monte essa pasta também: ```sh -v "./docs":/app/docs \ -v "./assets":/app/assets \ ``` A GitHub Action já faz isso sozinha. ## Desenvolvendo o próprio DoDocs Se você clonou este repositório para mexer no gerador: ```sh $ pnpm install $ pnpm dev ``` Um clone novo já sobe um site funcionando, usando a pasta `example/`, para você ver a estrutura antes de apontar para conteúdo real. Os padrões vêm do `.env.development`, que é versionado. Para usar a sua pasta, `MDX=./minha-doc pnpm dev`, ou sobrescreva no `.env.local`, que é ignorado pelo git. ]]> Destaca uma observação que o leitor não deveria passar batido, sem interromper a leitura. ```md Lembre de definir `MDX` antes de rodar o build. ``` resultado: Lembre de definir `MDX` antes de rodar o build. Para avisos com peso semântico (nota, dica, alerta, perigo), prefira os [alertas do GitHub](/authoring/gha), que já vêm com cor e ícone próprios. ]]> Os [alertas do GitHub](https://github.com/orgs/community/discussions/16925) funcionam aqui, com a mesma sintaxe. Cada nível tem cor e ícone próprios, derivados do seu tema. Escreva como uma citação, começando pelo nível: ```md > [!NOTE] > Informação que o leitor deve considerar, mesmo passando o olho. ``` resultado: > [!NOTE] > Informação que o leitor deve considerar, mesmo passando o olho. Os cinco níveis: > [!NOTE] > Informação que o leitor deve considerar, mesmo passando o olho. > [!TIP] > Algo opcional, que ajuda o leitor a se sair melhor. > [!IMPORTANT] > Informação essencial para o leitor ter sucesso. > [!WARNING] > Conteúdo urgente, que pede atenção imediata. > [!CAUTION] > Risco real, com consequências negativas se ignorado. As cores de cada nível são configuráveis: veja `theme_note`, `theme_tip`, `theme_important`, `theme_warning` e `theme_caution` na [configuração](/getting-started/configuration). ]]> Blocos de código comuns, com destaque de sintaxe e botão de copiar. Você pode numerar as linhas e realçar as que importam. Um bloco normal, indicando a linguagem: ````md ```sql SELECT id, title FROM docs WHERE published = true ORDER BY nav; ``` ```` resultado: ```sql SELECT id, title FROM docs WHERE published = true ORDER BY nav; ``` ## Numerando e realçando linhas Depois da linguagem, `showLineNumbers` numera, e `{1,4-6}` realça as linhas indicadas: ````md ```tsx {1,4-6} showLineNumbers type Props = { who: string } function Hi({ who }: Props) { return (

Olá, {who}!

) } ``` ```` resultado: ```tsx {1,4-6} showLineNumbers type Props = { who: string } function Hi({ who }: Props) { return (

Olá, {who}!

) } ``` Use o realce para apontar a linha que a prosa está explicando, em vez de descrever onde ela está. ]]> Diagramas do [Mermaid](https://mermaid.js.org/) são escritos como texto, dentro de um bloco de código. Eles se adaptam sozinhos ao tema claro e escuro. ## Fluxograma ````md ```mermaid graph TD A[Escreve o Markdown] --> B{Faz push?} B -->|Sim| C[A Action constrói] B -->|Não| D[Fica no seu editor] C --> E[Site publicado] ``` ```` resultado: ```mermaid graph TD A[Escreve o Markdown] --> B{Faz push?} B -->|Sim| C[A Action constrói] B -->|Não| D[Fica no seu editor] C --> E[Site publicado] ``` ## Diagrama de sequência ````md ```mermaid sequenceDiagram participant Autor participant Action participant Pages Autor->>Action: push na main Action->>Action: constrói o site Action->>Pages: publica Pages-->>Autor: site no ar ``` ```` resultado: ```mermaid sequenceDiagram participant Autor participant Action participant Pages Autor->>Action: push na main Action->>Action: constrói o site Action->>Pages: publica Pages-->>Autor: site no ar ``` Como o diagrama é texto, ele vive no mesmo commit da mudança que descreve, e o diff mostra o que mudou nele. ]]> Imagens usam a sintaxe normal do Markdown. O caminho pode ser relativo ao arquivo, absoluto, ou uma URL completa. ```md ![Uma legenda](foto.png) ![Uma legenda](../imagens/foto.png) ![Uma legenda](https://exemplo.com/foto.png) ``` O DoDocs resolve o caminho e copia a imagem para o site, então ela funciona tanto no GitHub, ao ler o `.md` direto no repositório, quanto no site publicado. ## Imagens numa pasta ao lado Se as suas imagens ficam numa pasta irmã da documentação, referenciadas como `../assets/foto.png`, a GitHub Action já monta essa pasta e copia o conteúdo. ``` meu-projeto/ ├── docs/ │ └── guia/pagina.md ← ![](../../assets/foto.png) └── assets/ └── foto.png ``` Rodando o Docker na mão, monte a pasta explicitamente. Veja [rodando local](/getting-started/local). ]]> Gera um índice de todas as páginas da documentação, agrupadas pela seção a que pertencem. Útil como página inicial ou como mapa do site. ```md ``` resultado: A lista é montada a partir dos arquivos, então ela nunca fica desatualizada: uma página nova aparece aqui sozinha. ]]> Lista os contribuidores de um repositório do GitHub, com foto e link para o perfil. ```md ``` resultado: Os dados vêm da API do GitHub, no momento do build. Em repositórios privados, ou para evitar o limite de requisições anônimas, defina `CONTRIBUTORS_PAT` com um token do GitHub. A Action já passa o token do próprio workflow. ]]>