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
- Ga naar de TinyCAD-documentatierepository:
https://github.com/matt123p/TinyCAD-docs - Blader naar de pagina die u wilt bewerken in
docs/v4/. - Open het Markdown-bestand (bijvoorbeeld
Rulers.md).
2) Begin met bewerken
- Klik op het potloodpictogram (Dit bestand bewerken).
- Als daarom wordt gevraagd, helpt GitHub u automatisch een fork aan te maken.
- Breng uw wijzigingen aan in Markdown.
3) Leg uw wijziging vast
- Scrol naar Wijzigingen vastleggen.
- Gebruik een duidelijke commitmelding, bijvoorbeeld:
docs(v4): clarify ruler units in Rulers - Kies Een nieuwe branch maken voor deze commit.
- Klik op Wijzigingen voorstellen.
4) Open een Pull Request
- Klik op Vergelijken en pull request maken.
- Stel de basisrepository in op
matt123p/TinyCAD-docsen de basisbranch opmain. - Vul de PR-titel en -beschrijving in (sjabloon hieronder).
- Dien de PR in.
Optie B: Lokaal bewerken + vooraf bekijken (aanbevolen voor grotere wijzigingen)
Gebruik deze methode als u meerdere bestanden moet bewerken, links wilt controleren of de opmaak vooraf wilt bekijken.
1) Forken en klonen
- Fork
matt123p/TinyCAD-docsop GitHub. - Kloon uw fork:
git clone https://github.com/<your-username>/TinyCAD-docs.git
cd TinyCAD-docs
- 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
- Open uw fork op GitHub.
- Klik voor uw branch op Vergelijken en pull request maken.
- Richt deze op
matt123p/TinyCAD-docs:main. - 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-tabsetis de synchronisatie-/opslagsleutel. Gebruik dezelfde waarde opnieuw om meerdere tabsets op dezelfde pagina gesynchroniseerd te houden.data-default-tabstelt 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
mainen cherry-pick alleen uw commit(s).
- Maak een nieuwe branch vanaf de bijgewerkte
- Navigatie-item ontbreekt
- Werk
docs/_data/navigation.ymlbij en controleer of de URL overeenkomt met het permalinkpad van de pagina.
- Werk
- 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.
- Terug naar v4-inhoudsopgave