Technical Writing & Documentation - Guía de Entorno¶

Guía completa para creación de documentación técnica con Claude Code.

Capacidades de Claude Code¶

Capacidad	Herramientas
Markdown	CommonMark, GFM, MDX
Static Sites	MkDocs, Docusaurus, Hugo
API Docs	OpenAPI, Swagger, Redoc
Diagramas	Mermaid, PlantUML, D2
PDF/LaTeX	LaTeX, Pandoc, Typst
Notebooks	Jupyter, Quarto

Markdown Ecosystem¶

Linters & Formatters¶

# markdownlint
npm install -g markdownlint-cli
markdownlint "**/*.md"
markdownlint --fix "**/*.md"

# prettier (también formatea MD)
npm install -g prettier
prettier --write "**/*.md"

# VS Code
code --install-extension DavidAnson.vscode-markdownlint
code --install-extension yzhang.markdown-all-in-one

MDX (Markdown + JSX)¶

# Para Docusaurus, Next.js docs
npm install @mdx-js/mdx @mdx-js/react

Documentation Generators¶

MkDocs (Este wiki)¶

# Instalar
pip install mkdocs mkdocs-material

# Crear proyecto
mkdocs new my-docs

# Estructura
my-docs/
├── docs/
│   ├── index.md
│   └── guide.md
├── mkdocs.yml
└── requirements.txt

# Comandos
mkdocs serve              # Desarrollo
mkdocs build              # Build
mkdocs gh-deploy          # Deploy a GitHub Pages

mkdocs.yml básico:

site_name: My Documentation
theme:
  name: material
  features:
    - navigation.tabs
    - search.highlight
    - content.code.copy

plugins:
  - search

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - toc:
      permalink: true

Docusaurus (React-based)¶

# Crear proyecto
npx create-docusaurus@latest my-docs classic

# Estructura
my-docs/
├── docs/
├── blog/
├── src/
├── static/
├── docusaurus.config.js
└── sidebars.js

# Comandos
npm run start      # Desarrollo
npm run build      # Build
npm run serve      # Preview build
npm run deploy     # Deploy

Hugo¶

# Instalar
brew install hugo  # macOS
winget install Hugo.Hugo.Extended  # Windows

# Crear sitio
hugo new site my-docs

# Añadir tema
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

# Comandos
hugo server -D     # Desarrollo con drafts
hugo               # Build

Sphinx (Python docs)¶

pip install sphinx sphinx-rtd-theme

# Crear proyecto
sphinx-quickstart docs

# Comandos
make html          # Build HTML
make latexpdf      # Build PDF

VitePress (Vue-based)¶

# Crear proyecto
npm add -D vitepress

# Estructura
docs/
├── .vitepress/
│   └── config.ts
├── index.md
└── guide/
    └── getting-started.md

# Comandos
npx vitepress dev docs
npx vitepress build docs
npx vitepress preview docs

API Documentation¶

OpenAPI / Swagger¶

# Swagger UI
docker run -p 8080:8080 -e SWAGGER_JSON=/app/openapi.yaml -v $(pwd):/app swaggerapi/swagger-ui

# Swagger Editor
docker run -p 8081:8080 swaggerapi/swagger-editor

# Validación
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

# Generación de código
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

Redoc¶

# CLI
npm install -g @redocly/cli

# Preview
redocly preview-docs openapi.yaml

# Build estático
redocly build-docs openapi.yaml -o docs/api.html

Stoplight¶

# Elements (componente web)
npm install @stoplight/elements

# Prism (mock server)
npm install -g @stoplight/prism-cli
prism mock openapi.yaml

Diagramas como Código¶

Mermaid¶

# CLI
npm install -g @mermaid-js/mermaid-cli

# Generar imagen
mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.png

# VS Code
code --install-extension bierner.markdown-mermaid

Ejemplos:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

sequenceDiagram
    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Data
    Server-->>Client: Response

PlantUML¶

# Java requerido
# Descargar plantuml.jar
java -jar plantuml.jar diagram.puml

# VS Code
code --install-extension jebbs.plantuml

D2 (Moderno)¶

# Instalar
brew install d2  # macOS
# https://d2lang.com/tour/install

# Generar
d2 diagram.d2 output.svg
d2 --watch diagram.d2 output.svg  # Live reload

Excalidraw¶

# VS Code extension
code --install-extension pomdtr.excalidraw-editor

# React component
npm install @excalidraw/excalidraw

LaTeX & PDF¶

LaTeX¶

# TeX Live (completo)
# Windows
winget install TeXLive

# macOS
brew install --cask mactex

# Linux
sudo apt install texlive-full

# Compilar
pdflatex document.tex
xelatex document.tex   # Unicode support
lualatex document.tex  # Modern

Typst (Moderno, reemplaza LaTeX)¶

# Instalar
brew install typst  # macOS
winget install typst.typst  # Windows

# Compilar
typst compile document.typ
typst watch document.typ  # Live reload

