Typemark Documentation

Typemark CLI

Kreeri või laadi alla projekt, muuda seda oma redaktoris, kontrolli ja avalda terminalist või CI-st.

Uuendatud 19. nov 202610 min lugemist

Käsk typemark võimaldab projektiga töötada oma redaktoris: loo see või laadi alla, muuda faile, kontrolli neid probleemide suhtes ning saada tagasi, et avaldada. Samuti kolib see Mintlify saidi Typemarkile ja avaldab CI-st. See on saadaval igal paketil.

Typemarki kasutamiseks seda pole vaja. Redaktor teeb kõik brauseris.

Installimine

CLI vajab Node.js versiooni 22 või uuemat, macOS-is, Linuxis või Windowsis.

npm install -g @gettypemark/cli
typemark --version

Pakett on @gettypemark/cli. Installitav käsk on typemark. Kui soovid seda ühekordselt käivitada ilma installimata, kasuta npx @gettypemark/cli käsu typemark asemel.

Uuendamine

Kui on välja tulnud uuem versioon, teatab CLI sellest käsu järel ühel real, kuni üks kord päevas. Väljundit --json korral, CI-s ja siis, kui väljund ei ole terminal, ta vaikib. Uuendamiseks:

npm install -g @gettypemark/cli@latest

Kui sinu versioon on Typemarkile liiga vana, peatuvad käsud veaga cli_outdated (väljumiskood 6) ja näitavad sama käsku uuendamiseks.

Sisselogimine

typemark login

Sinu brauser avab Typemarki lehe, kus on kood. Kontrolli, et see ühtib terminalis oleva koodiga, ja klõpsa Approve. Seejärel ütleb terminal, kellena oled sisse logitud.

Sisselogimine kehtib kuus kuud. Pärast seda käivita typemark login uuesti. Kui sinu organisatsioon nõuab üksiku sisselogimise (single sign-on) kasutamist, lakkavad varasemad sisselogimised ja tokenid töötamast: käivita typemark login uuesti ja logi sisse SSO kaudu. Masinas, kus pole brauserit, käivita typemark login --no-browser ja ava selle väljastatud link mis tahes seadmes.

Sisselogimine ilmub jaotisesse Account > API tokens nimega "CLI on", millele järgneb sinu arvuti nimi. Tühista see seal või käivita selles arvutis typemark logout.

Projekti muutmine kohalikult

  1. Laadi projekt alla

    typemark projects          # lists the projects you can open
    typemark pull acme-docs    # downloads acme-docs into ./acme-docs
    cd acme-docs
  2. Muuda ja eelvaata

    typemark dev

    Avab sinu saidi aadressil http://localhost:3333, kui muudad faile mis tahes redaktoris. Vt Eelvaade kohalikult.

  3. Kontrolli

    typemark check

    Leiab probleemid enne, kui lugejad need näevad. Vt Dokumentatsiooni kontrollimine.

  4. Avalda

    typemark push --wait

    Laeb üles kõik, mida muutsid, lisasid või kustutasid, ühe muudatusena sinu nimel, ning avaldab selle nagu salvestuse redaktoris. --wait ootab, kuni uus versioon on avalik.

typemark new guides/setup loob lehe ja lisab selle navigeerimisse. typemark open avab sinu saidi brauseris (typemark open editor avab redaktori). typemark status näitab saidi aadressi, viimast avaldamist ja kohalikke muudatusi. typemark push --dry-run loetleb, mida push saadaks, ilma seda saatmata.

Aadress, mida typemark projects, status ja open näitavad, on saidi enda oma: sinu kohandatud domeen pärast kinnitamist, muidu https://{slug}.typemark.dev.

Push avaldab muudetud lehed kohe, nagu push ühendatud GitHubi repositooriumisse. See kehtib ka käsitsi avaldamise režiimis, seega kasuta --dry-run, et näha, mis on avaldamas.

Projekti loomine

cd my-docs
typemark create "Acme Docs"

