Exportar para `.docx` (padrão X-Adm)¶

Gera um Word (.docx) no visual da X-Adm (A4, Verdana, cabeçalho/rodapé/logo, sumário, callouts, tabelas, diagramas Mermaid como imagem) a partir de um Markdown da docs/ — pré-projeto (nível 1) ou o livro do projeto (nível 2).

O .docx é documento gerado (constituição §1.3): a fonte da verdade é o Markdown; o Word é saída e não se commita (a exceção do §1.3 é só o pré-projeto, quando a diretoria exige). O pipeline vive na toolchain e é baixado fresco — o jeito sem fricção é a skill /xadm-docx.

Pré-requisitos¶

Ferramenta	Para quê	Instalar
pandoc	Markdown → DOCX	`apt install pandoc` · `brew install pandoc` · Windows: instalador em pandoc.org
mmdc	Mermaid → PNG offline	`npm i -g @mermaid-js/mermaid-cli`
python3	os scripts (só stdlib)	já vem no sistema

O mmdc usa um Chrome/Chromium. O pipeline detecta o Chrome do sistema (PUPPETEER_EXECUTABLE_PATH) e aplica --no-sandbox por default — funciona em WSL/headless/Windows sem baixar o navegador do puppeteer. Para forçar outro navegador/opções, exporte PUPPETEER_EXECUTABLE_PATH ou MMDC_PUPPETEER_CONFIG.

mmdc instalado mas falha — falta o Chrome (CI/runner limpo)

Num ambiente sem Chrome de sistema nem o do puppeteer (CI típico), o mmdc falha — e o erro do pipeline diz isso, com as saídas offline (sem cair no .ink): (1) instalar um Chrome/Chromium (ex. apt install chromium); (2) apontar um — export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome; ou (3) baixar o do puppeteer — npx puppeteer browsers install chrome-headless-shell. Só com MERMAID_RENDERER=ink o pipeline usa a rede (não, em pré-projeto/conteúdo confidencial — §1.9).

Receita¶

A skill /xadm-docx baixa o pipeline fresco de https://docs.xadm.biz/toolchain/raw/scripts/export-docx/ e roda. À mão é o mesmo:

DL="$(mktemp -d)/export-docx"; mkdir -p "$DL/assets"
BASE=https://docs.xadm.biz/toolchain/raw/scripts/export-docx
for f in export_docx.py expand_snippets.py admonitions.py render_mermaid.py make_reference.py \
         frontmatter.lua xadm-reference.docx; do
  curl -fsSL "$BASE/$f" -o "$DL/$f"
done
curl -fsSL "$BASE/assets/logo-xadm.png" -o "$DL/assets/logo-xadm.png"

python3 "$DL/export_docx.py" docs/pre-projeto/index.md
#  ou o livro:  python3 "$DL/export_docx.py" docs/projeto/index.md
#  Sem nome de saída → <slug>-<nível>[-v<versão>].docx na raiz (ex.: meu-app-projeto-v0.1.0.docx).

Nome de entrega rastreável + .gitignore

Sem 2º argumento, o nome sai auto-descritivo — <slug>-<nível>[-v<versão>].docx (slug = diretório-raiz; nível = pre-projeto/projeto; versão = git describe→VERSION) — para a entrega não colidir entre apps/releases. O .docx é gerado (§1.3, não commitado): o .gitignore do app deve ter /*.docx (root-anchored — não pega um pré-projeto .docx commitado em docs/pre-projeto/).

Por dentro, o export_docx.py (Python cross-platform, só stdlib) faz, nesta ordem:

Expande --8<-- (snippets) — o pandoc não conhece pymdownx.snippets, então o livro, que embute projeto/modelagem.md via --8<--, sairia sem o modelo. A expansão vem antes do Mermaid porque um embed pode trazer diagrama. O embed é injetado verbatim (não rebaixa headings — igual ao site): autore o fragmento no nível do embed (modelagem.md começa em ###, pois entra sob um ## — constituição §5).
Converte admonitions — !!! tipo "Título" / ??? tipo (que o pandoc não entende e despejaria literal) viram um callout (blockquote → estilo Block Text do reference), com o tipo como rótulo pt-BR no título (Nota/Aviso/Dica/…). O autor mantém o !!! na fonte (box nativo no site); só o .docx é adaptado.
Mermaid → PNG — cada bloco ```mermaid vira imagem (mmdc local). Legenda opcional por diagrama: %% caption: <texto> na 1ª linha do bloco (comentário que o mermaid ignora) vira a legenda da figura no .docx.
pandoc — --reference-doc=xadm-reference.docx (estilo X-Adm) --toc (sumário) e o filtro frontmatter.lua (quebra de página após o sumário e antes de cada #).

O .docx é o index + só os embeds — nada de auto-anexo

O pipeline não anexa os .md irmãos do index. Página que o livro só linka NÃO entra no .docx (o link já é a relação — igual ao site). O que precisa aparecer no Word se embute via --8<--: fragmentos de fonte única (modelagem.md, mapeamento.md) e, num pré-projeto, os anexos ao fim do index.md (cada # ganha quebra de página). Não transforme uma página linkada em anexo — embuta-a ou aceite que fica fora do Word.

Links para fora do .docx viram texto — cite por nome/número

Um link relativo para uma página que não está no .docx (ex. um ADR em ../decisoes/0008.md, o manual) seria um hyperlink morto no Word. O pipeline remove o href desses links, mantendo o texto — URL absoluta (https://…) e âncora interna (#secao) continuam clicáveis. Então, ao referenciar conteúdo só-no-site no texto destinado ao Word, cite por nome/número ("a decisão 0008 — BYTEA"), não por "[clique aqui]" — senão sobra só "clique aqui" sem o link.

Mermaid e confidencialidade¶

O default é offline (mmdc). Sem mmdc, o pipeline falha — não envia nada à rede por conta própria. Existe um opt-in MERMAID_RENDERER=ink que renderiza via mermaid.ink, um serviço externo que recebe o texto do diagrama: não use com pré-projeto nem conteúdo confidencial (constituição §1.9; veto a fonte ZIM/dados sensíveis saírem da empresa).

Limitação conhecida (1ª onda)¶

O .docx do livro traz a prosa autorada + os embeds --8<-- + os diagramas. O conteúdo injetado por hook do MkDocs no site (o changelog via , as listas de etapas via , o cabeçalho de frontmatter) não entra no Word — o site continua sendo a versão viva e completa. O Word é um retrato para a diretoria.

Regenerar o reference de estilo¶

O visual vem do xadm-reference.docx — um asset de tooling versionado (§1.3), não um documento gerado. Para regerá-lo a partir de um modelo .docx client-neutral (sem nome/arquivo de cliente em cabeçalho/rodapé):

python3 "$DL/make_reference.py" MODELO-NEUTRO.docx xadm-reference.docx

O modelo é obrigatório e não pode ser um documento de cliente. Em geral não é preciso regerar — o reference versionado já é a fonte canônica; ajustes finos podem ser feitos abrindo o .docx, editando os estilos e salvando por cima.

Exportar para .docx (padrão X-Adm)¶