Docusaurus サイトの作成とカスタマイズ (ブログ機能あり)

公開: 2023-02-17

軽量の Web サイト、アプリケーション、およびその他の小さなプロジェクトの場合、WordPress やその他のコンテンツ管理システム (CMS) よりも静的サイト ジェネレーターを使用する開発者が増えています。 静的サイトは、高速で安全で保守が容易な Web サイトとアプリケーションを作成するためのシンプルで効果的な方法を提供します。

Docusaurus はそのような静的サイト ジェネレーターの 1 つであり、開発コミュニティで急速に人気が高まっています。 遅いコンテンツ管理システムにうんざりしていませんか? ドクサウルスに会いましょう！ 速度を落とさずに仕事を終わらせる静的サイト ジェネレーター。 続きを読んで詳細を確認するクリックしてツイートする

この投稿では、Docsaurs を静的サイト ジェネレーターとして使用する利点と、開発者の間で人気が高まっている理由について詳しく説明します。

ドクサウルスとは？

Docusaurus は人気のある静的サイト ジェネレーターで、トップクラスの JavaScript ライブラリの 1 つである React をページ作成用の UI ライブラリとして使用します。 他のそのようなジェネレーターと同様に、セットアップと変更が簡単で、最も重要なことに、静的 Web サイトの実行を開始するために必要なすべてを提供します。

ただし、Docusaurus を際立たせているのは、コンテンツが重要な役割を果たすWeb サイトの作成と管理を支援することです。 ブログ機能を備えた完全な Web サイトをすばやく簡単に構築して、最初からコンテンツにスポットライトを当てることができます。

Docusaurus はコンテンツに重点を置いているため、Wiki などのドキュメント サイトを作成するのに最適です。 また、コラボレーションと git リポジトリへの保存の両方に理想的なマークダウンも利用しています。 さらに、i18n、検索、カスタム テーマなど、すばらしい機能がたくさんあります。これらについては後で詳しく説明します。

Docusaurus を確実なオプションにする優れた機能のほんの一部を次に示します。

  • Reactを使用して構築
  • MDX v1 のサポート
  • Markdown による React コンポーネントの埋め込みのサポート
  • ドキュメントのバージョン管理
  • Git、Crowdin、およびその他の翻訳マネージャーとの互換性があり、ドキュメントの翻訳および一括または個別の展開が可能

Docusaurus を使用するのは誰ですか?

Docusaurus は Facebook によって作成されたため、現在 Web 上の多くの大手ブランドや企業で使用されていることは驚くことではありません。

以下は、現在 Docusaurus を使用している最大のブランドのほんの一部です (Docusaurus の人気が高まり続けているため、すぐにさらに多くのブランドが登場します)。

  • Algolia DocSearch
  • 冗談
  • リアクトネイティブ
  • スーパーベース

そして、毎日、より多くの仲間が仲間入りしています。

Docusaurus のインストール方法

Docusaurus のインストールは非常に簡単で、数分しかかかりません。 このチュートリアルでは、ブログを含むドキュメント サイトを構築し、Web サイトの外観をカスタマイズします。

そして、ここが最もクールな部分です。すべてをスピンアップするのに 1 時間もかかりません。

飛び込みましょう！

要件

Docusarus には Node.js 16.14 以降が必要です。 これはフラットファイル SSG であるため、追加のデータベースは必要ありません。

Node.js 16.14+ をまだ利用できない場合は、Node.js をインストールするか、現在のバージョンをアップグレードすることから始める必要があります。 その後、以下の Docusaurus のインストール プロセスに進むことができます。

また、この GitHub リポジトリのサンプル Docusaurus サイトも使用します。 このチュートリアルでは、それを使用するか、Docusaurus のクリーン インストールを使用できます。

インストールプロセス

Docusaurus のインストール プロセスを開始するには、まず次のコマンドを実行する必要があります。

 npx [email protected] classic

これにより、プロジェクト用のフォルダーが作成され、その中にクラシック テーマがスキャフォールディングされます。 クラシック テーマには、ブログ、カスタム ページ、CSS フレームワークなどの事前構成済みの機能がいくつか含まれています。

インストール後、次のコマンドを実行してローカル サーバーを起動する必要があります。

 npm start

デプロイの準備ができている最適化されたバージョンをビルドする場合は、代わりにこれを実行する必要があります。

 npm run build

