※この記事は、Nextraというツールでドキュメントを書くのに必要な情報のみ集めてあります。
Nextraとは
Nextra は、Markdown で作成したmdxドキュメントファイルをそのままページとして公開できます。
Next.js をベースにした静的サイト生成ツールです。
Vercel を使用すると、ボタンひとつで基本的な部分を公開できるため、ドキュメントの編集に集中できます。
また、Markdown で編集できるため、シンタックスハイライト等が可能です。
GitHub でドキュメントを管理します。
GitHub Pagesで公開することも出来ます。
NextraはBlog等も公開できます。
必要なもの
Nextra
Vercel アカウント
GitHub アカウント
VSCode or Cursor
Nextra ドキュメントジェネレーター
公式サイト
Nextra – Next.js Static Site Generator
開始
Vercel アカウント
GitHub アカウント
を用意しておきます。
Docs Theme – Nextra
↑このページのクイックスタートを利用してVercelにデプロイします。
手順
Deploy to Vercel の項目にある「▲ Deploy」ボタンを押すだけです。
後は順番通りに進めていくだけです。
GitHub にもリポジトリが出来るので、
GitHubのリポジトリからローカルにpullして↓インストールをします。
そうするとローカルから編集が出来るようになります。
pnpm i
Nextraの使い方
VSCodeやCursorで編集します。
基本
1ファイルがそれぞれブラウザで表示される１ページに相当します。
Next.jsをベースに利用しているので、フォルダでのルーティングが可能です。
pagesフォルダの下にフォルダを作成するとその下にメニューの項目が増えます。
使用できる拡張子
拡張子.mdファイル
拡張子.mdxファイル
フォルダやファイルを作ると、左側にメニューが表示され、１つのフォルダ、ファイルが１つのメニューの項目に相当します。
管理ファイル _meta.json
pages_meta.json
↑このファイルでページの管理をします。
上から順に指定したファイルが、そのままブラウザ側でもその順番が反映されメニューの項目になります。
pagesフォルダの下に新たにフォルダやファイルを作っても、 _meta.json に登録しないとメニューの項目に反映されません。
データはjson形式で指定します。
JSONはプロパティ名（キー）と値のペアを使用してデータを構造化します。これらのペアは中括弧 {} で囲まれ、コロン : で区切られます。複数のペアはコンマ , で区切られます。
例えば、以下のようになります。
基本形
"拡張子を除いたファイル名": "メニューの項目名"
"フォルダ名": {
"apple": "りんご",
"orange": "みかん",
"banana": "バナナ"
},
_meta.jsonファイルはフォルダごとに配置します。
つまり、ネストしたフォルダごとに_meta.jsonを配置することで
そのフォルダの項目を表示する順番などが設定出来ます。
Page Configuration ページ構成
Page Configuration – Nextra
https://nextra.site/docs/docs-theme/page-configuration#fallbacks
Pages
↓このファイルが左サイドバーのメニューの項目の順番を決められます。
pages_meta.json
このように編集すると、メニューの項目の順番がそのまま反映されます。
{
"index": "My Homepage",
"contact": "Contact Us",
"about": "About Us"
}
Folders
フォルダは通常ページなりません、
しかし、フォルダはメニューの項目になっています。
そこに、メニューの項目のページを追加したい場合は、
フォルダと同じディレクトリに、同じ名前のMDXファイルを追加します。
例えば、/advancedルートを追加したい場合、pagesに advanced.mdxファイルを作成します。
{
"index": "Introduction",
"another": "Another Page",
"advanced": "Advanced (A Folder)",
"about": {
"title": "About",
"type": "page"
},
"contact": {
"title": "Contact ↗",
"type": "page",
"href": "https://twitter.com/masakinihirota", <<< 外部リンクの設定です。
"newWindow": true <<< リンクを新しいウィンドウで開きます。
}
}
_meta.json に href を含む項目を追加することで、サイドバーに外部リンクを追加できます。
リンクを常に新しいタブで開くには、"newWindow": true オプションを有効にします。
隠しルート
デフォルトでは、ファイルシステム内のすべての MDX ルートがサイドバーに表示されます。
ただし、"display": "hidden"構成を使用すると、特定のページまたはフォルダーを非表示にすることができます。
{
"index": "My Homepage",
"contact": {
"display": "hidden" <<< 隠す
},
"about": "About Us"
}
ページには引き続き /contact URL 経由でアクセスできますが、サイドバーには表示されません。
"display": "hidden"オプションを使用して、ナビゲーションバーからホームなどのリンクを非表示にすることもできます。
Navbar Items
Sub Docs
トップレベルのページやフォルダを
"type": "page"
として定義することで、サイドバーの代わりに
ナビゲーションバーに特別なページとして表示されます。
この機能により、複数の "サブドキュメント "や、常に表示される "お問い合わせ "のような特別なページやリンクを持つことができます。
例えば、プロジェクトに2つのdocsフォルダframeworksとfruitsを持つことができます：
最上位の _meta.json ファイルでは、通常のサイドバー項目ではなく、すべてをページとして設定できます。
page
frameworks
react.mdx
svelte.mdx
vue.mdx
fruits
apple.mdx
banana.mdx
_meta.json
about.mdx
トップレベルの_meta.jsonファイルで、通常のサイドバーアイテムの代わりに、すべてをページとして設定することができます：
{
"index": {
"title": "Home",
"type": "page"
},
"frameworks": {
"title": "Frameworks",
"type": "page"
},
"fruits": {
"title": "Fruits",
"type": "page"
},
"about": {
"title": "About",
"type": "page"
}
}
"display": "hidden"オプションを使用して、ナビゲーションバーからホームなどのリンクを非表示にすることもできます。
Menus
"type": "menu" および "items" オプションを使用して、ナビゲーションバーにメニューを追加することもできます。
{
"company": {
"title": "Company",
"type": "menu",
"items": {
"about": {
"title": "About",
"href": "/about"
},
"contact": {
"title": "Contact Us",
"href": "mailto:hi@example.com"
}
}
}
}
Links
[外部リンク] オプションと同じように、ナビゲーションバーにも外部リンクを含めることができます。
{
"index": {
"title": "Home",
"type": "page"
},
"about": {
"title": "About",
"type": "page"
},
"contact": {
"title": "Contact Us",
"type": "page",
"href": "https://example.com/contact",
"newWindow": true
}
}
Fallbacks
上記の Sub Docs の例では、すべてのページに "type": "page" オプションを定義する必要があります。
簡単にするために、「*」キーを使用して、このフォルダー内のすべてのアイテムのフォールバック構成を定義できます。
{
"*": {
"type": "page"
},
"index": "Home",
"frameworks": "Frameworks",
"fruits": "Fruits",
"about": "About"
}
すべての項目に "type": "page" が設定されている場合、これらは同等です。
Separators
「type」:「separator」で「プレースホルダー」項目を使用すると、サイドバーの項目間に区切り線を作成できます。
{
"index": "My Homepage",
"---": {
"type": "separator"
},
"contact": "Contact Us"
}
Sidebar.titleComponent テーマ オプションと併用すると、サイドバーのタイトルと区切り線の外観をカスタマイズできます。
Markdown
Markdown – Nextra
https://nextra.site/docs/guide/markdown
MDX
MDXはReact コンポーネントをサポートする高度な Markdown 形式です。
↓このようにReactの Hooksが使えます、ページにコードを貼り付けるとカウントされます。
## Hello MDX
import { useState } from 'react'
export function Counter({ children }) {
const [count, setCount] = useState(0)
return (
<button onClick={() => setCount(count + 1)}>
{children}
{count}
</button>
)
}
<Counter>**Clicks**: </Counter>
GitHub Flavored Markdown (GFM)
GFMはGitHubによって作られたMarkdownの拡張機能で、取り消し線、タスクリスト、表などをサポートします。
Strikethrough 取り消し線
~~removed~~
Task List タスクリスト
- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media
Table 表
| Syntax | Description | Test Text |
| :------------ | :---------: | ----------: |
| Header | Title | Here's this |
| Paragraph | Text | And more |
| Strikethrough | | ~~Text~~ |
Autolinks
httpsは自動でリンクになります。
Visit https://nextjs.org.
Custom Heading Id
カスタム見出しIDは
## My heading [#custom-id]
というフォーマットで指定できます。例えば
## Long heading about Nextra [#about-nextra]
この例では、デフォルトの ##long-heading-about-nextra を置き換えて、 #about-nextra が見出しリンクとして使われます。
Extended Syntax Highlighting 構文の強調表示
`で囲む
↓このコード部分が、色付きのシンタックスハイライトで表示されます。
例
Inlined syntax highlighting is also supported let x = 1{:jsx} via:
シンタックスハイライト
Syntax Highlighting – Nextra
`js
console.log('hello, world')
`
Features
Inlined Code
Inlined syntax highlighting is also supported `let x = 1{:jsx}` via:
Highlighting Lines
線の強調表示 コード ブロックに {} 属性を追加すると、コードの特定の行を強調表示できます。
`js {1,4-5}
import { useState } from 'react'
function Counter() {
const [count, setCount] = useState(0)
return setCount(count + 1)}>{count}
}
`
function Counter() { <<< この行はハイライトされません。
Highlighting Substrings 部分文字列のハイライト
属性をコード ブロックに追加することで、
コードの特定の部分文字列を強調表示できます。
`js /useState/
import { useState } from 'react'
function Counter() {
const [count, setCount] = useState(0)
return setCount(count + 1)}>{count}
}
`
/str/1 のように数値を追加するか、/str/1-3、/str/1,3 のように複数の数値を追加することで、その部分文字列の出現の一部のみを強調表示できます。
Copy Button
copy 属性を追加すると、ユーザーがコード ブロックの上にカーソルを置いたときに、コード ブロックにコピー ボタンが追加されます。
`js copy
console.log('hello, world')
`
Nextra 構成 (next.config.js ファイル) でdefaultShowCopyCode: true を設定することで、この機能をグローバルに有効にすることができます。グローバルに有効にしたら、copy=false 属性を使用して無効にできます。
Line Numbers
行番号の追加
showLineNumbers 属性を追加することで、コード ブロックに行番号を追加できます。
`js showLineNumbers
import { useState } from 'react'
function Counter() {
const [count, setCount] = useState(0)
return setCount(count + 1)}>{count}
}
`
Filenames and Titles
コード ブロックにファイル名またはタイトルを追加できます。
`js filename="example.js"
console.log('hello, world')
`
ハイライトに対応している全言語リスト
abap
actionscript-3
ada
apache
apex
apl
applescript
ara
asm
astro
awk
ballerina
bat | batch
beancount
berry | be
bibtex
bicep
blade
c
cadence | cdc
clarity
clojure | clj
cmake
cobol
codeql | ql
coffee
cpp | c++
crystal
csharp | c# | cs
css
csv
cue
cypher | cql
d
dart
dax
diff
docker | dockerfile
dream-maker
elixir
elm
erb
erlang | erl
fish
fsharp | f# | fs
gdresource
gdscript
gdshader
gherkin
git-commit
git-rebase
glimmer-js | gjs
glimmer-ts | gts
glsl
gnuplot
go
graphql | gql
groovy
hack
haml
handlebars | hbs
haskell | hs
hcl
hjson
hlsl
html
http
imba
ini | properties
java
javascript | js
jinja-html
jison
json
json5
jsonc
jsonl
jsonnet
jssm | fsl
jsx
julia
kotlin | kt | kts
kusto | kql
latex
less
liquid
lisp
logo
lua
make | makefile
markdown | md
marko
matlab
mdc
mdx
mermaid
mojo
narrat | nar
nextflow | nf
nginx
nim
nix
objective-c | objc
objective-cpp
ocaml
pascal
perl
php
plsql
postcss
powerquery
powershell | ps | ps1
prisma
prolog
proto
pug | jade
puppet
purescript
python | py
r
raku | perl6
razor
reg
rel
riscv
rst
ruby | rb
rust | rs
sas
sass
scala
scheme
scss
shaderlab | shader
shellscript | bash | sh | shell | zsh
shellsession | console
smalltalk
solidity
sparql
splunk | spl
sql
ssh-config
stata
stylus | styl
svelte
swift
system-verilog
tasl
tcl
tex
toml
tsx
turtle
twig
typescript | ts
v
vb | cmd
verilog
vhdl
viml | vim | vimscript
vue-html
vue
vyper | vy
wasm
wenyan | 文言
wgsl
wolfram
xml
xsl
yaml | yml
zenscript
zig
Next.js リンク
Next.js Link – Nextra
すべての相対 Markdown リンクは自動的に Next.js リンクに変換されます。
相対リンク
[here](/about)
これは、対象のページがプリフェッチされることを意味します。また、リンクをクリックすると、ページ全体を読み込むことなく、SPA のようにクライアント側にページが読み込まれます。
例
Click [here](/about) to read more.
Next.js イメージ
Next.js Image – Nextra
Next.js イメージの標準的な使用方法 MDX 内でコンポーネントを直接インポートするには、次のようにします。
import Image from 'next/image'
<Image src="/demo.png" alt="Hello" width={500} height={500} />
静止画像
この機能は、デフォルトでNextra config の staticImage: trueが有効になっています。
Markdown 構文を使用した静的画像インポートの自動最適化をサポートしています。
画像の幅と高さを指定する必要はありません。
Next.js SSG
Next.js SSG – Nextra
静的生成 (SSG)を使用してページを事前レンダリングできます。
パフォーマンスを最大化するために CDN によってキャッシュすることもできます。
Next.js I18n
Next.js I18n – Nextra
i18n化するには・・・
1 Add I18n Config
Nextraアプリケーションに多言語ページを追加するには、
まずnext.config.jsで国際化を設定する必要があります：
const withNextra = require('nextra')({
theme: 'nextra-theme-docs',
themeConfig: './theme.config.tsx'
})
module.exports = withNextra({
i18n: {
locales: ['en-US', 'zh-CN', 'de-DE'],
defaultLocale: 'en-US'
}
})
2 Add Middleware
次に、プロジェクトのルートにmiddleware.jsファイルを追加します（関連Next.jsドキュメント）：
export { locales as middleware } from 'nextra/locales'
すでにミドルウェアが定義されている場合は、下記のようにします。
import { withLocales } from 'nextra/locales'
export const middleware = withLocales(request => {
// Your middleware code...
})
3 Add Locale to Filenames
次に、ファイルの拡張子にロケールコードを追加します（デフォルトロケールにも必要です）：
/pages
_meta.en-US.json
_meta.zh-CN.json
_meta.de-DE.json
index.en-US.md
index.zh-CN.md
index.de-DE.md
...
4 Configure the Docs Theme
最後に、言語ドロップダウンを設定するために、theme.config.jsxに国際化オプションを追加します：
i18n: [
{ locale: 'en-US', text: 'English' },
{ locale: 'zh-CN', text: '中文' },
{ locale: 'de-DE', text: 'Deutsch' },
{ locale: 'ar-SA', text: 'العربية', direction: 'rtl' }
]
import { Callout } from 'nextra/components'
<Callout type="info" emoji="ℹ">
Today is Friday.
</Callout>