Nextra + Amplifyでさくっとオンラインマニュアルサイトを立ち上げる
お客様に依頼されて作成したWebサービスの管理サイトのマニュアルを作成することになり、最初パワポで作成して収めようかと思ったのですが、
- 更新の度に、お客様に送付するのがめんどくさい
- お客様の方で、最新版をちゃんとファイルを管理してもらえるのかわからない（それを負担させるのも申し訳ない）
- 現場のお客様は、PCよりタブレットやスマフォがメインなので、パワポで作成したところで、現場でそれを閲覧できるのかどうかわからない
- パワポで作成するのもしんどい
の理由から、オンラインマニュアルを検討することにしました。なお、検討する上で、普段よく使っているMarkdownで記載できると楽だなと思い、いくつか案を考えました。
案①：GROWI
昔会社員時代に、部内のナレッジ共有でつかってました。Markdownで投稿・編集できて、ナレッジ共有できるサービスです。やるとすればEC2などで、サーバーを立ち上げて実施する感じですが、正直投稿は私しかしないので、サービス側に投稿できるようにする必要があるのか？という気もして、この案は却下しました。
案②：esa.io
これも、昔所属した会社で利用していました。有料のクラウドナレッジマネジメントサービスです。簡単に利用できるのは便利ですが、閲覧するにもアカウントが必要で、結構お金がかかるので、却下です。
案③：microCMS + Next.js
microCMSとNext.jsのSSGでサイトを構築することが良くあるので、ありかなとも思いました。マニュアル程度であれば、無料プランに収まりそうな気もします。ただ、あまり更新しないマニュアルをわざわざCMSで管理するかといわれるとオーバースペックな気がします。
どれもしっくりこない・・・
どれもしっくりこないなーとおもい、単純にMarkdownで記載すれば、それがそのまま記事になればいいので、Next.jsとmarkdown-to-jsxで作ろうかなーと思いながら、もっと楽できないかとNext.jsのTemplatesを眺めていたところ、Nextraという、Starter Kitを発見し、ちょっとよく見るとまさに求めていたものでした。
Nextraとは？
Nextraは、Next.jsのSSGでMarkdownからドキュメントサイトを生成するNext.jsのStarter Kitです。特徴としては、
- 記事は基本的にMarkdownで記載するだけ
- 最初からテキスト検索機能などが組み込まれており、記事を書くことに集中できる
- SSGなので、Next.jsをVercelやAmplifyなどにデプロイするだけでよい
等です。今回の
- オンラインマニュアルを作成したい
- マニュアルの作成者は限られており、編集機能をWebサイトに持たせる必要はない
- コンポーネントや、検索機能など、めんどくさいことは一切したくない、とりあえず、早く立ち上げたい
という要望にまさにマッチしていました。
Nextraでサイトを作成
リポジトリを作成
最初に、GitHubでリポジトリを作成します。NextraのGitHubのリポジトリを開き、Use this templateボタンからCreate a new repositoryを選択し、テンプレートからリポジトリを作成します
リポジトリ名を適当に設定して、Create repository from templateから、リポジトリを作成します。なお、今回作成したのは、お客様向けのサイトなので、Privateなリポジトリにしています。
これでリポジトリは完成です。
ローカル環境で動かす
まず、ローカル環境で動かしてみます。作成したGitHubのリポジトリをcloneします。そして作成されたディレクトリに移動し、実行します。私の開発PCはyarnがインストールされているので、以下のコマンドで起動できます。
yarn install
yarn dev
起動すると、ブラウザで、http://localhost:3000にアクセスすると、初期状態で以下のようなサイトが表示されます。
ヘッダーをカスタマイズする
初期状態だと、ヘッダに、
- ロゴ（My Project)
- Aboutページへのリンク
- 検索フォーム
- Contact（Twitterへのリンク）
- GitHubへのリンク
- Discordへのリンク
がありますが、下の３つはいらないので削除します。theme.config.tsxを開き以下の行を削除します。
import React from 'react'
import { DocsThemeConfig } from 'nextra-theme-docs'
const config: DocsThemeConfig = {
logo: <span>My Project</span>,
- project: {
- link: 'https://github.com/shuding/nextra-docs-template',
- },
- chat: {
- link: 'https://discord.com',
- },
- docsRepositoryBase: 'https://github.com/shuding/nextra-docs-template',
footer: {
text: 'Nextra Docs Template',
},
}
export default config
次に、pages/_meta.jsonを開き、以下の行を削除します。
{
"index": "Introduction",
"another": "Another Page",
"advanced": "Advanced (A Folder)",
"about": {
"title": "About",
"type": "page"
},
- "contact": {
- "title": "Contact ↗",
- "type": "page",
- "href": "https://twitter.com/shuding_",
- "newWindow": true
- }
}
これでヘッダから、不要なコンポーネントがなくなりました。
内容を書く
内容は、pages内に、mdxを拡張しとして、Markdownの記事を書くだけです。私はTyporaを普段つかってMarkdownを作成しているので、ひたすらTyporaでMarkdownを書いていけば、オンラインマニュアルの完成です。
Typoraは、有償化されましたが、値段は15$ 程度で、買い切りなので、頑張って他のツールを探して、それに慣れるコストを考えると買ってしまった方が良いと思い。有償化されて即購入しました。
ストレスフリーにMarkdownをかけるので、とても重宝しています。
Amplifyにデプロイ
最後に、作成したサイトをホスティングします。Amplifyでも、VercelでもNetlifyでもなんでもよいのですが、普段AWSのAmplifyを使っているので、Amplifyでホスティングします。
GitHubアカウントと連携していれば、AWSのマネジメントコンソールにログインして、Amplifyのコンソールで、新しいアプリケーションを選択し、GitHubからリポジトリを選択して、次への選択していけば、ホスティングが完了です。
Amplifyを使用すれば、
- カスタムドメインで公開する
- Basic認証をかけて、限定公開にする
などの設定も簡単にできてしまいます。
ひたすらMarkdownを書く
GitHub ⇒ Amplifyの連携さえできてしまえば、あとは、ひたすらMarkdownを書いて、GitHubにpushしてしまえば、自動的にオンラインマニュアルが更新されます。
最初に仕組みさえ作ってしまえば、開発しながらマニュアルを書けますし、あとでマニュアル作るのめんどくさいなーと感じないのでお勧めです。
Discussion