GitBook é uma plataforma popular para criar sites de documentação, API guias e bases de conhecimento usando Markdown. Se os seus rascunhos de documentação vivem em Word, convertê-los para GitBook-compatível Markdown é um processo simples. Este guia abrange a totalidade Word para GitBook fluxo de trabalho.
Por que GitBook para Documentação?
GitBook transforma os arquivos Markdown em um site de documentação refinado e pesquisável com:
- Um tema padrão limpo e profissional
- Pesquisa em texto completo
- Barra lateral de navegação gerada a partir da sua estrutura de arquivo
- GitHub sincronização para documentos controlados por versão
- Domínios personalizados
O conteúdo escrito em Word mapeia bem o modelo de página de GitBooks uma vez convertido para Markdown.
Conversão de Word documentos
Começa com WordToMD:
- Arraste seu rascunho de documentação .docx para o conversor
- Rever a saída Markdown verificar cabeçalhos, tabelas e secções de código
- Baixar o arquivo .md
A saída é padrão Markdown que GitBook aceita diretamente.
GitBook Estrutura do ficheiro
GitBook organiza o conteúdo em torno de um SUMMARY.md Arquivo que define a estrutura de navegação:
# Table of Contents
* [Introduction](README.md)
* [Getting Started](getting-started/README.md)
* [Installation](getting-started/installation.md)
* [Configuration](getting-started/configuration.md)
* [API Reference](api/README.md)
* [Authentication](api/authentication.md)Cada bala em SUMARY.md torna-se uma página na sua barra lateral GitBook. Depois de converter seus documentos Word, organize-os nesta estrutura.
A primeira página em GitBook
GitBook (versões antigas) não usa YAML os títulos das páginas vêm do primeiro cabeçalho H1. A versão mais recente do GitBook (GitBook.com) aceita alguma matéria frontal, mas a abordagem segura é usar a primeira. # Heading como o título da página:
# Authentication Guide
This section describes how to authenticate with the API.
## Overview
...Estrutura da rubrica
GitBook gera uma tabela de conteúdos a nível de página a partir de cabeçalhos H2 e H3. Mantém a tua hierarquia limpa:
- H1 Título da página (um por ficheiro)
- H2 Secções principais (aparecem na página TOC)
- H3 Subsecções
A seguir: Markdown Guia de cabeçalhos para a rubrica das melhores práticas.
Tabelas em GitBook
GitBook renderiza tabelas GFM com estilo. Tabelas do seu documento Word converter corretamente via WordToMD:
| Endpoint | Method | Description |
|---|---|---|
| `/auth/login` | POST | Authenticate user |
| `/auth/logout` | POST | End session |
| `/users/{id}` | GET | Get user profile |Para cenários de tabela complexos, ver Markdown Tabelas: um guia completo.
Blocos de código
GitBook Renda blocos de código cercados com destaque de sintaxe. Após a conversão com WordToMD, formatar as amostras de código corretamente:
```bash
npm install -g gitbook-cli
gitbook init my-docs
```GitBook também possui um tipo de bloco especial Hint para chamadas:
{% hint style="info" %}
This is an information callout.
{% endhint %}
{% hint style="warning" %}
This is a warning callout.
{% endhint %}Se o seu documento Word tem marcadas caixas de indicação, converta-as para blocos de sugestões do GitBook após a conversão inicial Markdown.
GitHub Fluxo de trabalho de sincronização
GitBook suporta sincronização com um repositório GitHub:
- Crie um repo GitHub e adicione seus arquivos .md convertidos
- Conectar GitBook ao repo nas configurações GitBooks
- GitBook constrói e publica automaticamente a partir dos arquivos Markdown
- Edições em GitBook sincronizam de volta para GitHub, e vice-versa
Isto dá-lhe controle de versão para os seus documentos e permite que a sua equipa colabore através do GitHub PRs ou diretamente no editor do GitBook.
Para especificações GitHub Markdown, ver Word para GitHub Markdown.
Imagens
Exportar imagens de seus documentos Word (Salvar como → Página Web salva imagens em uma pasta). Em GitBook com GitHub sincronização, cometer as imagens para um assets/ or images/ Diretório e referências:
No editor da web GitBook, você pode carregar imagens diretamente ao editar páginas.
Migração de um conjunto completo de documentação
Para uma migração de grande documentação de Word para GitBook:
- Auditar os documentos Word identificar páginas, secções e hierarquia
- Planejar a estrutura SUMARY.md antes da conversão
- Converter arquivos with WordToMD (ou conversão por lotes para grandes volumes)
- Criar SUMARY.md que corresponda à sua estrutura planeada
- Rever cada página para a hierarquia de cabeçalhos, a formatação de tabelas e os blocos de código
- Publicação através de GitBooks importar ou GitHub sincronizar
FAQ
Que sabor Markdown usa GitBook? GitBook usa o padrão Markdown (CommonMark) mais suas próprias extensões (blocos de sugestão, guias, blocos de inserção). A saída Markdown de WordToMD é compatível.
Posso importar um .docx diretamente para GitBook? O recurso de importação GitBook.coms aceita documentos Word, mas a saída é muitas vezes de menor qualidade do que passar por Markdown. A abordagem de duas etapas (Word → Markdown → GitBook) dá melhores resultados para documentos complexos.
Como faço para lidar com ligações entre documentos?
Em GitBook com GitHub sincronização, use links relativos Markdown: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.
Minha documentação tem mais de 50 arquivos Word. Existe um fluxo de trabalho mais rápido? A seguir: Batch Convert Word para Markdown para automatizar a etapa de conversão, em seguida, escreva um script para gerar SUMMARY.md a partir da estrutura de arquivo.
Conclusão
Conversão Word para GitBook Markdown é um fluxo de trabalho limpo: WordToMD lida com a conversão do documento, e GitBooks GitHub sincronização ou importação direta lida com a publicação. Use estilos de cabeçalho padrão no Word, mantenha suas tabelas simples, e você terá um site de documentação profissional funcionando rapidamente.