W przypadku lekkich witryn, aplikacji i innych małych projektów coraz więcej deweloperów zwraca się ku generatorom witryn statycznych zamiast WordPressa lub innych systemów zarządzania treścią (CMS). Witryny statyczne oferują prosty i skuteczny sposób tworzenia witryn i aplikacji, które są szybkie, bezpieczne i łatwe w utrzymaniu.
Docusaurus jest jednym z takich generatorów stron statycznych i szybko zyskuje na popularności wśród społeczności programistów.
W tym poście przyjrzymy się bliżej korzyściom płynącym z używania Docusaurs jako generatora stron statycznych i dlaczego jest on coraz bardziej popularny wśród programistów.
Czym jest Docusaurus?
Docusaurus to popularny generator statycznych witryn, który wykorzystuje React, jedną z najlepszych bibliotek JavaScript, jako bibliotekę interfejsu użytkownika do tworzenia stron. Podobnie jak inne tego typu generatory, jest łatwy w konfiguracji i modyfikacji, a — co najważniejsze — zapewnia wszystko, czego potrzebujesz, aby od razu zacząć pracę nad statyczną witryną.
Jednakże tym, co wyróżnia Docusaurus, jest to, że pomaga Ci tworzyć i zarządzać witryną, w której treść odgrywa kluczową rolę. Umożliwia szybkie i łatwe zbudowanie pełnej witryny internetowej — z funkcją bloga — która od samego początku eksponuje Twoją treść.
Ponieważ w Docusaurusie najważniejsza jest treść, jest on idealny do tworzenia witryn dokumentacyjnych, takich jak wiki. Wykorzystuje również markdown, który jest idealny zarówno do współpracy, jak i przechowywania w repozytorium git. Co więcej, ma mnóstwo niesamowitych funkcji, takich jak i18n, wyszukiwanie i niestandardowe motywy, które omówimy bardziej szczegółowo później.
Oto kilka wyróżniających się cech, które sprawiają, że Docusaurus jest solidną opcją:
- Zbudowano przy użyciu React
- Wsparcie dla MDX v1
- Obsługa osadzania komponentów React za pośrednictwem Markdown
- Wersjonowanie dokumentów
- Zgodność z Git, Crowdin i innymi menedżerami tłumaczeń w celu tłumaczenia dokumentów i wdrażania zbiorczego lub indywidualnego
Kto używa Docusaurus?
Docusaurus został stworzony przez Facebooka, więc nic dziwnego, że obecnie korzysta z niego wiele dużych marek i firm w Internecie.
Oto kilka największych marek, które obecnie korzystają z Docusaurus (a wkrótce dołączą do nich kolejne, gdyż popularność Docusaurus stale rośnie):
I każdego dnia dołączają do nich kolejni.
Jak zainstalować Docusaurus
Docusaurus jest bardzo prosty w instalacji i wymaga tylko kilku minut. W tym samouczku zbudujemy witrynę dokumentacji z blogiem i dostosujemy wygląd witryny.
A oto najfajniejsza część: zajmie nam to mniej niż godzinę, żeby wszystko rozkręcić.
Zanurzmy się!
Wymagania
Docusarus wymaga Node.js 16.14 lub nowszego. Jest to płaski plik SSG, co oznacza, że nie będziesz potrzebować dodatkowej bazy danych.
Jeśli nie masz jeszcze Node.js 16.14+, musisz zacząć od zainstalowania Node.js lub uaktualnienia bieżącej wersji. Następnie możesz przejść do procesu instalacji Docusaurus poniżej.
Będziemy również korzystać z przykładowej witryny Docusaurus z to repozytorium GitHub. Możesz użyć go lub czystej instalacji Docusaurus na potrzeby tego samouczka.
Proces instalacji
Aby rozpocząć proces instalacji Docusaurus, musisz najpierw uruchomić następujące polecenie:
npx create-docusaurus@latest classic
Spowoduje to utworzenie folderu dla Twojego projektu i utworzenie rusztowania klasyczny motyw w środku. Klasyczny motyw zawiera już pewne wstępnie skonfigurowane funkcje, takie jak blog, strony niestandardowe i framework CSS.
Po instalacji należy uruchomić następujące polecenie, aby uruchomić serwer lokalny:
npm start
Jeśli chcesz zbudować zoptymalizowaną wersję gotową do wdrożenia, powinieneś uruchomić to polecenie:
npm run build
Struktura
Po zainstalowaniu instancji Docusaurus będziesz mógł otworzyć katalog projektu i przyjrzeć się bliżej „szkieletowi” swojej nowej witryny.
Oto jak wygląda struktura pliku:
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
Warto zwrócić uwagę na kilka szczegółów dotyczących tych plików i folderów:
- /blog: Zawiera wszystkie pliki powiązane z Twoim blogiem.
- /dokumenty: Zawiera wszystkie pliki powiązane z Twoimi dokumentami. Możesz dostosować ich kolejność w pasek boczny.js plik.
- /źródło: Zawiera wszystkie pliki niebędące dokumentacją, takie jak strony lub komponenty niestandardowe.
- /źródło/strony: Wszystkie pliki JSX/TSX/MDX zostaną przekształcone w strony.
- /statyczny: Pliki statyczne, które zostaną skopiowane do folderu ostatecznej kompilacji.
- docusaurus.config.js: Plik konfiguracyjny Docusaurus.
- zapakowany.json: Każda strona Docusaurus jest aplikacją React, dlatego znajdziesz tutaj wszystkie zależności i skrypty, z których korzysta w przypadku React.
- pasek boczny.js: Tutaj możesz określić kolejność dokumentów na pasku bocznym.
Dostosowywanie instalacji Docusaurus
Jak widać z prostoty struktury plików, Docusaurus jest łatwy w użyciu i nawigacji. Podobnie, dostosowywanie witryny Docusaurus jest dziecinnie proste. Możesz otwierać i edytować te pliki za pomocą swojego ulubionego edytora tekstu lub IDE.
Przyjrzyjmy się teraz niektórym opcjom personalizacji, z których będziesz miał dostęp zaraz po wyjęciu z pudełka.
Strona główna
Pierwszą rzeczą, którą prawdopodobnie będziesz chciał zrobić, jest dostosowanie domyślnej strony głównej, aby zamiast tego wyświetlać własny projekt. Na szczęście nie jest skomplikowane wprowadzanie jakichkolwiek zmian na stronie głównej Docusaurus.
Aby zmienić stronę główną, otwórz źródło/pages/index.js plik i wprowadzaj zmiany bezpośrednio tam. To typowa strona React, więc możesz ją zmienić lub przebudować, zmieniając zawartość lub tworząc niestandardowe komponenty React.
Plik konfiguracyjny
Następnie przejdziemy do kwestii kluczowych docusaurus.config.js plik i zmień kilka ważnych szczegółów dla naszego wystąpienia.
Nazwa i opis
W pliku konfiguracyjnym znajdziesz:
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',
Wystarczy zmienić te szczegóły zgodnie z potrzebami Twojej witryny, a następnie zapisać plik.
Pasek nawigacyjny
Aby edytować pasek nawigacyjny, znajdź element paska nawigacyjnego.
W naszym przykładzie chcemy dodać link do Kinsta, zmienić nazwę elementu „Tutorial” na „Starter documentation” i dodać logo Kinsta.
Oto jak to zrobimy:
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',
},
],
},
Stopka
Dostosowywanie stopki w Docusaurusie składa się z dwóch sekcji: samej treści stopki i linków stopki.
Zawartość stopki
Główną część zawartości stopki (bez listy linków) można umieścić w themeConfig.footer plik. To idealne miejsce, aby dodać logo i informację o prawach autorskich.
Oto jak zmodyfikowaliśmy konfigurację stopki:
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.`,
},
},
};
Linki stopki
Zmiana linków stopki jest podobna do zmiany górnego paska nawigacyjnego: Znajdź sekcję stopki w docusaurus.config.js i edytuj, aż dostosujesz do swoich potrzeb.
Oto jak zmieniliśmy wygląd naszej stopki:
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/',
},
],
},
],
};
Kolory i CSS
Klasyczny preset dla Docusaurus wykorzystuje framework Infima CSS. Mając to na uwadze, twórcy Docusaurus stworzyli bardzo przydatne narzędzie internetowe aby pomóc Ci zmienić kolory i inne elementy CSS oraz deklaracje.
Po wprowadzeniu preferencji na stronie narzędzie wygeneruje niestandardowy.css plik — w komplecie z pięknym zestawem uzupełniających się tonów — w ciągu kilku sekund. Następnie możesz skopiować ten nowy plik CSS do swojego projektu /źródło/css katalog w celach informacyjnych.
Dokumentacja
Cała dokumentacja na Twojej nowej stronie internetowej jest przechowywana w /dokumenty folder. Oczywiście, możesz zmienić nazwę folderu w docusaurus.config.js.
Po prostu utwórz pliki markdown w edytorze tekstu lub HTML i upuść je w tym folderze. Każdy plik powinien wyglądać tak:
--- id: the-id title: Title --- # Rest of the document
Na podstawie identyfikatora Docusaurus tworzy adresy URL artykułów w tym podfolderze: twojadomena.com/docs/{id}
Możemy również tworzyć podfoldery, jeśli chcemy podzielić naszą dokumentację na różne, logiczne sekcje. Jednak będziemy musieli wykonać trochę dodatkowej pracy, aby te podkatalogi działały tak, jak byśmy tego oczekiwali.
Załóżmy, że utworzymy nowy folder dokumentów o nazwie Przystawki. Gdybyśmy odświeżyli stronę główną i kliknęli na nowy link „Starters” automatycznie dodany do naszego paska bocznego, otrzymalibyśmy błąd — ponieważ w naszym nowym folderze nie ma jeszcze strony indeksu.
Najłatwiejszym sposobem rozwiązania tego problemu jest utworzenie _kategoria_.json plik, który wygeneruje indeks wszystkich stron, które są przechowywane w tym folderze. Musisz tylko dodać następujący kod:
{
"label": "Starters",
"position": 2,
"link": {
"type": "generated-index",
"description": "All Kinsta Starters"
},
};
Jak widać, pasek boczny regeneruje się, aby dopasować strukturę plików. Dzieje się tak, ponieważ pasek boczny.js plik zawiera ten samouczekPasek boczny: [{type: ‘autogenerated’, dirName: ‘.’}],
Jeśli wolisz zająć się tym samodzielnie, możesz po prostu zmienić to na coś takiego:
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
Blog
Docusaurus zawiera sprytny moduł bloga. Posiadanie bloga obok głównej witryny może być bardzo przydatne do informowania użytkowników o zmianach zachodzących w projekcie lub do prowadzenia notatek projektowych jako rodzaju dziennika zmian.
Każdy post składa się z części wstępnej, takiej jak ta:
--- slug: docusaurus-starter title: Docusaurus Starter authors: palmiak tags: [starters, docusaurus] ---
…i oczywiście sama treść. Ma również bardzo przydatny tag, który pomaga ograniczyć podsumowanie posta wyświetlane na wszystkich listach postów.
Świetnym pomysłem jest również stworzenie autorzy.yml plik dla kredytów. Plik wygląda tak:
palmiak: name: Maciek Palmowski title: DevRel url: https://github.com/palmiak image_url: https://github.com/palmiak.png
Dzięki temu plikowi wszystkie dane autora będą zgromadzone w jednym miejscu, umożliwiając łatwy dostęp.
Jak wdrożyć swoją witrynę Docusaurus w Kinsta
Oprócz witryn WordPress, samodzielnych aplikacji i baz danych, Kinsta może hostować również witryny statyczne.
Oznacza to, że doskonale nadaje się do obsługi witryn Docusaurus — a także do zarządzania wszystkimi projektami internetowymi — bezpośrednio z pulpitu MyKinsta.
Najpierw prześlij swój kod do preferowanego dostawcy Git (Bitbucket, GitHub lub GitLab), a następnie wykonaj poniższe kroki, aby wdrożyć swoją statyczną witrynę w Kinsta:
-
- Zaloguj się lub utwórz konto, aby wyświetlić panel MyKinsta.
- Autoryzuj Kinsta u swojego dostawcy Git.
- Trzask Witryny statyczne na pasku bocznym po lewej stronie, a następnie kliknij Dodaj witrynę.
- Wybierz repozytorium i gałąź, z której chcesz dokonać wdrożenia.
- Nadaj swojej witrynie unikalną nazwę.
- Dodaj ustawienia kompilacji w następującym formacie:
- Polecenie kompilacji: npm uruchom kompilację
- Wersja węzła: 18.16.0
- Publikuj katalog: zbudować
- Na koniec kliknij Utwórz witrynę.
Jeśli udało Ci się dotrzeć aż tutaj bez błędów, gratulujemy — pomyślnie wdrożyłeś swoją witrynę Docusaurus za pośrednictwem Kinsta!
Oto pierwsze spojrzenie na naszą przykładową stronę na Kinsta:
Jako alternatywę dla hostingu statycznej witryny możesz zdecydować się na wdrożenie swojej witryny statycznej za pomocą hostingu aplikacji Kinsta, który zapewnia większą elastyczność hostingu, szerszy zakres korzyści i dostęp do bardziej zaawansowanych funkcji. Na przykład skalowalność, dostosowane wdrożenie za pomocą pliku Dockerfile i kompleksową analizę obejmującą dane w czasie rzeczywistym i historyczne.
Streszczenie
Biorąc pod uwagę zaskakująco zaawansowane funkcje, przyjazny interfejs, intuicyjną nawigację i skupienie się na treści, nietrudno zrozumieć, dlaczego Docusaurus jest uważany za doskonałe narzędzie dla każdego programisty, który chce z łatwością wdrożyć i utrzymywać usprawnioną, dobrze zorganizowaną statyczną witrynę z dokumentacją i/lub bloga.
Gdy wypełnisz swoją witrynę treścią, którą Twoi goście docenią, zaczniesz zauważać dodatkowe wbudowane funkcje, które okazują się przydatne. Na przykład możliwości optymalizacji wyszukiwarki Docusaurus są idealne, aby pomóc Ci uzyskać lepszą widoczność wśród szerszej publiczności, podczas gdy pracujesz nad innymi technikami awansu w rankingach SEO.
Czy zbudowałeś coś z Docusaurus? Podziel się swoimi projektami i doświadczeniami w sekcji komentarzy poniżej.
Uzyskaj wszystkie swoje aplikacje, bazy danych i witryny WordPress online i pod jednym dachem. Nasza pełna funkcji, wydajna platforma w chmurze obejmuje:
- Łatwa konfiguracja i zarządzanie w panelu MyKinsta
- Wsparcie ekspertów 24/7
- Najlepszy sprzęt i sieć Google Cloud Platform, oparte na Kubernetes dla maksymalnej skalowalności
- Integracja Cloudflare na poziomie korporacyjnym zapewniająca szybkość i bezpieczeństwo
- Globalny zasięg odbiorców dzięki nawet 37 centrom danych i 260 punktom obecności na całym świecie
Zacznij od bezpłatnego okresu próbnego naszego hostingu aplikacji lub hostingu baz danych. Zapoznaj się z naszymi planami lub porozmawiaj z działem sprzedaży, aby znaleźć najlepsze rozwiązanie.
Maciek Palmowski
Maciek jest web developerem pracującym w Kinsta jako Development Advocate Analyst. Po godzinach spędza większość czasu na kodowaniu, próbach znalezienia interesujących wiadomości do swoich newsletterów lub piciu kawy.
