Creați și personalizați un site Docusaurus (cu funcția de blog)

Pentru site-uri web ușoare, aplicații și alte proiecte mici, din ce în ce mai mulți dezvoltatori apelează la generatoare de site-uri statice prin WordPress sau alte sisteme de gestionare a conținutului (CMS). Site-urile statice oferă o modalitate simplă și eficientă de a crea site-uri web și aplicații care sunt rapide, sigure și ușor de întreținut.

Docusaurus este un astfel de generator de site-uri static - și câștigă rapid în popularitate în comunitatea de dezvoltare. V-ați săturat de sistemele lente de management al conținutului? Faceți cunoștință cu Docusaurus! Un generator de site static care își face treaba fără să vă încetinească. Citiți mai departe pentru a afla mai multe Click to Tweet

În această postare, vom analiza în profunzime beneficiile utilizării Docusaurs ca generator de site-uri static și de ce este un favorit în creștere printre dezvoltatori.

Ce este Docusaurus?

Docusaurus este un generator de site-uri static popular care folosește React, una dintre cele mai importante biblioteci JavaScript, ca bibliotecă UI pentru crearea paginilor. La fel ca și alte astfel de generatoare, este ușor de configurat și ușor de modificat și, cel mai important, vă oferă tot ceea ce aveți nevoie pentru a începe funcționarea site-ului dvs. static.

Totuși, ceea ce diferențiază Docusaurus este faptul că vă ajută să creați și să gestionați un site web în care conținutul joacă un rol cheie . Vă permite să construiți rapid și ușor un site web complet - complet cu o funcție de blog - care vă pune în valoare conținutul de la început.

Deoarece conținutul se află în centrul atenției cu Docusaurus, este perfect pentru a crea site-uri de documentare precum wiki-uri. De asemenea, utilizează markdown, care este ideal atât pentru colaborare, cât și pentru stocare într-un depozit git. În plus, are o mulțime de funcții uimitoare, cum ar fi i18n, căutare și teme personalizate, pe care le vom discuta mai detaliat mai târziu.

Iată doar câteva dintre caracteristicile remarcabile care fac din Docusaurus o opțiune solidă:

• Construit folosind React
• Suport pentru MDX v1
• Suport pentru încorporarea componentelor React prin Markdown
• Versiune document
• Compatibilitate cu Git, Crowdin și alți manageri de traducere pentru traducerea documentelor și implementarea în bloc sau individuală

Cine folosește Docusaurus?

Docusaurus a fost creat de Facebook, așa că nu este surprinzător faptul că este utilizat în prezent de multe mărci și companii mari de pe web.

Iată doar câteva dintre cele mai mari mărci care folosesc Docusaurus astăzi (cu multe altele vor veni în curând, pe măsură ce popularitatea lui Docusaurus continuă să crească):

• Algolia DocSearch
• Glumă
• Reacționează nativ
• Supabaza

Și mai mulți se alătură rândurilor lor în fiecare zi.

Cum se instalează Docusaurus

Docusaurus este foarte simplu de instalat și necesită doar câteva minute. În acest tutorial, vom construi un site de documentare cu un blog și vom personaliza modul în care arată site-ul web.

Și iată cea mai tare parte: ne va dura mai puțin de o oră să învârtim totul.

Să ne scufundăm!

Cerințe

Docusarus necesită Node.js 16.14 sau mai nou. Este un SSG cu fișier plat, ceea ce înseamnă că nu veți avea nevoie de o bază de date suplimentară.

Dacă nu aveți deja disponibil Node.js 16.14+, va trebui să începeți prin a instala Node.js sau să actualizați versiunea curentă. Apoi puteți trece la procesul de instalare Docusaurus de mai jos.

De asemenea, vom folosi exemplul de site Docusaurus din acest depozit GitHub. Îl puteți folosi sau o instalare curată a Docusaurus pentru acest tutorial.

Procesul de instalare

Pentru a începe procesul de instalare a Docusaurus, mai întâi trebuie să rulați următoarea comandă:

 npx [email protected] classic

Acest lucru va crea un folder pentru proiectul dvs. și va schelă tema clasică în interiorul acestuia. Tema clasică conține deja câteva funcții preconfigurate, cum ar fi un blog, pagini personalizate și un cadru CSS.

După instalare, trebuie să rulați următoarea comandă pentru a porni serverul local:

 npm start

Dacă doriți să construiți o versiune optimizată care este gata de implementare, ar trebui să rulați aceasta:

 npm run build

Structura

Odată ce ați instalat instanța Docusaurus, veți putea deschide directorul de proiect și veți vedea mai atent „scheletul” noului site.

