Nextra で Docs サイトを作る

2023-11-11

#Next.js

#Nextra

#Vercel

#GitHub

#pnpm

最小構成の Nextra を GitHub 経由で Vercel にデプロイする

Overview

最小構成の Nextra を GitHub 経由で Vercel にデプロイする

Flow

リポジトリの作成

（pnpm をインストール）

Terminal window
npm i -g pnpm

プロジェクトディレクトリを作成

Terminal window
ni <PROJECT_NAME> -type dir
Terminal window
cd <PROJECT_NAME>

Git を初期化

Terminal window
git init -b main

.gitignore を作成

Terminal window
ni .gitignore
.gitignore
.next
node_modules

パッケージをインストール

Terminal window
pnpm add next react react-dom nextra nextra-theme-docs

作成された package.json に scripts を追記

package.json
"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
},

next.config.js を作成

Terminal window
ni next.config.js
next.config.js
const withNextra = require("nextra")({
  theme: "nextra-theme-docs",
  themeConfig: "./theme.config.jsx",
});


module.exports = withNextra();


// If you have other Next.js configurations, you can pass them as the parameter:
// module.exports = withNextra({ /* other next.js config */ })

theme.config.jsx を作成

Terminal window
ni theme.config.jsx
theme.config.jsx
export default {
  logo: <span>My Nextra Documentation</span>,
  project: {
    link: "https://github.com/<GITHUB_USERNAME>/<PROJECT_NAME>/",
  },
  docsRepositoryBase:
    "https://github.com/<GITHUB_USERNAME>/<PROJECT_NAME>/tree/<DEPLOY_BRANCH>/",
  // ... other theme options
};

index ページを追加

Terminal window
ni pages/index.mdx -force
pages/index.mdx
# Welcome to Nextra


Hello, world!

変更をコミットし、リポジトリを GitHub へプッシュ

Terminal window
git add .
git commit -m "First commit"

Vercel へのデプロイ

Vercel にログインする

Add new project を選択する
Import Git Repository で 作成したリポジトリを選択する
Deploy をクリックして開始

何事もなく完了すれば、デプロイは成功 🎉

Note

ページの更新日時が表示されない

更新から数日経ったページなどで、gitTimestamp が付与されなくなることがある
デフォルトでは shallow clone されることが原因

Vercel に作成されたプロジェクトの Settings を開く
Environment Variables を開き、以下の環境変数を追加する
deep clone されるようになり、各ページの更新日時が Git のコミット日時から取得・表示される

KeyValue
VERCEL_DEEP_CLONEtrue

_meta.json を更新しても反映されない

_meta.json を更新して、サイドバーに表示される記事の順序を変更しようとしても、反映されない場合がある
Vercel のキャッシュの問題らしく、以下の手順で反映させることができる

  1. 更新内容を GitHub に Push 後、自動デプロイの完了を待つ
  2. Vercel の Deployments から最新コミットの Redeploy を選択し、​Use existing Build Cache のチェックを外して開始する

根本的な解決には至っていない模様

InvalidCharacterError: Failed to execute ‘add’ on ‘DOMTokenList’

以下のクソ長いエラーのため、Local 環境でエラーが発生した
原因は localhost:3000 のローカルストレージに theme values が保存されていたこと（いつの間に）
（内容的に、Misskey をローカルで起動した際に作成されたっぽい）

Chrome の開発者ツールから
アプリケーション > ストレージ > ローカルストレージ > http://localhost:3000
を右クリックし 消去 することで解決

