Docusaurus 設定方法 Site Metadata
Site metadata
上記に詳しい説明がありますが、以下の設定が必須のようです。
title
文字列で設定、WEBサイトとして設定した場合のタイトル、HTMLのヘッダー<head>: 文書メタデータ (ヘッダー) 要素の<title>に設定される。
さらに、useDocusaurusContext()でReact内部にも持ち込める。
設定例
module.exports = { title: 'おれおれサイト', };
サイトヘッダー
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="generator" content="Docusaurus"> <title>おれおれサイト</title> <link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="おれおれサイト Blog RSS Feed"> <link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="おれおれサイト Blog Atom Feed"> <script defer src="/runtime~main.js"></script><script defer src="/main.js"></script><link href="/styles.css" rel="stylesheet"> </head>};
JSX
function HomepageHeader() { const {siteConfig} = useDocusaurusContext(); return ( <header className={clsx('hero hero--primary', styles.heroBanner)}> <div className="container"> <h1 className="hero__title">{siteConfig.title}</h1> </div> </header> ); }
url
文字列で設定、WEBサイトとして設定した場合のトップレベルとなるホスト名、
たとえはhttps://facebook.github.io とかhttps://facebook.github.io/metro/ とかの場合、青色の部分を設定
設定例
module.exports = { url: 'https://docusaurus.io', };
baseUrl
文字列で設定、WEBサイトとして設定した場合のホスト名+パスとなる部分
たとえはhttps://facebook.github.ioの場合は / を設定
https://facebook.github.io/metro/ とかの場合、濃い青色の部分を設定 metro/
決まりとして最後はスラッシュ/で終えなければいけないようです。
設定例
module.exports = { baseUrl: '/', };
module.exports = { baseUrl: 'metro/', };
Docusaurus 設定方法および設定ファイル
Docusaurusのフォルダー構成が判明したところで、今度はDocusaurusの各種設定がどうなっているのか覗いてみましょう。
シンプルなことに設定ファイルはプロジェクトフォルダーのルートにある「docusaurus.config.js」のみのようです。
このファイルを変更するといろいろ設定が変化するようです。
公式ページをみてみると以下の構成要素があるようです。
Site metadata
Deployment configurations
Theme, plugin, and preset configurations
Custom configurations
一つずつ見てみましょう。
Docusaurus 雛形の構造を見てみましょう
雛形ができあがって無事にWEBサイトが立ち上がったところで、スターターが作成したソースコードを眺めてみましょう。
公式サイトをみると以下のような説明があります。（かなりの要約なので注意、詳しくは本家サイトを参照してくだい）
/blog/ - ここにMarkdownファイルを作成するとブログになります。
/docs/ - ここにMarkdownファイルを作成するとドキュメントになります。
/src/ - ここにMarkdownファイルをおいてはいけません。ページや、カスタムReactコンポーネントなどが配置されます。
* /static/ - 写真とかPDFとかを置く場所です、ビルドされたフォルダーの直下に配置されます。
Docusaurus 最初の一歩 Get Started 雛形起動
環境準備ができたら、ようやく「Get Started」です。
前回までに作成した作業用フォルダー「Work」に移動して、「docusaurus.code-workspace」をダブルクリックし、VsCodeを立ち上げてみてください。
ターミナルウインドウが開いている場合はそのウインドウをカーソルでクリックしてアクティブにしてコマンドが入力できるようにします。
ターミナルウインドウがない場合は「Terminal」-> 「New Terminal」と選択すると、画面の下部分にターミナルウインドウが表示されます。
ターミナルウインドウ内で以下のコマンドを入力します。
npx @docusaurus/init@latest init my-website classic
「my-website」の部分は好きな名前にしてもらっても構いません（たとえば ore-ore-site とか ）。今回はチュートリアル通りmy-websiteで作成してみます。
エンターキーを押したあとはしばらく時間がかかりますが、終了するとWorkフォルダー以下は次のようなフォルダー、ファイル構成になっていると思います。
docusaurus.code-workspace my-website ├── blog │ ├── 2019-05-28-hola.md │ ├── 2019-05-29-hello-world.md │ └── 2020-05-30-welcome.md ├── docs │ ├── tutorial-basics │ ├── tutorial-extras │ └── intro.md │ ├── src │ ├── css │ │ └── custom.css │ └── pages │ ├── styles.module.css │ └── index.js ├── static │ └── img ├── docusaurus.config.js ├── package.json ├── README.md ├── sidebars.js └── yarn.lock
各フォルダーの説明はのちほど行うとして、
「my-website」フォルダーにDocusaurusのサイトジェネレータが作成されたので以下のコマンドでジェネレータが作動し
雛形となるWEBサイトが表示されます。
cd my-website && npm run start
ようやくたどり着きました。
Docusaurus 最初の一歩 Get Started まずは環境整備②
必要なアプリケーションがインストールできたら、次は「Get Started」するための土台を作成します。
1. 作業用フォルダーを作成する。
2. VsCodeを起動してTerminalをGit Bashにする。
3. VsCodeを起動するためのcode-workspaceファイルを作成する。
4. VsCodeでTerminalを起動するとデフォルトではPowerShellになるのでデフォルトをGit Bashにする。
以上です。 詳しく見てみましょう。
1. 作業用フォルダーを作成する。
これは簡単ですね、今回はCドライブ直下に「Work」という名前のフォルダーを作成してみます。
もちろん好きな場所に好きな名前でフォルダーを作成しても構いません。
作り方を解説するまでもないので次に進みます。
2. VsCodeを起動してTerminalをGit Bashにする。
作成されたWorkフォルダーをマウスで右クリック、「Codeで開く」を選択。するとWorkフォルダーをワークスペースとした Vs Codeの画面が開きます。
次にメニューバーの「Terminal」-> 「New Terminal」と選択すると、画面の下部分にターミナルウインドウが表示されます。
デフォルトではターミナルの種類はPowerShellになっているのでこれをGitBashに変更します。
ターミナルウインドウの上部メニューの下矢印「V」をクリックすると「GitBash」がリストにでてきますのでこれを選択します。
3.VsCodeを起動するためのcode-workspaceファイルを作成する。
次に毎回この手順を行うのは効率が悪いのでターミナルウインドウを開くとデフォルトでGitBashにするようにVsCodeのワークスペース（この場合Workフォルダ）にワークスペース用の設定ファイルを作成し、ターミナルはデフォルトでGitBashになるように設定します。 GitBashのターミナルウインドウに以下のコマンドを入力してVsCodeのワークスペースに設定ファイルを作成します。
touch docusaurus.code-workspace
「.code-workspace」の前の名前は便宜上docusaurusとしていますが、なんでも構いません。
ファイル名の末尾が「.code-workspace」であることが重要です。
すると「docusaurus.code-workspace」ファイルが左側のエクスプローラーに表示されます。
4. VsCodeでTerminalを起動するとデフォルトではPowerShellになるのでデフォルトをGit Bashにする。
次に「docusaurus.code-workspace」ファイル名をクリックして、以下のコードをコピペして保存します。
{ "folders": [ { "path": "." } ], "settings": { // ターミナル設定 "terminal.integrated.defaultProfile.windows": "Git Bash", "terminal.integrated.profiles.windows": { "Git Bash": { "source": "Git Bash" }, }, } }
これでTerminalウインドウがGitbashになります。
ためしに、VsCodeを終了し、Workフォルダーを開き、「docusaurus.code-workspace」ファイルをダブルクリックしてみてください。
VsCodeが立ち上がりTerminalウインドウを表示するとGitbashになっているはずです。
以降はVsCodeを立ち上げる際、フォルダーを選択して右クリックで「Codeで開く」を選択するのではなく、この作成した設定ファイルをダブルクリックするようにすると設定が反映されたVsCodeが立ち上がります。
また今後もここにいくつかの重要な設定を逐次追加していきます。
Docusaurus 最初の一歩 Get Started まずは環境整備①
前回、Docusaurusの紹介をしたのだけれど、とりあえず動かしてみたいと思う人が多いと思います。（能書きはいいので動くもん見せんかい）
そこで、公式サイトをもとに「Get Started」をやってみたいと思います。
フツーにやるとあまり面白くないのでシステム屋がやりそうなやり方でやってみたいと思います。（ようはオレオレ方式）
もっとも利用されているＯＳ、Windowsのやり方です。
これからソースをいじることになるので、まずはテキストエディターをインストールします。 さすがにメモ帳でソースコードを編集するのはきついので
おすすめのVisual Studio codeを使います。
Visual Studio code
最近のスターターで作成した雛形（スキャフォールド）にはソースのバージョン管理ソフトを使う前提でプロジェクトが作られることが多いので
バージョン管理ソフト、ここではこれまたスタンダードなGitを使います。
このGitをインストールすると同時にWindowsなのにUnixコマンドが使用できるGit Bashがインストールされます。
これによりLinuxやMacOSを利用している人にも使用するコマンドが同じになるので大変便利です。
git
そしてなによりこれがないと動きません、NodeJsです。
NodeJs
上記のソフトを公式URLや他の紹介サイトなどでインストール方法を確認してインストールしておいてください。
(丸投げ感ありあり）
Docusaurusの紹介
WEB系システム開発においてフロントエンドとバックエンドがあるが、現在主流となりえるやり方として
フロントエンドは静的サイトジェネレーター(SSG)、バックエンドはいわゆるRestAPIかGraphQLの採用が多くなってきた。 （バックエンドは言語、エンジン等は特に問わないが、環境によって影響される要素が強い）
じゃあ、いまのフロントエンドってなにがあるのって思ってググってみると以下のサイトが見つかった。
GatsbyJS 現代のWordpress
このなかで利用したことがあるのはNUXTJS,Gatsbyであるが、どちらかとVueよりはReactを使いたいのでNEXTJS、Gatsbyが候補。
NEXTJSは先ほどのサイトを見ると使ったことはないが、SSR(Server Side Rendering) らしく却下、Gatsbyを試してみたけど
GraphQLなどちょっと先取りしすぎな点が難点であり、なにかないかな～と思っていたところ
Docusaurus
docusaurus.io
を見つけた。
Gatsbyと似ているが、ドキュメント用のWEBサイトに特化しているようである、以下のような特徴があるように書いてある。
Powered by Markdown
Markdownでページを作成できて、その中にJSXも記述できる。
Built Using React
Reactエンジンなので、拡張、カスタマイズが簡単そう。
Ready for Translations
WEBサイトの多言語化も可能。
Document Versioning
ドキュメントのバージョニングが可能。
Content Search
Algoliaによる全文検索が可能。
これならもしかして、WEBサイトやブログはもとより、バックエンドと絡めてWEBシステムも構築可能なのでは？ 早速スターターを動かしてみたら、解らないことだらけ、しかもググってみても日本語のページは少なく まだそんなに注目されていない感じ、なら学習を兼ねてここで使い方なんかを記事にしてもいいかなと思い立った。