Iată cum arată structura fișierului:

 my-website ├── blog │ ├── 2019-05-28-hola.md │ └── 2020-05-30-welcome.md ├── docs │ ├── doc1.md │ └── mdx.md ├── src │ ├── css │ │ └── custom.css │ └── pages │ ├── styles.module.css │ └── index.js ├── static │ └── img ├── docusaurus.config.js ├── package.json ├── README.md ├── sidebars.js └── yarn.lock

Există câteva detalii de reținut cu privire la câteva dintre aceste fișiere și foldere:

• /blog : Conține toate fișierele legate de blogul tău.
• /docs : Conține toate fișierele legate de documentele dvs. Puteți personaliza ordinea acestora în fișierul sidebar.js .
• /src : Conține toate fișierele care nu sunt documentate, cum ar fi paginile sau componentele personalizate.
• /src/pages : Toate fișierele JSX/TSX/MDX vor fi transformate în pagini.
• /static : Fișiere statice care vor fi copiate în folderul de compilare final.
• docusaurus.config.js : fișier de configurare Docusaurus.
• packaged.json : Fiecare site Docusaurus este o aplicație React, așa că aici veți găsi toate dependențele și scripturile pe care le folosește pentru React.
• sidebar.js : Aici puteți specifica ordinea documentelor în bara laterală.

Personalizarea instalării Docusaurus

După cum puteți vedea din simplitatea structurii sale de fișiere, Docusaurus este ușor de utilizat și de navigat. De asemenea, personalizarea site-ului dvs. Docusaurus este ușoară. Puteți deschide și edita aceste fișiere folosind editorul de text sau IDE-ul preferat.

Să trecem peste câteva dintre opțiunile de personalizare pe care le veți avea imediat din cutie.

Pagina principala

Primul lucru pe care probabil că veți dori să îl faceți este să personalizați pagina de pornire implicită pentru a vă expune propriul proiect. Din fericire, nu este complicat să faci orice modificări pe care le dorești în pagina principală Docusaurus.

Pentru a modifica pagina de pornire, deschideți fișierul src/pages/index.js și faceți ajustări chiar acolo. Este o pagină tipică React, așa că o puteți modifica sau reconstrui modificând conținutul sau creând componente React personalizate.

Fișier de configurare

În continuare, ne vom scufunda în fișierul crucial docusaurus.config.js și vom modifica câteva detalii importante pentru instanța noastră.

Nume și descriere

