GitBook es una plataforma popular para crear sitios de documentación, guías API y bases de conocimiento utilizando Markdown. Si sus borradores de documentación viven en Word, convertirlos a GitBook-compatible Markdown es un proceso sencillo. Esta guía abarca la totalidad de Palabra para GitBook flujo de trabajo.
¿Por qué GitBook para la documentación?
GitBook convierte los archivos Markdown en un sitio de documentación pulido y de búsqueda con:
- Un tema predeterminado limpio y profesional
- Búsqueda de texto completo
- Barra lateral de navegación generada a partir de su estructura de archivos
- GitHub sincronización para documentos controlados por versiones
- Dominios personalizados
El contenido escrito en Word se corresponde bien con el modelo de página de GitBook una vez convertido a Markdown.
Conversión de documentos Word
Comienza con WordToMD:
- Arrastre su proyecto de documentación .docx en el convertidor
- Revise la salida Markdown compruebe encabezados, tablas y secciones de código
- Descarga el archivo .md
La salida es Markdown estándar que GitBook acepta directamente.
GitBook Estructura del archivo
GitBook organiza el contenido alrededor de un SUMMARY.md archivo que define la estructura de navegación:
# 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 en SUMARY.md se convierte en una página en su barra lateral GitBook. Después de convertir sus documentos Word, organizarlos en esta estructura.
El tema principal en GitBook
GitBook (versiones heredadas) no utiliza YAML los títulos de las páginas provienen del primer encabezado H1. La versión más reciente de GitBook (GitBook.com) acepta algo de material frontal, pero el enfoque seguro es usar el primero. # Heading como el título de la página:
# Authentication Guide
This section describes how to authenticate with the API.
## Overview
...Estructura de las direcciones
GitBook genera una tabla de contenido a nivel de página a partir de los encabezados H2 y H3. Mantenga su jerarquía limpia:
- H1 Título de la página (uno por archivo)
- H2 Secciones principales (aparece en la página TOC)
- H3 Subsecciones
No se puede hacer. Markdown Guía de encabezados para el encabezamiento de las mejores prácticas.
Tablas en GitBook
GitBook muestra las tablas GFM con el estilo. Las tablas de su documento Word se convierten correctamente a través de WordToMD:
| Endpoint | Method | Description |
|---|---|---|
| `/auth/login` | POST | Authenticate user |
| `/auth/logout` | POST | End session |
| `/users/{id}` | GET | Get user profile |Para escenarios de tabla complejos, véase Markdown Tablas: una guía completa.
Bloques de código
GitBook Rende bloques de código cercados con resaltado de sintaxis. Después de la conversión con WordToMD, formato de las muestras de código correctamente:
```bash
npm install -g gitbook-cli
gitbook init my-docs
```GitBook también tiene un tipo de bloque especial Hint para llamadas:
{% hint style="info" %}
This is an information callout.
{% endhint %}
{% hint style="warning" %}
This is a warning callout.
{% endhint %}Si su documento de Word ha resaltado los cuadros de llamadas, conviértelos en bloques de sugerencias de GitBook después de la conversión inicial de Markdown.
GitHub Flujo de trabajo de sincronización
GitBook soporta la sincronización con un repositorio GitHub:
- Crear un GitHub repositorio y agregar sus archivos .md convertidos
- Conectar GitBook al repositorio en las configuraciones de GitBooks
- GitBook crea y publica automáticamente desde los archivos Markdown
- Las ediciones en GitBook se sincronizan de nuevo con GitHub, y viceversa
Esto le da control de versiones para sus documentos y permite a su equipo colaborar a través de GitHub PRs o directamente en el editor de GitBook.
Para las especificaciones GitHub Markdown, véase Se trata de una serie de medidas que se aplican a todos los Estados miembros, incluidos los Estados miembros de la Unión Europea..
Imágenes
Exportar imágenes de sus documentos Word (Guardar como → Página Web guarda imágenes en una carpeta). En GitBook con GitHub sincronizar, comprometer las imágenes a un assets/ or images/ directorio y hacer referencia a ellos:
En el editor web de GitBook, puede cargar imágenes directamente al editar páginas.
Migración de un conjunto completo de documentación
Para una migración de documentación de gran tamaño desde Word a GitBook:
- Auditar los documentos Word identificar las páginas, las secciones y la jerarquía
- Planificar la estructura SUMARY.md antes de la conversión
- Convertir archivos with WordToMD (o el Conversión por lotes para grandes volúmenes)
- Creación de SUMMARY.md que coincida con su estructura planificada
- Revisar cada página para la jerarquía de encabezados, el formato de tablas y los bloques de código
- Publicación A través de GitBooks importación o GitHub sincronización
FAQ
¿Qué sabor Markdown usa GitBook? GitBook utiliza el estándar Markdown (CommonMark) más sus propias extensiones (bloques de indicación, pestañas, bloques de incorporación). La salida Markdown de WordToMD es compatible.
¿Puedo importar un .docx directamente en GitBook? La función de importación GitBook.com acepta documentos Word, pero la salida a menudo es de menor calidad que pasar por Markdown. El enfoque de dos pasos (Word → Markdown → GitBook) da mejores resultados para documentos complejos.
¿Cómo manejo los enlaces entre documentos?
En GitBook con GitHub sincronización, utilizar enlaces relativos Markdown: [See Authentication](../api/authentication.md). GitBook resolves these to proper page links.
Mi documentación tiene más de 50 Word archivos. ¿Hay un flujo de trabajo más rápido? No se puede hacer. Conversión por lotes de Word a Markdown para automatizar el paso de conversión, luego escriba un script para generar SUMMARY.md desde la estructura del archivo.
Conclusión
Conversión Se trata de una serie de medidas que se aplican a todos los Estados miembros, incluidos los Estados miembros de la Unión Europea. es un flujo de trabajo limpio: WordToMD se encarga de la conversión del documento, y GitBooks GitHub sincronización o importación directa se encarga de la publicación. Utilice estilos de encabezado estándar en Word, mantenga sus tablas simples, y tendrá un sitio de documentación profesional funcionando rápidamente.