# VS Code
code --install-extension nvarner.typst-lsp

Pandoc (Conversor universal)¶

# Instalar
brew install pandoc  # macOS
winget install JohnMacFarlane.Pandoc  # Windows

# Conversiones
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o output.html
pandoc input.docx -o output.md

# Con template
pandoc input.md --template=template.tex -o output.pdf

# Slides
pandoc slides.md -t revealjs -o slides.html
pandoc slides.md -t beamer -o slides.pdf

Jupyter & Notebooks¶

JupyterLab¶

pip install jupyterlab

jupyter lab

Quarto (Notebooks científicos)¶

# Instalar
# https://quarto.org/docs/get-started/

# Render
quarto render document.qmd
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

# Preview
quarto preview document.qmd

# Proyecto
quarto create project book my-book
quarto create project website my-website

Spell Check & Grammar¶

Vale (Prose linting)¶

# Instalar
brew install vale  # macOS
winget install jdkato.vale  # Windows

# Configurar .vale.ini
StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale, Google

# Ejecutar
vale sync  # Descargar estilos
vale docs/

LanguageTool¶

# Docker
docker run -d -p 8010:8010 silviof/docker-languagetool

# VS Code
code --install-extension davidlday.languagetool-linter

cspell (Code spell checker)¶

npm install -g cspell

cspell "**/*.md"
cspell --config cspell.json "docs/**/*"

Comandos que Claude Code Ejecutará¶

# MkDocs
mkdocs serve
mkdocs build
mkdocs gh-deploy

# Docusaurus
npm run start
npm run build

# Hugo
hugo server -D
hugo

# API Docs
spectral lint openapi.yaml
redocly build-docs openapi.yaml

# Diagramas
mmdc -i diagram.mmd -o diagram.svg
d2 diagram.d2 output.svg

# PDF/LaTeX
pandoc input.md -o output.pdf
typst compile document.typ

# Quarto
quarto render document.qmd
quarto preview

# Linting
vale docs/
markdownlint "**/*.md"
cspell "**/*.md"

VS Code Extensions¶

# Markdown
code --install-extension yzhang.markdown-all-in-one
code --install-extension DavidAnson.vscode-markdownlint
code --install-extension bierner.markdown-mermaid

# Diagramas
code --install-extension bierner.markdown-mermaid
code --install-extension jebbs.plantuml
code --install-extension pomdtr.excalidraw-editor

# LaTeX
code --install-extension James-Yu.latex-workshop
code --install-extension nvarner.typst-lsp

# Spell check
code --install-extension streetsidesoftware.code-spell-checker
code --install-extension streetsidesoftware.code-spell-checker-spanish
code --install-extension valentjn.vscode-ltex

# Preview
code --install-extension shd101wyy.markdown-preview-enhanced

Verificación del Entorno¶

#!/bin/bash
echo "=== Verificación Entorno Docs ==="

echo -e "\n--- Static Site Generators ---"
mkdocs --version 2>/dev/null || echo "MkDocs no instalado"
hugo version 2>/dev/null || echo "Hugo no instalado"

echo -e "\n--- Diagramas ---"
mmdc --version 2>/dev/null || echo "Mermaid CLI no instalado"
d2 --version 2>/dev/null || echo "D2 no instalado"

echo -e "\n--- PDF/LaTeX ---"
pandoc --version 2>/dev/null | head -1 || echo "Pandoc no instalado"
typst --version 2>/dev/null || echo "Typst no instalado"
pdflatex --version 2>/dev/null | head -1 || echo "LaTeX no instalado"

echo -e "\n--- Quarto ---"
quarto --version 2>/dev/null || echo "Quarto no instalado"

echo -e "\n--- Linting ---"
vale --version 2>/dev/null || echo "Vale no instalado"
markdownlint --version 2>/dev/null || echo "markdownlint no instalado"

echo -e "\n=== Verificación Completa ==="

Technical Writing & Documentation - Guía de Entorno¶

Capacidades de Claude Code¶

Markdown Ecosystem¶

Linters & Formatters¶

MDX (Markdown + JSX)¶

Documentation Generators¶

MkDocs (Este wiki)¶

Docusaurus (React-based)¶

Hugo¶

Sphinx (Python docs)¶

VitePress (Vue-based)¶

API Documentation¶

OpenAPI / Swagger¶

Redoc¶

Stoplight¶

Diagramas como Código¶

Mermaid¶

PlantUML¶

D2 (Moderno)¶

Excalidraw¶

LaTeX & PDF¶

LaTeX¶

Typst (Moderno, reemplaza LaTeX)¶

Pandoc (Conversor universal)¶

Jupyter & Notebooks¶

JupyterLab¶

Quarto (Notebooks científicos)¶

Spell Check & Grammar¶

Vale (Prose linting)¶

LanguageTool¶

cspell (Code spell checker)¶

Comandos que Claude Code Ejecutará¶

VS Code Extensions¶

Verificación del Entorno¶

Recursos¶