Contribuir al manual de TinyCAD
Este manual se publica con GitHub Pages. Si encuentra un error, falta algún paso, una captura de pantalla no es clara o la información está desactualizada, puede proponer una corrección mediante una solicitud de incorporación de cambios (Pull Request, PR).
Esta guía explica dos flujos de trabajo:
- Ediciones rápidas en el navegador (ideal para corregir textos breves)
- Edición y vista previa local (ideal para cambios más amplios)
Antes de empezar
Necesitará:
- Una cuenta de GitHub
- Para editar localmente: Git, Node.js, Ruby y Bundler
Detalles del repositorio:
- Repositorio de origen:
https://github.com/matt123p/TinyCAD-docs - Sitio publicado: salida de GitHub Pages de este repositorio
- Carpeta de origen de la documentación:
docs/ - Páginas de v4:
docs/v4/
Opción A: Edición rápida en GitHub (sin configuración local)
Use este método para corregir errores tipográficos, aclarar algo brevemente o actualizar enlaces.
1) Abra en GitHub el código fuente de la página
- Vaya al repositorio de documentación de TinyCAD:
https://github.com/matt123p/TinyCAD-docs - Busque la página que desea editar en
docs/v4/. - Abra el archivo Markdown (por ejemplo,
Rulers.md).
2) Empiece a editar
- Haga clic en el icono del lápiz (Edit this file).
- Si se le solicita, GitHub le ayudará a crear automáticamente una bifurcación (fork).
- Realice los cambios en Markdown.
3) Confirme el cambio
- Desplácese hasta Commit changes.
- Use un mensaje de confirmación claro, por ejemplo:
docs(v4): clarify ruler units in Rulers - Elija Create a new branch for this commit.
- Haga clic en Propose changes.
4) Abra una solicitud de incorporación de cambios
- Haga clic en Compare & pull request.
- Establezca el repositorio base en
matt123p/TinyCAD-docsy la rama base enmain. - Complete el título y la descripción de la PR (consulte la plantilla a continuación).
- Envíe la PR.
Opción B: Edición local + vista previa (recomendada para cambios más amplios)
Use este método cuando necesite editar varios archivos, comprobar enlaces o previsualizar el formato.
1) Bifurque y clone
- Bifurque
matt123p/TinyCAD-docsen GitHub. - Clone su bifurcación:
git clone https://github.com/<your-username>/TinyCAD-docs.git
cd TinyCAD-docs
- Añada el repositorio remoto original:
git remote add upstream https://github.com/matt123p/TinyCAD-docs.git
2) Instale las dependencias
Este repositorio incluye scripts de npm que ejecutan Bundler + Jekyll por usted:
npm install
npm run bundle:install
3) Cree una rama para el cambio
git checkout -b docs/v4-fix-rulers
Ideas para nombrar la rama:
docs/fix-typo-...docs/v4-update-...docs/add-...
4) Realice las ediciones
La mayoría de las páginas visibles para los usuarios están en:
docs/v4/*.md(páginas del manual de v4)docs/v3/*.md(páginas del manual de v3)docs/_data/navigation.yml(navegación lateral)
Si añade una página nueva, actualice también la navegación para que los usuarios puedan encontrarla.
5) Previsualice el sitio localmente
npm run serve
A continuación, abra la URL local que aparece en el terminal (normalmente, http://127.0.0.1:4000).
Compruebe que:
- La estructura de los encabezados sea legible
- Los enlaces internos funcionen
- La navegación incluya la página nueva o renombrada
- Las imágenes se carguen correctamente
6) Confirme y envíe los cambios
git add .
git commit -m "docs(v4): improve Rulers instructions"
git push -u origin docs/v4-fix-rulers
7) Cree la PR
- Abra su bifurcación en GitHub.
- Haga clic en Compare & pull request para su rama.
- Seleccione como destino
matt123p/TinyCAD-docs:main. - Complete el título y la descripción de la PR y envíela.
Lista de comprobación de calidad de redacción
Antes de abrir una PR, compruebe rápidamente que:
- El alcance esté bien definido (un tema o problema por PR)
- Las instrucciones sean precisas y correspondan al comportamiento actual de TinyCAD
- El lenguaje sea claro y conciso
- Los destinos de los enlaces sean válidos
- La página esté enlazada desde la navegación cuando sea necesario
- Se mantengan el estilo y la terminología existentes
Conjuntos de pestañas reutilizables para navegador y escritorio
Cuando una página requiera instrucciones distintas para TinyCAD en el navegador y en la aplicación de escritorio, use el componente compartido de conjunto de pestañas en vez de crear marcado específico para esa página.
<div class="manual-tabset" data-tabset="product-mode" data-tabset-label="Choose your TinyCAD product" data-default-tab="Browser" markdown="1">
### Browser
Browser-specific content.
### Desktop App
Desktop-specific content.
</div>
Notas:
data-tabsetes la clave de sincronización/almacenamiento. Reutilice el mismo valor para mantener sincronizados varios conjuntos de pestañas de una misma página.data-default-tabestablece la pestaña seleccionada en la primera visita.- Mantenga todos los encabezados de pestaña en el mismo nivel (
###en el ejemplo anterior).
Plantilla sugerida para la PR
Copie y pegue esto en la descripción de su PR:
## Summary
-
## What changed
-
## Why
-
## Validation
- [ ] Previewed locally with `npm run serve`
- [ ] Checked navigation and links
- [ ] Confirmed formatting on rendered page
## Screenshots (if relevant)
-
Mantenga su bifurcación actualizada
Si su PR permanece abierta durante un tiempo, sincronice su rama con la versión más reciente de main:
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
git checkout docs/v4-fix-rulers
git merge main
git push
Problemas habituales y soluciones
- La PR muestra cambios en archivos que no están relacionados
- Cree una rama nueva a partir de
mainactualizado y aplique con cherry-pick únicamente sus confirmaciones.
- Cree una rama nueva a partir de
- Falta un elemento de navegación
- Actualice
docs/_data/navigation.ymly asegúrese de que la URL coincida con la ruta del enlace permanente de la página.
- Actualice
- La página se muestra de forma extraña
- Compruebe los niveles de los encabezados, la sangría de las listas y los marcadores de bloques de código cercados.
- El enlace funciona localmente, pero no en Pages
- Prefiera los enlaces relativos usados en otras partes de este repositorio y mantenga coherentes los nombres de las páginas.
Después del envío
Es posible que los responsables del mantenimiento soliciten cambios. Añada confirmaciones de seguimiento a la misma rama/PR; la PR se actualizará automáticamente. Una vez aprobados y fusionados, sus cambios aparecerán en el manual publicado cuando GitHub Pages vuelva a generarlo.
Gracias por mejorar la documentación de TinyCAD.
- Volver al contenido de v4