Loob projekti nimega Acme Docs ja seob kausta, kus oled, selle külge, nii et typemark push, typemark status ja teised käsud teavad, millist projekti kasutada. See on sama mis armatuurlaual New project: projekt algab failiga typemark.json ja mõne algelehega ning selle sait on võrguühenduseta, kuni avaldad selle. Kehtib paketi projektide limiit. Vt Arveldus.

Seejärel avalda kaust algelehtede asemel:

typemark push --prune

Või alusta algelehtedest: tühjas kaustas käivita typemark pull.

ValikMida teeb
--slug acmeValib projekti aadressi. Ilma selleta tehakse aadress nimest, nagu acme-docs.
--no-linkLoob ainult projekti. Seo kaust sellega hiljem käsuga typemark link acme-docs.
--dir docsSeob teise kausta selle asemel, kus oled

Kaust, mis on juba projektiga seotud, jääb sellega seotuks: typemark create peatub ilma midagi loomata. Kasuta --no-link või typemark link, et kausta teise projekti külge üle viia.

Eelvaade kohalikult

typemark dev

typemark dev näitab sinu kausta aadressil http://localhost:3333 täpselt nii, nagu Typemark selle avaldab: sama paigutus, komponendid, koodi esiletõstmine, navigeerimine, otsing ja brändivärv. Faili salvestamine, lisamine, kustutamine või ümbernimetamine laadib lehe uuesti; muudatused kaustades .git ja node_modules ning failides, mida .gitignore või .typemarkignore ignoreerib, ei tee seda. See töötab võrguühenduseta ega nõua sisselogimist.

  • Leht, mis ei ehitu, näitab vea ja selle rida lehe asemel.
  • Leht, mis ei ole navigeerimises, näitab "Not published", sest lugejad ei pääseks sinna ligi. Peidetud leht avaneb, kuid ei ole külgribal.
  • Terminal loetleb, mitu probleemi typemark check leiab, iga kord kui see arv muutub.

API viitelehed

Typemark genereerib OpenAPI spetsifikatsiooni ülevaate- ja lõpp-punktide lehed. Sisselogituna saadab typemark dev spetsifikatsiooni Typemarkile ja näitab lehti täpselt nii, nagu need avaldatakse. Saadetakse ainult spetsifikatsioon ja ainult siis, kui see muutub. Kui oled välja logitud või võrguühenduseta, näitab viide kohatäitjat, kuni käivitad typemark login.

Spetsifikatsioon, mida ei saa parsida, näitab oma viga viite asemel, olenemata sisselogimisest, ja typemark check teatab sellest koos reaga. Leht, mille oled kirjutanud lõpp-punktile, näitab seda lõpp-punkti samamoodi.

Eelvaates puuduv

Mõned asjad juhtuvad ainult avaldatud saidil: AI otsing (eelvaate otsing vastab lehe tekstile), tagasiside vidin, lehe tegevuste menüü, "Powered by Typemark" ja sinu kohandatud kood ning integratsioonid. Saidil, mis on mitmes keeles, näitab eelvaade vaikekeelt.

ValikMida teeb
--port 4000Serveerib teisel pordil. Ilma selleta kasutatakse esimest vaba porti pärast 3333.
--host 0.0.0.0Muudab eelvaate kättesaadavaks teistest seadmetest sinu võrgus, nagu sinu telefon
--no-openEi ava brauserit

Lehe lisamine

typemark new guides/setup --title "Set up Acme"

Loob faili guides/setup.mdx pealkirjaga, sinu docs_root sees, kui sul on see, ja lisab selle navigeerimisse. Ilma valikuta --group asetatakse leht teiste samas kaustas olevate lehtede kõrvale või esimesse gruppi. --group "Guides" paneb selle sellesse gruppi ja loob grupi, kui seda pole; lisa --tab, et valida vahekaart. --no-nav loob ainult faili.

Kui keegi teine ka muudab

typemark pull jätab meelde, millist versiooni igast failist allalaadimisel sai, kaustas .typemark, mida Git ignoreerib. Push kasutab seda, et saata ainult sinu muudatused.

  • Keegi muutis teisi faile Typemarkil sinu viimasest pullist alates: sinu push läheb läbi ja CLI ütleb, et pead käivitama typemark pull, et saada nende muudatused.
  • Keegi muutis sama faili: midagi ei saadeta. CLI loetleb failid. Käivita typemark pull, et saada nende versioon, ja push uuesti.