Unhandled Runtime Error
InvalidCharacterError: Failed to execute 'add' on 'DOMTokenList': The token provided ('{"accent":"rgb(113, 136, 217)","accentDarken":"rgb(73, 102, 206)","accentLighten":"rgb(153, 170, 228)","accentedBg":"rgba(113, 136, 217, 0.15)","focus":"rgba(113, 136, 217, 0.3)","bg":"rgb(32, 34, 37)","acrylicBg":"rgba(32, 34, 37, 0.5)","fg":"rgb(228, 228, 228)","fgTransparentWeak":"rgba(228, 228, 228, 0.75)","fgTransparent":"rgba(228, 228, 228, 0.5)","fgHighlighted":"rgb(255, 255, 255)","fgOnAccent":"rgb(255, 255, 255)","fgOnWhite":"rgb(51, 51, 51)","divider":"rgba(255, 255, 255, 0.1)","indicator":"rgb(113, 136, 217)","panel":"rgb(54, 57, 63)","panelHighlight":"rgb(61, 64, 71)","panelHeaderBg":"rgb(61, 64, 71)","panelHeaderFg":"rgb(228, 228, 228)","panelHeaderDivider":"rgba(0, 0, 0, 0)","panelBorder":"solid 1px var(--divider)","acrylicPanel":"rgba(54, 57, 63, 0.5)","windowHeader":"rgba(54, 57, 63, 0.85)","popup":"rgb(61, 64, 71)","shadow":"rgba(0, 0, 0, 0.3)","header":"rgb(47, 49, 54)","navBg":"rgb(47, 49, 54)","navFg":"rgb(142, 146, 151)","navHoverFg":"rgb(220, 221, 222)","navActive":"rgb(255, 255, 255)","navIndicator":"rgb(113, 136, 217)","link":"rgb(0, 176, 244)","hashtag":"rgb(113, 136, 217)","mention":"rgb(113, 136, 217)","mentionMe":"rgb(113, 136, 217)","renote":"rgb(67, 181, 129)","modalBg":"rgba(0, 0, 0, 0.5)","scrollbarHandle":"rgb(32, 34, 37)","scrollbarHandleHover":"rgba(255, 255, 255, 0.4)","dateLabelFg":"rgb(228, 228, 228)","infoBg":"rgb(37, 49, 66)","infoFg":"rgb(255, 255, 255)","infoWarnBg":"rgb(66, 50, 28)","infoWarnFg":"rgb(255, 189, 62)","switchBg":"rgba(255, 255, 255, 0.15)","buttonBg":"rgba(255, 255, 255, 0.05)","buttonHoverBg":"rgba(255, 255, 255, 0.1)","buttonGradateA":"rgb(113, 136, 217)","buttonGradateB":"rgb(125, 113, 217)","switchOffBg":"rgba(255, 255, 255, 0.1)","switchOffFg":"rgba(228, 228, 228, 0.8)","switchOnBg":"rgba(113, 136, 217, 0.15)","switchOnFg":"rgb(113, 136, 217)","inputBorder":"rgba(255, 255, 255, 0.1)","inputBorderHover":"rgba(255, 255, 255, 0.2)","listItemHoverBg":"rgba(255, 255, 255, 0.03)","driveFolderBg":"rgba(113, 136, 217, 0.3)","wallpaperOverlay":"rgba(0, 0, 0, 0.5)","badge":"rgb(49, 177, 206)","messageBg":"rgb(32, 34, 37)","success":"rgb(134, 179, 0)","error":"rgb(236, 65, 55)","warn":"rgb(236, 182, 55)","codeString":"rgb(255, 182, 117)","codeNumber":"rgb(207, 255, 158)","codeBoolean":"rgb(197, 158, 255)","deckBg":"rgb(0, 0, 0)","htmlThemeColor":"rgb(32, 34, 37)","X2":"rgb(49, 52, 58)","X3":"rgba(255, 255, 255, 0.05)","X4":"rgba(255, 255, 255, 0.1)","X5":"rgba(255, 255, 255, 0.05)","X6":"rgba(255, 255, 255, 0.15)","X7":"rgba(255, 255, 255, 0.05)","X8":"rgb(133, 153, 222)","X9":"rgb(93, 119, 212)","X10":"rgba(113, 136, 217, 0.4)","X11":"rgba(0, 0, 0, 0.3)","X12":"rgba(255, 255, 255, 0.1)","X13":"rgba(255, 255, 255, 0.15)","X14":"rgba(47, 49, 54, 0.5)","X15":"rgba(54, 57, 63, 0)","X16":"rgba(54, 57, 63, 0.7)","X17":"rgba(32, 34, 37, 0.8)"}') contains HTML space characters, which are not valid in tokens.

Ref