GitBook är en plattform som låter dig bygga dokumentationssajter eller företagswikis. Du kan använda den för att dokumentera alla möjliga saker, från kod till API: er och hur man använder en mjukvaruprodukt.

GitBook använder en liknande process som GitHub-förråd. Huvudkopian av dokumentationen fungerar som en "master"-kopia. Du kan sedan skapa "utkast", som liknar "grenar".

Denna process gör det möjligt för många användare att arbeta på en enda dokumentationsplats samtidigt som de hanterar eller förhindrar konflikter. Det tillåter också ändringar från olika grenar att gå igenom en granskningsprocess innan du slår ihop dem.

Hur man börjar använda GitBook

Du kan välja mellan flera GitBook-priser planer. Prissättningen beror på om du använder GitBook för projekt med öppen källkod, personligt bruk eller privat teamsamarbete. GitBook är gratis att använda om du använder den för projekt med öppen källkod.

GitBook stöder Markdown, ett populärt märkningsspråk med många fördelar för att skriva eller dokumentera på webben.

instagram viewer

GitBook integreras också med GitHub, en plattform för värd, lagring och redigering av kod. Du kan länka ditt GitBook-konto direkt till ditt GitHub-konto genom att logga in med dina GitHub-uppgifter.

  1. Registrera dig till GitBook. Om du har ett eget GitHub-konto kan du klicka på Registrera dig med GitHub.
  2. När du har loggat in kommer GitBook att omdirigera dig till en ny intern wiki. Det kommer också att förfylla din wiki med lite exempelinnehåll.

En översikt över GitBook-gränssnittet

GitBook har flera funktioner som låter dig bygga och göra ändringar på din dokumentationssida.

  1. Den övre panelen låter dig skapa nya utkast, se ändringshistoriken eller visa andra diskussioner eller bilagor.
  2. Sidofältet längst till vänster låter dig skapa flera utrymmen. Du kan använda separata utrymmen för olika projekt så att du kan separera och organisera dina dokumentationsområden. Du kan utöka eller stänga sidofältet.
  3. Den vänstra panelen fungerar som en meny för dokumentationssidan. Du kan visa sidorna på din dokumentationswebbplats och använda den för att skapa grupper och kapslade sidor. Du kan också navigera över webbplatsen med hjälp av länkarna.
  4. Den nedre panelen innehåller knappar som är avgörande för versionskontrollprocessen. Du kan lägga till ett namn för ditt utkast, slå samman en ändring eller skicka in ändringen för granskning.

Hur man skapar ett nytt utkast

Du kan skapa ett nytt utkast genom att skapa en ny ändringsbegäran och göra ändringar i den.

  1. Klicka på i den övre panelen Ändringsförfrågningar.
  2. På den nya panelen som visas till höger klickar du på Förslag flik. Detta kommer att visa dig alla dina aktiva utkast.
  3. Härifrån kan du klicka på ett befintligt utkast för att öppna det. För att skapa ett nytt utkast, klicka på Ny ändringsförfrågan, och vänta på att sidan ska laddas klart.
  4. Klicka på i den nedre panelen Ange ett ämne. Detta öppnar ett fönster där du kan ge det nya utkastet ett namn. Till exempel, Ny sida - Hur man ställer in kodbas.

Hur man skapar sidor och grupper

När du har ett utkast kan du börja göra ändringar i dokumentationen. GitBook lagrar dina ändringar i utkastet, så att de inte påverkar huvudkopian. Du kan använda det vänstra sidofältet för att lägga till sidor och sidgrupper.

  1. Skapa en ny sida genom att klicka på Ny sida länk längst ned i sidofältet och välj Ny dokumentsida från rullgardinsmenyn. Alternativt kan du hålla muspekaren under en befintlig sida och klicka på den blå plus knapp.
  2. För att skapa en ny sidgrupp, klicka på Ny sidaoch välj Ny grupp alternativ från rullgardinsmenyn.
  3. Du kan byta namn på sidan genom att klicka på de tre prickarna bredvid sidan eller gruppen och välja Döp om.
  4. Börja lägga till innehåll för att fylla din nya sida. Du kan lägga till enkelt innehåll som text eller rubriker. GitBook låter dig också lägga till andra innehållsblock som bilder, filbilagor, tabeller, flikar eller kodavsnitt. Det finns också möjlighet att lägga till andra integrationer som YouTube-inbäddningar eller Google Docs-innehåll.
  5. Klicka på Diff vy knappen i den nedre panelen för att se skillnaderna mellan ditt utkast och originalkopian av originaldokumentationen.
  6. När du har skrivit klart ditt innehåll kan du klicka på Sammanfoga, Skicka in och slå samman, eller Skicka in för granskning.

Du kan komma åt delningslänken från topppanelen på GitBook. Du måste vara ute ur ett utkast och se huvuddokumentationen för att kunna se länken.

  1. Som standard är synligheten för din dokumentationswebbplats "olistad". Det betyder att du kan komma åt dokumentationssidan via en privat länk, och inte via sökmotorer. I den övre panelen klickar du på Onoterat knapp.
  2. Välj önskade synlighetsinställningar från rullgardinsmenyn. Observera att GitBook kan låsa vissa synlighetsinställningar, och du kan behöva uppgradera för att komma åt dem.
  3. Under listan med synlighetsinställningar finns en länk som du kan dela med andra användare som kommer att använda din dokumentationswebbplats. Kopiera denna länk för att dela den med andra.
  4. Klicka på under länken Länk- och domäninställningar. Det är här du kan länka ett anpassat domännamn eller ändra en del av webbadressen. Om du använder en anpassad domän kan du visa Gitbooks dokumentation om hur du korrekt konfigurerar din DNS.

Skapa dokumentation med GitBook

GitBook låter dig skapa och arbeta på dokumentationssajter eller företagswikis i samarbete. GitBook lånar koncept från GitHub som grenar och sammanslagning för att kontrollera en huvudkopia och hantera eventuella konflikter.

Du kan skapa ett nytt utkast för att lägga till dina egna individuella ändringar i dokumentationen. I utkastet kan du göra ändringar i innehållet, samt lägga till nya sidor eller sidgrupper. När du har gjort dina ändringar kan du antingen slå ihop dem eller skicka in dem för granskning.

Om du skapar intern dokumentation för din Java-kod kanske du vill utforska Javadoc. Javadoc låter dig dokumentera din Java-kod automatiskt.