Skep 'n dokumentasiewebwerf

Dokumentasie kom in baie vorms en tipes voor. U het dalk reeds sommige hulpbronne of moet van voor af begin. Kom ons kyk hoe om inhoud met Archbee by te voeg.

Sodra u 'n nuwe dokument skep, kan u begin om inhoud by te voeg deur óf Markdown-kortpaaie óf enige van die 30+ pasgemaakte blokke te gebruik.

Die pasgemaakte blokke help u om die inhoud te formateer soos u dit benodig. Om hulle oop te maak, tik 'n vorentoe-skuinsstreep / in die redigeerder en gaan deur die opsies.

Die blokke is gegroepeer onder Basies, Media, Ontwikkelaar, Inbed, en Hergebruik van inhoud.

Byvoorbeeld, as u dinamies na ander dokumente wil skakel, tik @ en die dokumenttitel. Dit sal met die dokument-ID verbind. As u die titel of die posisie van die dokument verander, sal die skakel altyd daarna wys.

Nog 'n voorbeeld is om die bloknaam op te roep. Druk / en tik die blok se naam, bv. /verticalsplit, wat die blok waarvoor u wil gebruik sal uitfilter.

Die derde opsie is om hakies te gebruik, en die naam van die blok - bv. (api) - sal die API-endpuntblok byvoeg.

Die outydse kopieer-en-plak-broers. Maar hoekom hierdie een dek? Aangesien Archbee se redigeerder Markdown ondersteun, kan u die volgende boodskap kry as u in hierdie formaat wil plak:

As u op die kanselleer-knoppie klik, sal die inhoud nie weergegee word nie, en as u op OK in die dialoogkassie klik, sal ons die Markdown na Archbee se blokke omskakel.

Dus het u 'n kodevoorbeeld wat as 'n kode-redigeerderblok in Archbee weergegee sal word.

Kopieer-en-plak werk heeltemal goed, maar as u Markdown- of Word-lêers het, hoekom dit nie in 'n Space invoer nie?

Voordat u enige inhoud invoer, maak seker dat u op die Space klik waar u die lêers wil invoer. U het pas op die tipe lêer wat u het geklik en minute se kopieer-en-plak vanaf ander bronne bespaar.

Wanneer dit by die dokumentering van APIs kom, het u verskeie opsies.

Kom ons sê u gebruik die OpenAPI-standaard (voorheen Swagger). Dit maak maklike invoer en sinkronisering van die lêers moontlik.

Sodra dit na Archbee ingevoer is, sal die inhoud in 'n 3-kolom-uitleg weergegee word wat maklik-bestuurbare dokumentasie moontlik maak.

Dit gebeur dat die dokumentasie in 'n GitHub repository geskryf is, en u kan voortgaan om in GitHub te skryf en die repo met 'n Archbee Space sinkroniseer. Die voordeel is dat u daardie Space na u pasgemaakte domein kan publiseer en ander Spaces met bykomende inligting soos API-verwysings kan byvoeg.

Voordat u met die inhoud begin, neem 'n klein stap wat later 'n verskil sal maak. Stel u subdomein op om toegang tot die voorskou- en produksie-omgewings te hê. Gaan na die dokumentasiebladsy en volg die stappe om u pasgemaakte domein by te voeg.

Veelvuldige opsies is beskikbaar onder die Algemeen-oortjie - u kan Indekseerbaar deur soekenjins afskakel (indien publiek) vanuit dieselfde Space Settings. U wil dit dikwels geaktiveer hê sodat gebruikers u webwerf op die soekenjin-resultatebladsy kan vind. U kan na die Public access control-opsie gaan en enige van die vyf opsies kies vir meer beheer.

Voordat u enige dokumentasie skryf, oorweeg die hoofonderwerpe wat u gaan dek. Hierdie keer kan 'n pen en papier u help om die struktuur te teken.

Skep vervolgens 'n dokument, omskep dit na 'n kategorie, en gee dit 'n naam.

Sodra u hierdie het, is u gereed om dokumente onder elke kategorie by te voeg.

Begin met 'n dokument wat die hoofthings bekendstel wat 'n gebruiker op die dokumentasiewebwerf sal vind. Dit hoef nie ingewikkeld te wees nie; hier is hoe ons dit in ons Gebruiker- en ontwikkelaargids: gedoen het

Wanneer u begin om inhoud by te voeg, is dit noodsaaklik om 'n werkvloei te hê. Hier is 'n moontlike een, maar u wil dit dalk aanpas:

Werk met templates maak dit maklik vir bydraers om inhoud te begin skryf. U kan 'n stel templates stoor om u te help om inhoudproduksie vinnig aan die gang te kry. As u inspirasie benodig, wanneer u 'n nuwe dokument skep, sal u 'n knoppie genaamd: Start with a template onderaan die bladsy sien. Om u eie templates te bou, gaan na die navigasie aan die linkerkant, Templates, en begin dokumente skep met die struktuur wat u dokumente benodig.

U kan ook die pasgemaakte blokke bekendstel wat 'n outeur sal gebruik of voorbeelde uit ander bronne byvoeg.

Hierdie opsies is op dokumentvlak. U moet dus op die drie kolletjies ⋮ regs bo klik en SEO-meta-kontroles kies.

Voeg 'n relevante titel by, verander die URL, skryf 'n meta beskrywing of laai 'n beeld op vir voorskoue.

In die Voorkoms-oortjie sal u die handelsmerkopsies vind soos Aksentkleur, Logo, en Favicon, saam met ander opsies vir die sjabloon.

Afhangend van die tipe produkte of dienste, wil u dalk verskillende Space URL-paaie hê.

U kan ’n Space as die primêre dokumentasie hê en verskillende Spaces vir ander produkte of selfs weergawes daarvan skep.

Daar is ’n kortpad! U kan ’n kloon van enige Space skep as die veranderinge inkrementeel is. Dit sal u help om die struktuur te behou en die wysigings vir die nuwe weergawe aan te bring.

Dus, as weergawebeheer en multiprodukte iets is wat u benodig, gebruik verskillende Spaces en voeg dit by met die toepaslike pad of pasgemaakte domein.

Gaan na Space-skakels en begin u navigasie bou.

Die hoofdoel van die tuisblad is om die besoeker te help om na die volgende bladsy te gaan.

Die bou van ’n bestemmingsbladsy vir u dokumentasie-webwerf hoef nie dieselfde praktyke as ’n aanbiedingswebwerf te volg nie.

Die eerste dokumentbladsy is belangrik om u produk of diens aan die gebruikers bekend te stel, dus help dit baie om dit kort te hou en verwagtinge te stel.

U kan die Pasgemaakte bestemmingsbladsy-funksie gebruik en u eie HTML byvoeg vir meer beheer oor die eerste bladsy. Daar is baie opsies om inspirasie uit te kry, en as u die voorkoms en gevoel van die eerste bladsy wil verander, is dit u opsie.

Hier is hoe een van ons kliënte hul beginbladsy vir hul hulppagina gebou het.

Gebruik Gepasmaakte CSS as u u eie geur by die dokumentasiewebwerf wil voeg. As u vertroud is met CSS-klasse, sal u ’n paar begin-ab's vind en u kan hulle teiken.