TinyCAD-handleiding
tinycad.net

Bijdragen aan de TinyCAD-handleiding

Deze handleiding wordt gepubliceerd met GitHub Pages. Als u een fout, ontbrekende stap, onduidelijke schermafbeelding of verouderde informatie aantreft, kunt u een wijziging voorstellen met een Pull Request (PR).

Deze gids beschrijft twee werkwijzen:

  • Snel bewerken in uw browser (geschikt voor kleine tekstcorrecties)
  • Lokaal bewerken en vooraf bekijken (geschikt voor grotere wijzigingen)

Voordat u begint

U hebt nodig:

  • Een GitHub-account
  • Voor lokaal bewerken: Git, Node.js, Ruby en Bundler

Gegevens van de repository:

  • Bronrepository: https://github.com/matt123p/TinyCAD-docs
  • Gepubliceerde site: GitHub Pages-uitvoer van deze repository
  • Bronmap van de documentatie: docs/
  • v4-pagina’s: docs/v4/

Optie A: Snel bewerken in GitHub (zonder lokale installatie)

Gebruik deze methode voor typefouten, korte verduidelijkingen of bijgewerkte links.

1) Open de paginabron op GitHub

  1. Ga naar de TinyCAD-documentatierepository: https://github.com/matt123p/TinyCAD-docs
  2. Blader naar de pagina die u wilt bewerken in docs/v4/.
  3. Open het Markdown-bestand (bijvoorbeeld Rulers.md).

2) Begin met bewerken

  1. Klik op het potloodpictogram (Dit bestand bewerken).
  2. Als daarom wordt gevraagd, helpt GitHub u automatisch een fork aan te maken.
  3. Breng uw wijzigingen aan in Markdown.

3) Leg uw wijziging vast

  1. Scrol naar Wijzigingen vastleggen.
  2. Gebruik een duidelijke commitmelding, bijvoorbeeld: docs(v4): clarify ruler units in Rulers
  3. Kies Een nieuwe branch maken voor deze commit.
  4. Klik op Wijzigingen voorstellen.

4) Open een Pull Request

  1. Klik op Vergelijken en pull request maken.
  2. Stel de basisrepository in op matt123p/TinyCAD-docs en de basisbranch op main.
  3. Vul de PR-titel en -beschrijving in (sjabloon hieronder).
  4. Dien de PR in.

Gebruik deze methode als u meerdere bestanden moet bewerken, links wilt controleren of de opmaak vooraf wilt bekijken.

1) Forken en klonen

  1. Fork matt123p/TinyCAD-docs op GitHub.
  2. Kloon uw fork:
git clone https://github.com/<your-username>/TinyCAD-docs.git
cd TinyCAD-docs
  1. Voeg de upstream-afstandsbediening toe:
git remote add upstream https://github.com/matt123p/TinyCAD-docs.git

2) Afhankelijkheden installeren

Deze repository bevat npm-scripts die Bundler + Jekyll voor u uitvoeren:

npm install
npm run bundle:install

3) Maak een branch voor uw wijziging

git checkout -b docs/v4-fix-rulers

Ideeën voor branchnamen:

  • docs/fix-typo-...
  • docs/v4-update-...
  • docs/add-...

4) Breng uw wijzigingen aan

De meeste pagina’s voor gebruikers staan onder:

  • docs/v4/*.md (v4-handleidingpagina’s)
  • docs/v3/*.md (v3-handleidingpagina’s)
  • docs/_data/navigation.yml (linkernavigatie)

Als u een nieuwe pagina toevoegt, werk dan ook de navigatie bij zodat gebruikers deze kunnen vinden.

5) Bekijk de site lokaal

npm run serve

Open vervolgens de lokale URL die in de terminal wordt weergegeven (doorgaans http://127.0.0.1:4000).

Controleer:

  • Of de kopstructuur goed leesbaar is
  • Of interne links werken
  • Of de navigatie uw nieuwe of hernoemde pagina bevat
  • Of afbeeldingen correct worden geladen

6) Committen en pushen

git add .
git commit -m "docs(v4): improve Rulers instructions"
git push -u origin docs/v4-fix-rulers

7) Maak de PR aan

  1. Open uw fork op GitHub.
  2. Klik voor uw branch op Vergelijken en pull request maken.
  3. Richt deze op matt123p/TinyCAD-docs:main.
  4. Vul de PR-titel en -beschrijving in en dien de PR in.

Checklist voor tekstkwaliteit

Controleer het volgende voordat u een PR opent:

  • De reikwijdte is afgebakend (één onderwerp/probleem per PR)
  • Instructies zijn correct voor het huidige gedrag van TinyCAD
  • De taal is duidelijk en beknopt
  • Links verwijzen naar geldige doelen
  • De pagina is indien nodig opgenomen in de navigatie
  • Bestaande stijl en terminologie zijn behouden

Herbruikbare tabsets voor browser/desktop

Als een pagina verschillende instructies nodig heeft voor TinyCAD in de browser en de desktopapp, gebruik dan de gedeelde tabsetcomponent in plaats van eigen pagin specifieke opmaak te bedenken.

<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>

Opmerkingen:

  • data-tabset is de synchronisatie-/opslagsleutel. Gebruik dezelfde waarde opnieuw om meerdere tabsets op dezelfde pagina gesynchroniseerd te houden.
  • data-default-tab stelt het tabblad in dat bij het eerste bezoek wordt geselecteerd.
  • Houd de koppen van de tabbladen op hetzelfde niveau (### in het voorbeeld hierboven).

Voorgesteld PR-sjabloon

Kopieer/plak dit in uw PR-beschrijving:

## Summary
-

## What changed
-

## Why
-

## Validation
- [ ] Previewed locally with `npm run serve`
- [ ] Checked navigation and links
- [ ] Confirmed formatting on rendered page

## Screenshots (if relevant)
-

Uw fork up-to-date houden

Als uw PR een tijdje openstaat, synchroniseer dan uw branch met de nieuwste 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

Veelvoorkomende problemen en oplossingen

  • PR toont niet-gerelateerde bestandswijzigingen
    • Maak een nieuwe branch vanaf de bijgewerkte main en cherry-pick alleen uw commit(s).
  • Navigatie-item ontbreekt
    • Werk docs/_data/navigation.yml bij en controleer of de URL overeenkomt met het permalinkpad van de pagina.
  • Pagina wordt vreemd weergegeven
    • Controleer kopniveaus, inspringing van lijsten en markeringen voor ingesloten codeblokken.
  • Link werkt lokaal maar niet op Pages
    • Gebruik bij voorkeur relatieve links zoals elders in deze repository en houd paginanamen consistent.

Na indiening

Onderhouders kunnen om wijzigingen vragen. Voeg vervolgcommits toe aan dezelfde branch/PR; de PR wordt automatisch bijgewerkt. Zodra deze is goedgekeurd en samengevoegd, verschijnen uw wijzigingen in de gepubliceerde handleiding nadat GitHub Pages opnieuw is opgebouwd.

Bedankt voor het verbeteren van de TinyCAD-documentatie.