Käivita typemark pull allalaaditud kaustas, et see uuendada. See ei kirjuta kunagi üle faili, mida muutsid. Kui fail muutus nii kohalikult kui Typemarkil, peatub see ja loetleb need. typemark pull --force võtab siis nende failide puhul Typemarki versiooni, pärast seda kui sinu versioon on salvestatud kausta .typemark/backup/.

Mõned nimed, mida Typemark salvestab, ei saa olla sinu arvuti failid: Windowsis nimed, mis sisaldavad < > : " | ? *, lõppevad punkti või tühikuga või on reserveeritud nimi nagu con.mdx; macOS-is ja Windowsis kaks nime, mis erinevad ainult suurtähtede poolest, nagu Guide.mdx ja guide.mdx. typemark pull leiab need enne kirjutamist, laadib alla kõik muu ja loetleb failid, mille jättis välja, ning miks. Nimeta need ümber Typemarkil või ühendatud repositooriumis ja pulli uuesti. Push sinu kaustast jätab need nagu on.

Failid, mida ei saadeta

Failid, mis sobivad kaustas oleva .gitignore või .typemarkignore-iga, ei saadeta kunagi, ega ka .git, node_modules, .DS_Store, Thumbs.db ja desktop.ini. Lisa mustandid või ehitusväljund faili .typemarkignore, et hoida need kohalikult.

Push võib korraga muuta kuni 500 faili ja 50 MB, kusjuures iga fail kuni 10 MB.

Windowsis salvestavad Git ja paljud redaktorid tekstifaile CRLF reavahetustega. See ei loe muudatuseks: push saadab teksti LF reavahetustega, nagu Git seda salvestab, ning pilte ja muid binaarfaile täpselt sellisena, nagu need on.

GitHubiga ühendatud projektid

Kui projekt sünkroniseerub GitHubiga, elavad selle failid GitHubis. typemark pull, check ja status töötavad, kuid typemark push keeldub. Tee selle asemel commit ja push GitHubi, siis avaldab Typemark sealt.

Dokumentatsiooni kontrollimine

typemark check loeb sinu kausta nii, nagu seda teeb Typemarki build, ja teatab:

VeadHoiatused
typemark.json puudub või pole kehtiv JSONLehed, mis pole navigeerimises, nii et lugejad neid ei leia
Navigeerimise kirjed ilma vastava lehe või OpenAPI failitaLehed, mis on navigeerimises rohkem kui üks kord
OpenAPI spetsifikatsioonid, mida ei saa parsida, koos reaga
MDX, mis ei ehitu, koos rea ja veeru numbrigaLehed ilma pealkirjata nende frontmatter'is
Frontmatter, mis pole kehtiv YAMLKomponendid, mida Typemark ei renderda
Lingid lehtedele, mis ei eksisteeri (lingid API viitelehtedele loetakse lehtedeks)import/export laused ja {expressions}, mis eemaldatakse avaldamisel
Lehed, mis on salvestatud baidijärjekorra märgiga (byte order mark), mille frontmatter'it Typemark ei suuda lugeda
Lehed, mille openapi lõpp-punkt ei ole üheski spetsifikatsioonis, nii et need näitavad ainult oma teksti
Failinimed, mida Windows või macOS ei saa salvestada, ja typemark pull jätab need seal välja
languages kirjed, mida Typemark ei saa kasutada, nagu kood, mis pole keelekood või esineb kaks kordalanguages, kus on ainult üks keel, nii et kogu sait on selles
Lehed navigeerimises keele kaustas, kuhu lugejad ei pääse
Tõlked, nagu fr/quickstart.mdx, lehtedest, mis pole navigeerimises
translate väärtus muu kui "ai" või "manual", või translations.do_not_translate, mis pole loend

Vead peatavad typemark push. Kasuta typemark check --strict, et ebaõnnestuda ka hoiatuste korral, näiteks CI-s. typemark push --no-check saadab ilma kontrollimata.

Migreerimine teisest platvormist