構造

Docusaurus インスタンスをインストールしたら、プロジェクト ディレクトリを開いて、新しいサイトの「スケルトン」を詳しく調べることができます。

ファイル構造は次のようになります。

 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

これらのファイルとフォルダーのいくつかについて、注意すべき点がいくつかあります。

  • /blog :ブログに関連するすべてのファイルが含まれます。
  • /docs :ドキュメントに関連するすべてのファイルが含まれます。 sidebar.jsファイルで順序をカスタマイズできます。
  • /src :ページやカスタム コンポーネントなど、ドキュメント以外のすべてのファイルが含まれます。
  • /src/pages :すべての JSX/TSX/MDX ファイルがページに変換されます。
  • /static :最終ビルド フォルダーにコピーされる静的ファイル。
  • docusaurus.config.js : Docusaurus 構成ファイル。
  • packaged.json :各 Docusaurus サイトは React アプリであるため、React に使用するすべての依存関係とスクリプトがここにあります。
  • sidebar.js :ここでは、サイドバー内のドキュメントの順序を指定できます。

Docusaurus インストールのカスタマイズ

ファイル構造が単純であることからわかるように、Docsaurus は使いやすく、操作も簡単です。 同様に、Docsaurus サイトのカスタマイズも簡単です。 これらのファイルは、お気に入りのテキスト エディターまたは IDE を使用して開いて編集できます。

箱から出してすぐに使えるカスタマイズオプションのいくつかを見てみましょう.

ホームページ

おそらく最初にやりたくてうずうずすることは、代わりに独自のプロジェクトを表示するようにデフォルトのホームページをカスタマイズすることです。 幸いなことに、Docsaurus ホームページに必要な変更を加えるのは複雑ではありません。

ホームページを変更するには、 src/pages/index.jsファイルを開き、そこで調整を行います。 これは典型的な React ページであるため、コンテンツを変更したり、カスタム React コンポーネントを作成したりして、変更または再構築できます。

構成ファイル

次に、重要なdocusaurus.config.jsファイルに飛び込み、インスタンスの重要な詳細を変更します。

名前と説明

構成ファイルには、次のものがあります。

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

これらの詳細をサイトのニーズに合わせて変更し、ファイルを保存してください。

ナビゲーションバー

ナビゲーション バーを編集するには、 navbarアイテムを見つけます。

ここでの例では、Kinsta へのリンクを追加し、「チュートリアル」アイテムの名前を「スターター ドキュメント」に変更し、Kinsta ロゴを追加します。

方法は次のとおりです。

 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', }, ], },

フッター

Docusaurus でのフッターのカスタマイズは、フッター コンテンツ自体とフッター リンクの 2 つのセクションで構成されます。

フッターの内容

フッター コンテンツの大部分 (リンク リストを除く) は、 themeConfig.footerファイルに配置できます。 これは、ロゴと著作権表示を追加するのに理想的な場所です。

