新しいドキュメント

数週間の作業を経て、Formikの新しいドキュメントWebサイトと、新しいドメインhttps://formik.dokyumento.jpをリリースできることを嬉しく思います。

Formikは、FacebookのドキュメントフレームワークDocusaurusの初期ユーザーの1つでした。それは素晴らしい働きをし、限られたスタイリングオプションのおかげで、コンテンツに集中し、見た目にはこだわらないようにすることができました。

とは言え、Docusaurus v1には欠点があります。まず、真に静的なサイトジェネレーターです。純粋なHTMLを出力します。これは多くのライブラリやツールにとって素晴らしいことですが、ReactパッケージであるFormikのようなものにとっては、最新のクライアントサイドJSを実行できないことは不満でした。ページ内プレイグラウンドや編集可能なコードブロックなどは実現不可能でした。

ドキュメントを待望のリフレッシュする時期が来たとき、GatsbyとDocusaurus v2を評価しましたが、最終的にNext.jsを選択することにしました。 getStaticProps、キャッチオールルート、インクレメンタル静的サイト生成などの新機能のおかげで、Formikドキュメントは、今後革新できる強固な基盤を手に入れました。

要約

Formikドキュメントは以下を使用して構築されています

• Next.js 9.4.x + MDX
• Notion （あなたが今読んでいるこのブログ投稿を強化するため）
• Tailwind CSS
• 検索にはAlgolia DocSearch v3 Alphaを使用

この投稿の残りの部分では、Formikのドキュメントスタック、その背後にある根拠、そして興味深いと思われるいくつかの詳細な概要を説明します。

Next.js 9.4

GatsbyやDocusaurus v2などの代替案ではなく、Next.jsを選択した理由はいくつかあります。決定における最大の要因は、ドキュメントは製品の一部であると信じていることです。今後のSaaSダッシュボードとマーケティングサイトの一部はすでにNext.jsを使用しているため、Next.jsの世界にとどまることは、すべてのコードベースがオープンソースのものであっても同じように機能することを意味します。これにより、認知オーバーヘッドが軽減され、アプリケーション間で作業したり、コンポーネントを共有したりすることが容易になります。

なぜGatsbyではないのですか？

Gatsbyは、豊富なプラグインとテーマエコシステムを備えたReactベースの静的サイトジェネレーターです。GraphQLを搭載した単一のデータグラフが主要な価値提案です。ドキュメントサイトに関して言えば、子テーマが継承できるプラグイン、レイアウト、コンポーネントのグループであるGatsbyテーマは非常に便利です。 私たちが取り組んでいるOSSプロジェクトの数が増えていることを考えると、これは非常に魅力的でした。しかし、GraphQLはドキュメントやほとんどの静的なドキュメント主導のWebサイトにとってはまだ過剰であると確信しています。そして、はい、GatsbyでGraphQLを技術的に使用する必要はないことは十分に承知していますが、それは間違いなくGatsbyにとって最適な方法です。

なぜDocusaurus v2ではないのですか？

執筆時点では、Docusaurus v2.0はまだアルファ版です。新しいバージョンでは、クライアントサイドのReact、プラグイン、さらにはカスタムテーマを許可することで、v1.0の多くの問題が修正されています。

私にとってDocusaurus 2の最大の問題は、その基本テーマでした/あります。

多くのプロジェクトにとって、Facebookのドキュメント用の新しい静的CSSフレームワークであるInfima（Docusaurusで使用され、同じチームによって共同開発されています）で問題ありません。しかし、私を本当に悩ませる点がいくつかあります。

モバイルナビゲーションがぎこちない

モバイルでDocusaurus v2のすべてのWebサイトをナビゲートするのに苦労しています。フローティングサブナビゲーションは、Docusaurus v1のサブナビゲーションバーと比較して直観的ではないと思います。比較ビデオをご覧ください。左がv1、右がv2です。

Infima CSSのテーマ設定は簡単ではない

Infima CSSは完全なCSSフレームワークですが、テーマオプションはやや限られています。新しいFormikドキュメントをエンタープライズSaaSアプリのデザインシステムと視覚的に一致させることも、Infima CSSを大幅に曲げたり拡張したりする必要があるため、難しいように思われました。

コミュニティテーマの不足

Docusaurus v2のもう1つの大きな追加は、カスタムテーマと第一級のテーマコンポーネントオーバーライド（別名「Swizzling」）です。聞いたことがない場合は、コンポーネントのスウィズリングは、Wordpressのテーマとプラグインのテンプレート階層と同様に機能しますが、Reactコンポーネント用です。 docusaurus swizzle <theme name> [component name] を実行すると、Docusaurusは指定されたテーマのコンポーネントを node_modules から src/theme/[component name] のローカルファイルにコピーします。その後、そのファイルに必要なすべての変更を加えることができ、Docusaurusはサイトを構築するときに、ベースのバージョンではなく「スウィズル」されたバージョンを使用します。

スウィズリングの大きな欠点は、Wordpressの子テーマを永遠に悩ませるものと同じです。アップグレードをはるかに複雑にする可能性があります（特に基本テーマに新しい機能が追加された場合）。この問題は非常に顕著であるため、Docusaurusドキュメントは現在、v2がベータ版に達するまでスウィズリングを推奨していません

少なくともベータ版に達するまでは、コンポーネントのスウィズリングを推奨しません。コンポーネントAPIは急速に変化しており、ベータ版に達するまで変化し続ける可能性があります。将来の潜在的な問題を回避するために、可能な限りデフォルトの外観に固執してください。