CLI teisendab Mintlify, GitBooki või ReadMe saidi kaustas sinu arvutis, sõltumata sellest, kus repositoorium asub. Importimiseks GitHubist brauseris vaata Migreerimine Typemarkile.

cd my-old-docs
typemark login
typemark migrate             # detects the platform, converts the folder, then offers to create the project and push it

typemark migrate otsib faile docs.json või mint.json (Mintlify), .gitbook.yaml või SUMMARY.md (GitBook) või kausta docs/ koos failidega _order.yaml (ReadMe), juurkaustas või kuni kaks kausta allpool. Ta teisendab need samal koodil, mis GitHubi import, prindib, mida ei saanud üle tuua, ja käivitab seejärel typemark check. Lisa --from mintlify, --from gitbook või --from readme, et tuvastamine vahele jätta, ja --dry-run, et näha tulemust ilma midagi kirjutamata.

  • Mintlify: kirjutatakse ainult typemark.json. Sinu lehti ja docs.json ei muudeta. Vt Mintlifyst.
  • GitBook ja ReadMe: lehed teisendatakse ja liigutatakse kohapeal, nii et kaust peab olema Giti repositoorium ilma commit'imata muudatusteta (--force jätab selle kontrolli vahele). Vaata tulemust käsuga git diff; git checkout -- . && git clean -fd võtab selle tagasi. Vt GitBookist ja ReadMe'st.

Pärast teisendamist küsib typemark migrate, kas luua kausta jaoks Typemarki projekt (nimetatud sinu saidi järgi; võid sisestada teise nime) ja seda siduda, ning seejärel, kas avaldada see uue projekti algelehtede asemel (typemark push --prune, pärast typemark check). Kui typemark check leiab vigu, ei paku see üleslaadimist: paranda need ja käivita siis typemark push --prune. Uue projekti sait jääb võrguühenduseta, kuni avaldad selle.

Skriptides, CI-s või koodiagendiga anna vastused lippudena: midagi ei küsita, kui väljund on --json, CI on määratud või sisend pole terminal.

typemark migrate --create "My Docs" --push

Kui loomine või üleslaadimine ebaõnnestub (paketi projektide limiit, kinnitamata e-posti aadress, kontrollivead, aegunud sisselogimine), jäävad teisendatud failid nii nagu on ja CLI ütleb, mida järgmisena käivitada. Et avaldada olemasolevasse projekti, käivita enne migreerimist typemark link my-project, seejärel typemark migrate --push, või pärast seda typemark push --prune.

Koodiagendiga

typemark migrate --agent claude käivitab sinu koodiagendi praeguses kaustas, kus juhistena on Typemarki migreerimisjuhend. Töötab ka codex, cursor ja gemini korral ning --from abil mis tahes platvormi nimega ja --source abil, kus sinu dokumendid praegu asuvad: kaust, repositoorium või elav sait.

typemark migrate --agent claude --from docusaurus --source ../old-docs

Agent töötab sinu arvutis sinu enda sisselogimisega. typemark migrate --guide prindib samad juhised mis tahes muule agendile. Kui agent pole installitud, ütleb CLI, kuidas seda installida; Windowsis installib Cursor PowerShellist käsuga irm 'https://cursor.com/install?win32=true' | iex. Vt Koodiagendiga.

Avaldamine CI-st

Kui soovid avaldada dokumendid, mis asuvad teises repositooriumis, näiteks kaustas docs/ sinu toote repos, saada need CI-st igal liitmisel:

  1. Loo token

    Loo API token ja salvesta see CI saladusena nimega TYPEMARK_TOKEN.

  2. Lisa CI samm

    CI-s kaust ei ole seotud, seega nimeta projekt muutujaga TYPEMARK_PROJECT. GitHub Actionsiga:

    - uses: actions/setup-node@v4
      with:
        node-version: 22
    - run: npx @gettypemark/cli push --prune --wait --message "docs: ${{ github.sha }}"
      working-directory: docs
      env:
        TYPEMARK_TOKEN: ${{ secrets.TYPEMARK_TOKEN }}
        TYPEMARK_PROJECT: acme-docs

