メインコンテンツまでスキップ

技術ブログをはじめました

小倉大地
小倉大地
Engineer

WeCapital 株式会社の技術ブログを開設しました。 1本目のブログとして、本ブログでも利用している Docusaurus でのブログ開設について記します。

Docusaurus の紹介​

ブログ開設には様々な選択肢があります。

  • Qiita, note, Zenn, はてなブログなどのプラットフォームを利用する
  • Wordpress, Movable Typeなどの CMS を利用する
  • Docusaurus, Hugo, MkDocsなどの静的サイトジェネレータを利用する

せっかくなら会社ブランド向上のために自前で用意したい、静的ホスティングでインフラ管理なくかつ無料でデプロイしたい、MDX を使ってみたい、などの理由から今回は Docusaurus を選定しました。 技術ブログですので Markdown かつローカルで開発サーバーを立てることのハードルが低いことも理由になります。

今回はGitHub Pagesを利用してデプロイしていますが、多くのホスティングサービスに対応しておりドキュメントも充実しています。1

Docusaurusのマークダウン​

Docusaurusの公式ドキュメントはかなり充実している印象です。 Docusaurusの設定はdocusaurus.config.tsに書かれますが、この設定についてはDocusaurusのドキュメント自体の設定をみると参考になります。2 他にもDocusaurusを利用しているサイトを参考にするのもよさそうです。機能が非常に多いためいくつかをピックアップして紹介します。

コードブロック​

コードブロックの一例ですが、prismセクションのmagicCommentの設定により、自由に指定行にclassを付与することができます。
MDXファイルとdocusaurus.config.ts、cssの例とその表示例になります。 highlight-startとhighlight-endというコメントで囲った部分をハイライトし、error-next-lineの次の表をエラーのように表現します。

sample.py
def error_function(x, y):
    result = x / y

    return result

def fixed_function(x, y):
    try:
      result = x / y
    except ZeroDivisionError as e:
      print(f"Error: {e}")

    return result
備考

MDXタブにmagicCommentsのコメントの記法をCSSタブにスタイルを記載しています。

Diffも表現することができます。

sample.py
  a = 1
  b = 2
- c = a + d
+ c = a - b

ドキュメント：https://docusaurus.io/docs/markdown-features/code-blocks

タブ​

コードブロックのセクションでも利用していますが、シンクロされたタブを作成することもできます。さらに、URLのクエリパラメータにも状態を付与できます。インストール手順など作成するのに便利です。

choco install nodejs-lts
node -v

記述の仕方は以下の通りです。

<Tabs groupId="current-os" queryString>
  <TabItem value="windows" label="タブのタイトル">
    /* ここに内容 */
  </TabItem>
  <TabItem value="mac" label="タブのタイトル">
    /* ここに内容 */
  </TabItem>
</Tabs>

ドキュメント：https://docusaurus.io/docs/markdown-features/tabs

ライブコードエディタ​

Docusaurusで目立つ機能かと思いますが、ライブコードエディタを利用することができます。テーマを導入するだけで簡単に利用できます。

ライブエディター
function Clock(props) {
  const [count, setCount] = useState(0);

  function handleClick() {
    setCount(count + 1);
  }

  return (
    <div>
      <button onClick={handleClick}>Click me</button>
      <h2>It is {count}</h2>
    </div>
  );
}
結果
Loading...

ドキュメント：https://docusaurus.io/docs/markdown-features/code-blocks#interactive-code-editor

カスタムコンポーネント​

MDXをサポートしているため、JSXを記述してReactコンポーネントを呼び出すことができます。タブもJSXで記述しました。

今回は例としてMUIコンポーネントを利用してReactコンポーネントをMDXで利用してみます。最近追加された@mui/x-chartsのBarChartをサンプルコード色だけ変えてそのまま利用してみます。

自作のコンポーネントも利用できます。例えば、この

もMUIのToolTipです。普通に利用するとずれるためスタイルは調整しています。

custom.css
.MuiSvgIcon-root {
  vertical-align: bottom;
  padding-top: 1px;
  padding-bottom: 4px;
}

SSRではないためサーバーサイドで外部APIのフェッチをしたりDBからデータを取得することはできませんが、クライアントサイドでのAPIフェッチは可能です。 The Cat APIからランダムな猫の画像を取得して表示するReactコンポーネントの例です。

No cat found

その他​

他にもremark, rehypeプラグインも利用でき、最初からかなり多くのプラグインが利用できます。私は利用したことがなかったのですが、注釈も利用できるようです。 他にも有用なプラグインを探すのに便利なリポジトリがあります。3

ブログレイアウトの調整​

DocusaurusのBlogページのレイアウトは、デフォルトで「最近の投稿・コンテンツ・目次」が「3:7:2」で表示されます。ドキュメントと比べて少し幅が狭いので変更しました。いくつかコミュニティで議論がありましたが変更できるようにする変更は見られなく、変更できても複雑だったので簡易的な方法を紹介します。

custom.css
@media screen and (min-width: 1000px) {
  .col--7 {
    --ifm-col-width: calc(8 / 12 * 100%);
  }
  .col--3 {
    --ifm-col-width: calc(2 / 12 * 100%);
  }  
  .col--2 {
    --ifm-col-width: calc(2 / 12 * 100%);
  }
}

さいごに​

Docusaurusは紹介しきれないほどの多くのカスタマイズができ、紹介した他にもMermaid.jsや国際化、SEO対策などもサポートされています。デフォルトの設定でも十分に利用でき、本格的にやるにも多くのカスタマイズができ使いやすいツールだと思います。

WeCapitalではエンジニアを募集しています！！

Footnotes​

  1. https://docusaurus.io/docs/deployment ↩

  2. https://github.com/facebook/docusaurus/blob/main/website/docusaurus.config.ts ↩

  3. 注釈はこのように表示されます。Footnotesの日本語化は変更が公開されておらず一旦諦めました。 ↩