フッター構成を変更した方法は次のとおりです。

 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.`, }, }, };
フッターリンク

フッター リンクの変更は、トップ ナビゲーション バーの変更と似ています。docusaurus.config.jsでfooterセクションを見つけて、必要に応じて編集します。

footerセクションを次のように変更しました。

 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/', }, ], }, ], };

色とCSS

Docusaurus のクラシック プリセットは、Infima CSS フレームワークを使用します。 これを念頭に置いて、Docusaurus の作成者は、色やその他の CSS 要素と宣言を変更するのに役立つ非常に便利な Web ツールを作成しました。

ページに設定を入力すると、ツールは数秒でcustom.cssファイルを生成します。 次に、この新しい CSS ファイルを参照用にプロジェクトの/src/cssディレクトリにコピーできます。

Docusaurus のカスタム CSS ツール。
Docusaurus 公式ドキュメントの一部。Docusaurus デザインの個々の要素の 16 進コード調整を入力するフィールドを備えたカスタム CSS ツールを示しています。

ドキュメンテーション

新しい Web サイトのすべてのドキュメントは、/docsフォルダーに保存されます。 もちろん、 docusaurus.config.jsでフォルダー名を変更できます。

テキスト エディターまたは HTML エディターでマークダウン ファイルを作成し、そのフォルダーにドロップするだけです。 各ファイルは次のようになります。

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

ID に基づいて、Docsaurus はそのサブフォルダー内の記事の URL を構築します: yourdomain.com/docs/{id}

ドキュメントを異なる論理的なセクションに分割したい場合は、サブフォルダーを作成することもできます。 ただし、これらのサブディレクトリが期待どおりに機能するには、少し追加の作業を行う必要があります。

「スターター」という名前の新しいドキュメント フォルダーを作成するとします。 次にホームページを更新して、サイドバーに自動的に追加された新しい「スターター」リンクをクリックすると、エラーが発生します — 新しいフォルダーにはまだインデックス ページがないためです。

これを修正する最も簡単な方法は、このフォルダーに保存されているすべてのページのインデックスを生成する_category_.jsonファイルを作成することです。 次のコードを追加するだけです。

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

ご覧のとおり、サイドバーはファイルの構造に合わせて再生成されます。 これは、 sidebar.jsファイルにこのtutorialSidebar : [{type: 'autogenerated', dirName: '.'}],

これを自分で処理したい場合は、これを次のように変更できます。

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

ブログ

Docusaurus には洗練されたブログ モジュールが含まれています。 メインの Web サイトの横にブログを配置すると、プロジェクトで発生した変更をユーザー ベースに通知したり、変更ログの形式としてプロジェクト ノートを実行し続けるのに非常に役立ちます。

各投稿は、次のような frontmatter 部分で構成されます。

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

…そしてもちろん、コンテンツそのもの。 また、非常に便利な<!--truncate-->タグもあり、すべての投稿リストに表示される投稿の概要を制限するのに役立ちます。

また、クレジット用のauthors.ymlファイルを作成することもお勧めします。 ファイルは次のようになります。

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

このファイルのおかげで、著者のすべてのデータを 1 か所にまとめて簡単に参照できます。

Kinsta で Docusaurus ウェブサイトを展開する方法

WordPress サイト、スタンドアロン アプリケーション、およびデータベースに加えて、Kinsta は静的な Web サイトをホストできます。

これは、MyKinsta ダッシュボードから直接 Docusaurs サイトやすべての Web プロジェクトを管理するのに最適であることを意味します。

アプリケーションがデプロイされると、次のような測定値を使用して、ライブおよび履歴の両方でアプリケーションの進行中の分析を確認できます。

  • 帯域幅の使用
  • ビルド時間
  • 実行時間
  • CPU使用率
  • メモリ使用量

最初から最後まで、MyKinsta による展開プロセスは数分しかかかりません。

始めましょう！

前提条件: Docusaurus プロジェクトの構成

Kinsta のアプリケーション ホスティング プラットフォームで Docusaurus プロジェクトをホストするには、次のことを行う必要があります。

  1. package.jsonファイルに name フィールドを含めます。 (これは何でも構いませんが、展開には影響しません。)
  2. package.jsonファイルにビルド スクリプトを含めます。 (Docusaurus プロジェクトには既にこれが含まれているはずです。)
  3. serve npm パッケージをインストールし、start スクリプトを serve build に設定します。

それらがチェックされたら、実際のサイトの展開に進むことができます.

Docusaurus プロジェクトのデプロイ

次の簡単な手順に従って、GitHub アカウントに接続し、Docusaurus サイトを起動します。

  1. MyKinsta アカウントにログインし、左側のメニューから[アプリケーション]タブに移動します。
  2. 青い[サービスの追加]ボタンをクリックし、ドロップダウンから[アプリケーション]を選択します。

    MyKinstaの「サービスを追加」の下にある「アプリケーション」を選択します。
    青色の「サービスを追加」ボタンをクリックした後、「アプリケーション」オプションの上にマウスを置いたMyKinstaダッシュボードの「アプリケーション」タブ。

  3. MyKinsta から GitHub アカウントにまだ接続していない場合は、接続を促すモーダルが表示されます。 [GitHub で続行]ボタンをクリックして続行します。

    MyKinsta と GitHub の統合。
    「GitHub 統合: ここで kinsta を GitHub 名前空間に接続して、既存のリポジトリをインポートします。」というテキストを含むモーダル。 右下には白い「キャンセル」ボタンと青い「GitHub で続行」ボタンがあります。

  4. 新しいウィンドウが開き、Kinsta に GitHub リソースへのアクセスと管理を許可する許可を求めます。 正しい GitHub アカウントにサインインしていることを確認してから、下部にある緑色の[Kinsta を承認]ボタンをクリックします。

    GitHub での Kinsta の承認。
    「Kinsta by Kinstaが次の許可を求めています: GitHub ID (kinstauser) を確認します。 アクセスできるリソースを把握します。 下部に灰色の「キャンセル」ボタンと緑色の「Kinstaを承認」ボタンの両方があります。

  5. これで、GitHub 統合ウィザードが表示されました。 これは、サイトを展開する前の最後の手順です。 提示されたフィールドを慎重に検討し、GitHub 構成とプロジェクトの要件に従って入力してください。 リポジトリに Dockerfile がある場合は、これを使用してコンテナー イメージをセットアップできます。 それ以外の場合、Kinsta はコンテナ イメージを自動的に設定します。 特にこれがKinstaを介した最初の展開である場合は、先に進む前にGitHubのアクセス許可を編集する必要がある場合があることに注意してください.
    GitHub のアクセス許可を編集します。
    「GitHub リポジトリ」フィールドの「GitHub アクセス許可の編集」ドロップダウン オプションの上にマウスの手を置いている MyKinsta の新しいアプリケーション ウィザード。

    Kinstaにすべてのリポジトリへのアクセスを許可するか、特定のリポジトリのみへのアクセスを許可するかを選択できます。 これらのアクセス許可は、GitHub アカウントのアプリケーション設定からいつでも調整できます。

    Kinstaに付与するGitHub権限の選択。
    GitHub の「アクセス許可」セクション。「リポジトリ アクセス」セクションに「すべてのリポジトリ」または「選択したリポジトリのみ」という 2 つのオプションが表示されています。

  6. 選択を行って選択内容を確認すると、デプロイの詳細と、 [設定を変更] または[再デプロイ]のオプションが表示されます。
    MyKinsta を介したアプリケーションのデプロイの成功。
    MyKinstaの「デプロイの詳細」ページには、デプロイされたブランチ名、コミット番号、付随するコミットメッセージ、デプロイ時間、選択されたデータセンターの場所など、デプロイされたアプリに関する情報が表示されます。

    ここには、展開中に発生したエラーと、失敗の原因に関する詳細も表示されるため、簡単に対処できます。 問題の修正に苦労している場合は、ロールアウト エラーに関する追加のガイダンスが Kinsta のドキュメントに記載されています。

    詳細を含む「ビルド プロセスに失敗しました」エラー。
    失敗の原因となった個々のエラーを一覧表示する詳細ペインの上に、「ビルド プロセスが失敗しました」というタイトルのエラーと「不明なビルド失敗の種類」が表示されます。

ここまでエラーが発生しなかった場合は、おめでとうございます。Kinsta を介して Docusaurus サイトを正常に展開したことになります。 ウィザードを完了するとすぐに、アプリケーション (つまり、静的サイト) が利用可能になります。 アプリケーションの URL (通常はhttps:// your-docusaurus-site .kinsta.appで表示できます。

Kinstaのサンプルサイトの最初の外観は次のとおりです。

デプロイされた Docusaurus サイト。
展開された Docusaurus のホームページ。その上部には、「My Site」という見出しと「Dinosaurs are cool」というキャッチフレーズが白いテキストで書かれた緑色のバナーがあります。

まとめ

驚くほど強力な機能、使いやすいデザイン、直感的なナビゲーション、コンテンツへのフォーカスを備えた Docusaurus が、合理化され、よく整理された静的ドキュメント サイトや/またはその両方を簡単にデプロイおよび維持しようとしている開発者にとって優れたツールと見なされる理由を理解するのは難しくありません。ブログ。 Web 開発ゲームを切り替えましょう! 不格好な CMS に別れを告げ、開発ゲームを変えつつあるシンプルな静的サイト ジェネレーターである Docusaurus にようこそ。 ここでチェックしてください️ クリックしてツイートします

訪問者が評価するコンテンツでサイトを埋め尽くすと、便利な追加の組み込み機能に注目し始めます。 たとえば、Docsaurus の検索エンジン最適化機能は、SEO ランキングを上げるための他の手法に取り組んでいる間、より多くのオーディエンスからの可視性を向上させるのに最適です。

Docusaurus で何かを構築しましたか? 以下のコメントセクションで、あなたのプロジェクトと経験を私たちと共有してください。