Siin on repositoorium tõeallikas: --prune kustutab Typemarkil lehed, mida repositooriumis enam pole, ja Typemarki redaktoris tehtud muudatused kirjutatakse järgmise sama faili pushiga üle. Kui jätad --prune välja, lisatakse ja uuendatakse ainult.

Kui push ebaõnnestub kontrolli või build'i tõttu, ebaõnnestub samm koos põhjusega.

Skriptid ja AI agendid

Iga käsk võtab --json. Tulemus on üks JSON dokument standardväljundis ja edenemisteated lähevad standardvea voogu. Vead näevad välja nii:

{
  "error": {
    "code": "conflict",
    "exit_code": 5,
    "message": "1 file was also changed on Typemark since your last pull:\n  quickstart.mdx",
    "hint": "Nothing was pushed. Run `typemark pull` to see their version, then push again.",
    "conflicts": ["quickstart.mdx"]
  }
}

Koodid on API veakoodid, lisaks usage (käsurida on vale), not_linked (kaust pole projektiga seotud), already_linked (typemark create kaustas, mis on seotud teise projektiga), check_failed (typemark check leidis vigu) ja deploy_failed (koos --wait-iga ebaõnnestus avaldamine). Toetu koodile code ja väljumiskoodile; sõnumid on kirjutatud inimestele ja võivad muutuda.

Väljumiskoodid

KoodTähendus
0Õnnestus
1Midagi muud läks valesti: võrk, server, projekti pole, paketi limiit, ebaõnnestunud avaldamine
2Käsurida on vale: tundmatu käsk või valik, puuduv või liigne argument või lubamatu väärtus
3typemark check leidis vigu (või hoiatusi koos --strict-iga) või typemark push peatus nende tõttu
4Sa pole sisse logitud, või sinu sisselogimine või TYPEMARK_TOKEN on tühistatud, aegunud või vanem kui organisatsiooni üksiku sisselogimise nõue: käivita typemark login või kasuta uut tokenit
5Fail muutus nii siin kui Typemarkil: käivita typemark pull ja proovi uuesti
6See CLI versioon on liiga vana: käivita npm install -g @gettypemark/cli@latest

Need koodid ei muuda kunagi tähendust. Uusi lisatakse ainult ebaõnnestumistele, mis juba lõpevad nullist erineva koodiga.

Käsud

KäskMida teeb
typemark loginLogib sisse brauseri kaudu
typemark logoutLogib välja ja tühistab sisselogimise
typemark whoamiNäitab, kellena oled sisse logitud
typemark projectsLoetleb sinu projektid
typemark link [project]Seob praeguse kausta projektiga
typemark create <name>Loob projekti ja seob praeguse kausta sellega
typemark statusNäitab saiti, viimast avaldamist ja sinu kohalikke muudatusi
typemark deploymentsLoetleb viimased avaldamised, viimase hoiatustega, näiteks failid, mida sinu GitHubi repositoorium sisaldab ja sait ignoreerib. -n 20 näitab rohkem.
typemark open [site|editor|settings]Avab projekti brauseris. --print prindib aadressi.
typemark pull [project] [folder]Laadib projekti uude kausta alla või uuendab seotud kausta
typemark pushLaeb sinu muudatused üles ja avaldab need
typemark new <page>Loob lehe ja lisab selle navigeerimisse
typemark devEelvaatab sinu dokumente kohalikult, laadides uuesti iga salvestuse peale
typemark checkLeiab probleemid enne pushi
typemark migrateTeisendab Mintlify, GitBooki või ReadMe saidi ning pakub projekti loomist ja pushi (--create, --push) või käivitab sinu koodiagendi muu migreerimise jaoks

Käivita typemark help <command>, et näha selle valikuid.

Seaded

MuutujaVaikimisiMida teeb
TYPEMARK_TOKENAPI token, mida kasutada typemark login asemel
TYPEMARK_PROJECTSeotud projektKasutatav projekt. Sama mis --project.
TYPEMARK_API_URLhttps://typemark.devTypemarki server, millega suhelda. Sama mis --api-url.
TYPEMARK_CONFIG_DIR~/.config/typemarkKus typemark login hoiab sinu sisselogimist (Windowsis %APPDATA%\typemark)