この時点で、Formik用のカスタムDocusaurus v2テーマを作成するのにかかる労力を評価するのに少し時間を費やしましたが、上記の警告のために最終的に却下することにしました。私の考えは、そのウサギの穴に飛び込むつもりなら、Next.jsを使用してMarkdown処理パイプライン全体を完全に制御した方がよいということでした。そして、それはまさに私がしたことでした...

MDX FTW

少しの努力で、Next.jsはドキュメントに最適です。MDXが秘訣です。ただし、Docusaurusと同等の機能を実現するには、かなりの労力が必要であり、気 faint な人向けではありません。とは言うものの、新しいドキュメントの仕組み、ドキュメントへの貢献の容易さ、そしてサイトの見栄えに非常に満足しています。

Formikの新しいドキュメントは、ほとんどのNext.jsサイトとは少し異なる方法でMDXを処理することに注意してください。公式の @next/mdx プラグインを使用する代わりに、Brent VatneのカスタムwebpackローダーをExpo.ioドキュメントから厚かましく盗みました。これは、すべての.mdxファイルでフロントマターを自動的に抽出し、ラッパーレイアウトコンポーネントエクスポートを挿入します。

1 const fm = require('gray-matter');
2 
3 // Makes mdx in next.js much better by injecting necessary exports so that
4 // the docs are still readable on github
5 // (Shamelessly stolen from Expo.io docs)
6 // @see https://github.com/expo/expo/blob/master/docs/common/md-loader.js
7 module.exports = async function (src) {
8   const callback = this.async();
9   const { content, data } = fm(src);
10   const layout = data.layout || 'Docs';
11   const code =
12     `import { Layout${layout} } from 'components/Layout${layout}';
13 export const meta = ${JSON.stringify(data)};
14 export default ({ children, ...props }) => (
15   <Layout${layout} meta={meta} {...props}>{children}</Layout${layout}>
16 );
17 ` + content;
18 
19   return callback(null, code);
20 };

デフォルトでは、このローダーは LayoutDocs.tsx レイアウトコンポーネントをラッパーとして挿入しますが、必要に応じて追加のレイアウトを追加できます。これらは、layoutフロントマターキーを介してページごとに指定できます。

静的サイト生成を備えたNotion搭載ブログ

従来のCMSまたはMDXを使用する代わりに、あなたが今読んでいるこのブログは、実際にはNotionとNext.jsの静的サイト生成機能によって強化されています。投稿をNotion APIのテーブルに関連するメタデータとともに保存し、Notionの文書化されていないAPIを./src/pages/blog/[...slug].tsxのカスタムReactコンポーネントにマッピングします。結果は素晴らしく、素晴らしい執筆体験です。このセットアップのより詳細な例と、すぐにデプロイできる例については、こちらをご覧ください：https://notion-blog.now.sh/

Tailwind

私は何年もAtomic CSSのファンです。 Tailwindは、すべてのアトミックCSSフレームワークの中で最新かつおそらく最高のものです。柔軟性があり、直観的で、見栄えが良く、パフォーマンスの点で他に類がありません（CSSだけなので！）。 Tailwind 1.4.xのおかげで、新しいpurge機能を使用して、すべての無関係なクラスをパージすることもできます。

Algolia DocSearch v3 Alpha

ドキュメント 작업 중에新しいバージョンのdocsearch.jsを偶然発見しましたが、想像以上に優れています。クールなオムニバーがあり、最近の検索やお気に入りを追跡することもできます。

全体的に、新しいドキュメントサイトに非常に満足しています。しばらくの間初めて、ドキュメントを再び書くことに興奮しています。まだかなりの数の機能が欠けていますが、エンドユーザーエクスペリエンスとこのスタックが提供する開発者エクスペリエンスに非常に満足しています。 Next.jsは、ドキュメントサイトにアプリのような機能を構築するための優れた基盤を提供します。これらの最初のものは、まったく新しいインタラクティブなチュートリアルと、新しい検索可能な例とボイラープレートディレクトリになります。いつものように、お手伝いをする、またはより深く掘り下げることに興味がある場合は、新しいドキュメントの完全なソースコードがGitHubで入手できます。

それで、調べてみてください、しかし穏やかにしてください。バグが見つかったら、問題を報告してください。この新しいNotion搭載のブログでは、より頻繁に投稿する予定です。フッターにあるメールアドレスを入力して購読ボタンをクリックして、Formikメーリングリストに参加してください。

-J

2021年9月更新

この記事を書いて以来、NotionにはパブリックAPIができました。しかし、最終的にはブログコンテンツにもMDXに切り替えました.

Notionで遭遇した問題は、承認なしに外部のコントリビューターによって作成されたPRでドキュメントのビルドが失敗することです。これは、NotionをCMSとして使用するには、Vercelが組織外の開発者によって行われたPRデプロイメントへのアクセスを正当に許可しない秘密のAPIトークンが必要なためです。これは実際にはNotionに固有のものではありませんが、OSSプロジェクトのブログを強化するために使用されるヘッドレスCMSでも同じです。すべてのPRがすぐに失敗するため、GitHubでFormikの問題をブラウズするのが困難になりました。さらに、新しいコントリビューターにとって、何も間違っていなくても赤いXが表示されるのは素晴らしい経験ではありません。

この時点で、ブログを独自のレポまたはサイトに移動することもできましたが、Notionを古き良きMDXにドロップして、すべてをコードベース内に保持する方が簡単だと判断しました.

NotionのパブリックAPIに加えて、Docusaurus v2はモバイルナビゲーションを更新および改善しました。Next.jsを搭載したDocusaurusのようなNextraと呼ばれる別のプロジェクトとともに、チェックしてみる価値があります。今日Formikドキュメントを書き直す場合、おそらくnextra-theme-docsをフォークするでしょう.