În fișierul de configurare, veți găsi:

 const config = { title: 'My Site', tagline: 'Dinosaurs are cool', url: 'https://your-docusaurus-site.com', baseUrl: '/',

Doar modificați aceste detalii pentru a se potrivi nevoilor site-ului dvs., apoi salvați fișierul.

Bară de navigare

Pentru a edita bara de navigare, localizați elementul navbar .

Pentru exemplul nostru de aici, dorim să adăugăm un link către Kinsta, să redenumim elementul „Tutorial” în „Documentație de pornire” și să adăugăm sigla Kinsta.

Iată cum am proceda:

 navbar: { title: 'Kinsta starters', logo: { alt: 'Kinsta Logo', src: 'img/kinsta-logo-alpha-purple.png', }, items: [ { label: 'Kinsta starters', to: '/docs/intro', }, {to: '/blog', label: 'Blog', position: 'left'}, { href: 'https://github.com/kinsta', label: 'GitHub', position: 'right', }, ], },

Subsol

Personalizarea subsolului în Docusaurus este alcătuită din două secțiuni: conținutul subsolului în sine și linkurile de subsol.

Conținut de subsol

Cea mai mare parte a conținutului subsolului dvs. (fără a include lista de linkuri) poate fi plasată în fișierul themeConfig.footer . Acesta este locul ideal pentru a adăuga un logo și o notificare privind drepturile de autor.

Iată cum ne-am modificat configurația subsolului:

 module.exports = { themeConfig: { footer: { logo: { alt: 'Kinsta Logo', src: 'img/kinsta-logo.png', href: 'https://kinsta.com', width: 160, height: 51, }, copyright: `Copyright ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`, }, }, };

Linkuri de subsol

Modificarea legăturilor de subsol este similară cu schimbarea barei de navigare de sus: găsiți secțiunea footer în docusaurus.config.js și editați până când se potrivește nevoilor dvs.

Iată cum ne-am schimbat secțiunea footer pentru a arăta:

 footer: { style: 'dark', links: [ { title: 'Docs', items: [ { label: 'Kinsta starters', to: '/docs/intro', }, ], }, { title: 'Talk with us', items: [ { label: 'Discord', href: 'https://discord.gg/vjRPMhFaBA', }, { label: 'Support', href: 'https://kinsta.com/kinsta-support/', }, { label: 'Twitter', href: 'https://twitter.com/kinsta', }, ], }, { title: 'More', items: [ { label: 'Application Hosting', href: 'https://kinsta.com/application-hosting/', }, { label: 'Database Hosting', href: 'https://kinsta.com/database-hosting/', }, { label: 'WordPress Hosting', href: 'https://kinsta.com/wordpress-hosting/', }, { label: 'DevKinsta', href: 'https://kinsta.com/devkinsta/', }, ], }, ], };

Culori și CSS

Presetarea clasică pentru Docusaurus utilizează cadrul CSS Infima. Având în vedere acest lucru, creatorii Docusaurus au creat un instrument web foarte util pentru a vă ajuta să schimbați culorile și alte elemente și declarații CSS.

Odată ce ați introdus preferințele pe pagină, instrumentul va genera un fișier custom.css - complet cu o suită minunată de tonuri complementare - în câteva secunde. Apoi puteți copia acest nou fișier CSS în directorul /src/css al proiectului dumneavoastră pentru referință.

Documentație

Toată documentația de pe noul dvs. site web este stocată în folderul /docs . Desigur, puteți schimba numele folderului în docusaurus.config.js .

Doar creați fișierele markdown în editorul dvs. de text sau HTML și plasați-le în acel folder. Fiecare fișier ar trebui să arate astfel:

 --- id: the-id title: Title --- # Rest of the document

Pe baza ID-ului, Docusaurus creează adresele URL pentru articolele din acel subdosar: yourdomain.com/docs/{id}

De asemenea, putem crea subfoldere dacă dorim să ne împărțim documentația în diferite secțiuni logice. Cu toate acestea, va trebui să facem puțină muncă suplimentară pentru ca aceste subdirectoare să funcționeze așa cum ne-am aștepta.

Să presupunem că creăm un nou folder de documente numit „Starters”. Dacă ar fi apoi să reîmprospătăm pagina de pornire și să facem clic pe noul link „Starters” adăugat automat în bara noastră laterală, vom primi o eroare - deoarece nu există încă o pagină de index în noul nostru dosar.

Cel mai simplu mod de a remedia acest lucru este să creați un fișier _category_.json care va genera indexul tuturor paginilor care sunt stocate în acest folder. Trebuie doar să adăugați următorul cod:

 { "label": "Starters", "position": 2, "link": { "type": "generated-index", "description": "All Kinsta Starters" }, };

După cum puteți vedea, bara laterală se regenerează pentru a se potrivi cu structura fișierelor dvs. Asta pentru că fișierul sidebar.js conține acest tutorialSidebar : [{type: 'autogenerated', dirName: '.'}],

Dacă preferați să vă ocupați de acest lucru pe cont propriu, puteți schimba acest lucru în ceva de genul acesta:

 tutorialSidebar: [ 'intro', 'hello', { type: 'category', label: 'Tutorial', items: ['tutorial-basics/create-a-document'], }, ],

Blog

Docusaurus include un modul de blog slick. Crearea unui blog alături de site-ul dvs. principal poate fi foarte utilă pentru a vă informa baza de utilizatori cu privire la modificările care au loc în proiectul dvs. sau pentru a continua să rulați note de proiect ca o formă de jurnal de modificări.

Fiecare postare constă dintr-o parte frontală, astfel:

 --- slug: docusaurus-starter title: Docusaurus Starter authors: palmiak tags: [starters, docusaurus] ---

… și, desigur, conținutul în sine. Are, de asemenea, o etichetă <!--truncate--> foarte utilă, care ajută la limitarea rezumatului postărilor afișate pe toate postările.

De asemenea, este o idee grozavă să creați un fișier authors.yml pentru credite. Fișierul arată astfel:

 palmiak: name: Maciek Palmowski title: DevRel url: https://github.com/palmiak image_url: https://github.com/palmiak.png

Datorită acestui fișier, veți avea toate datele autorului într-un singur loc pentru o referire ușoară.

Cum să vă implementați site-ul web Docusaurus la Kinsta

Pe lângă site-urile WordPress, aplicațiile autonome și bazele de date, Kinsta poate găzdui site-uri web statice.

Aceasta înseamnă că este perfect pentru site-urile dvs. Docusaurs - și pentru gestionarea tuturor proiectelor dvs. web - direct din tabloul de bord MyKinsta.

Odată ce aplicația dvs. a fost implementată, veți putea revizui analizele în curs de desfășurare a aplicației dvs., atât în ​​timp real, cât și istoric, cu măsurători care includ:

• Utilizarea lățimii de bandă
• Construiește timp
• Timp de rulare
• Utilizarea procesorului
• Folosirea memoriei

De la început până la sfârșit, procesul de implementare prin MyKinsta durează doar câteva minute.

Să începem!

Cerințe preliminare: configurarea proiectului Docusaurus

Pentru a vă găzdui proiectul Docusaurus pe platforma de găzduire a aplicațiilor Kinsta, va trebui să:

1. Includeți un câmp de nume în fișierul package.json . (Acest lucru poate fi orice și nu vă va afecta implementarea.)
2. Includeți un script de compilare în fișierul package.json . (Proiectul dvs. Docusaurus ar trebui să includă deja acest lucru.)
3. Instalați pachetul serve npm și setați scriptul de pornire pentru a servi build.

După ce acestea sunt bifate, puteți trece la implementarea efectivă a site-ului dvs.

Implementarea proiectului Docusaurus

Urmați acești pași simpli pentru a vă conecta la contul GitHub și a lansa site-ul Docusaurus:

1. Conectați-vă la contul MyKinsta și navigați la fila Aplicații din meniul din stânga.
2. Faceți clic pe butonul albastru Adăugați serviciu și alegeți Aplicație din meniul drop-down.

   

3. Dacă nu v-ați conectat încă la contul GitHub prin MyKinsta, vi se va afișa un mod care vă încurajează să faceți acest lucru. Faceți clic pe butonul Continuați cu GitHub pentru a continua.

   

4. Se va deschide o nouă fereastră, solicitând permisiunea dvs. de a autoriza Kinsta să acceseze și să gestioneze resursele dvs. GitHub. Asigurați-vă că v-ați conectat la contul GitHub corect, apoi faceți clic pe butonul verde Autorizare Kinsta din partea de jos.

   

5. Ați ajuns acum la expertul de integrare GitHub. Acesta este ultimul pas înainte de a vă putea implementa site-ul. Luați în considerare cu atenție câmpurile prezentate și completați-le în funcție de configurația dvs. GitHub și de cerințele proiectului. Dacă aveți un Dockerfile în depozit, îl puteți folosi pentru a configura imaginea containerului; în caz contrar, Kinsta va configura automat o imagine de container pentru dvs. Rețineți că poate fi necesar să vă editați permisiunile GitHub înainte de a putea continua, mai ales dacă aceasta este prima dvs. implementare prin Kinsta.

   

   Puteți alege dacă să acordați acces Kinsta la toate depozitele sau numai la unele anume. Aceste permisiuni pot fi ajustate oricând din setările de aplicații ale contului tău GitHub.

   

6. După ce ați făcut selecțiile și le-ați confirmat, vi se vor afișa detaliile despre implementare, precum și opțiunile pentru Modificarea setărilor sau Reimplementarea .

   

   Tot aici veți vedea orice erori care au apărut în timpul implementării, împreună cu detalii despre ce a cauzat defecțiunea, astfel încât să o puteți rezolva cu ușurință. Dacă vă confruntați cu dificultăți pentru a remedia problema, îndrumări suplimentare despre erorile de lansare pot fi găsite în documentația Kinsta.

   

Dacă ați ajuns până aici fără erori, atunci felicitări - tocmai v-ați implementat cu succes site-ul Docusaurus prin Kinsta! Aplicația dvs. (adică site-ul dvs. static) este disponibilă imediat ce ați finalizat expertul. Îl puteți vizualiza la adresa URL a aplicației dvs., care este de obicei https:// your-docusaurus-site .kinsta.app .

Iată prima noastră privire asupra site-ului nostru exemplu de pe Kinsta:

rezumat

Cu caracteristicile sale surprinzător de puternice, designul prietenos, navigarea intuitivă și concentrarea pe conținut, nu este greu de înțeles de ce Docusaurus este considerat un instrument excelent pentru orice dezvoltator care dorește să implementeze și să mențină cu ușurință un site de documentație statică simplificat, bine organizat și/sau blog. Schimbați-vă jocul de dezvoltare web! Spune-ți la revedere CMS-ului neplăcut și salută Docusaurus - un simplu generator de site-uri static care schimbă jocul dezvoltatorului. Verificați-l chiar aici ️ Faceți clic pentru a trimite pe Tweet

Odată ce ați umplut site-ul cu conținut pe care vizitatorii dvs. îl vor aprecia, veți începe să luați notă de funcțiile încorporate suplimentare care vă sunt utile. De exemplu, capabilitățile de optimizare pentru motoarele de căutare ale Docusaurus sunt perfecte pentru a vă ajuta să obțineți o vizibilitate îmbunătățită printr-un public mai larg, în timp ce lucrați la alte tehnici de avansare în clasamentele SEO.

Ai construit ceva cu Docusaurus? Împărtășiți-vă proiectele și experiența cu noi în secțiunea de comentarii de mai jos.