Nextra 無料で簡単にドキュメントをMarkdownで編集出来る静的サイトを作るツール (ドキュメント編)

※この記事は、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

https://nextra.site/



## 開始

Vercel アカウント
GitHub アカウント
を用意しておきます。

Docs Theme – Nextra

https://nextra.site/docs/docs-theme/start

↑このページのクイックスタートを利用してVercelにデプロイします。

手順
Deploy to Vercel の項目にある「▲ Deploy」ボタンを押すだけです。
後は順番通りに進めていくだけです。

GitHub にもリポジトリが出来るので、
GitHubのリポジトリからローカルにpullして↓インストールをします。
そうするとローカルから編集が出来るようになります。

```terminal
pnpm i

```



# Nextraの使い方

VSCodeやCursorで編集します。



## 基本

1ファイルがそれぞれブラウザで表示される１ページに相当します。
Next.jsをベースに利用しているので、フォルダでのルーティングが可能です。
pagesフォルダの下にフォルダを作成するとその下にメニューの項目が増えます。

### 使用できる拡張子

```
拡張子.mdファイル
拡張子.mdxファイル

```

フォルダやファイルを作ると、左側にメニューが表示され、１つのフォルダ、ファイルが１つのメニューの項目に相当します。



## 管理ファイル _meta.json

pages\_meta.json

↑このファイルでページの管理をします。
上から順に指定したファイルが、そのままブラウザ側でもその順番が反映されメニューの項目になります。

pagesフォルダの下に新たにフォルダやファイルを作っても、 _meta.json に登録しないとメニューの項目に反映されません。

データはjson形式で指定します。

JSONはプロパティ名（キー）と値のペアを使用してデータを構造化します。これらのペアは中括弧 {} で囲まれ、コロン : で区切られます。複数のペアはコンマ , で区切られます。

例えば、以下のようになります。

### 基本形

```_meta.json
"拡張子を除いたファイル名": "メニューの項目名"

```

```_meta.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

このように編集すると、メニューの項目の順番がそのまま反映されます。

```pages/_meta.json
	{
	  "index": "My Homepage",
	  "contact": "Contact Us",
	  "about": "About Us"
	}

```



## Folders

フォルダは通常ページなりません、
しかし、フォルダはメニューの項目になっています。
そこに、メニューの項目のページを追加したい場合は、

フォルダと同じディレクトリに、同じ名前のMDXファイルを追加します。

例えば、/advancedルートを追加したい場合、pagesに advanced.mdxファイルを作成します。

```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/masakinihirota",   <<< 外部リンクの設定です。
    "newWindow": true   <<< リンクを新しいウィンドウで開きます。
  }
}

```

_meta.json に href を含む項目を追加することで、サイドバーに外部リンクを追加できます。

リンクを常に新しいタブで開くには、"newWindow": true オプションを有効にします。



## 隠しルート

デフォルトでは、ファイルシステム内のすべての MDX ルートがサイドバーに表示されます。

ただし、"display": "hidden"構成を使用すると、特定のページまたはフォルダーを非表示にすることができます。



```pages/_meta.json
{
  "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ファイルで、通常のサイドバーアイテムの代わりに、すべてをページとして設定することができます：



```pages/_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" オプションを使用して、ナビゲーションバーにメニューを追加することもできます。



```pages/_meta.json
{
  "company": {
    "title": "Company",
    "type": "menu",
    "items": {
      "about": {
        "title": "About",
        "href": "/about"
      },
      "contact": {
        "title": "Contact Us",
        "href": "mailto:hi@example.com"
      }
    }
  }
}

```



### Links

[外部リンク] オプションと同じように、ナビゲーションバーにも外部リンクを含めることができます。

```pages/_meta.json
{
  "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" オプションを定義する必要があります。

簡単にするために、「*」キーを使用して、このフォルダー内のすべてのアイテムのフォールバック構成を定義できます。



```pages/_meta.json
{
  "*": {
    "type": "page"
  },
  "index": "Home",
  "frameworks": "Frameworks",
  "fruits": "Fruits",
  "about": "About"
}

```

すべての項目に "type": "page" が設定されている場合、これらは同等です。



## Separators

「type」:「separator」で「プレースホルダー」項目を使用すると、サイドバーの項目間に区切り線を作成できます。

```_meta.json
{
  "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が使えます、ページにコードを貼り付けるとカウントされます。

```Markdown
## 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

https://nextra.site/docs/guide/syntax-highlighting

\`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 <button onClick={() => setCount(count + 1)}>{count}</button>
}

\`

function Counter() { <<< この行はハイライトされません。



## Highlighting Substrings 部分文字列のハイライト

属性をコード ブロックに追加することで、
コードの特定の部分文字列を強調表示できます。



\`js /useState/
import { useState } from 'react'

function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

\`



/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 <button onClick={() => setCount(count + 1)}>{count}</button>
}

\`



## Filenames and Titles

コード ブロックにファイル名またはタイトルを追加できます。

\`js filename="example.js"
console.log('hello, world')

\`



<details><summary>ハイライトに対応している全言語リスト</summary>

```
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


```

</details>



----------------------------------------

# Next.js リンク

Next.js Link – Nextra

https://nextra.site/docs/guide/link

すべての相対 Markdown リンクは自動的に Next.js リンクに変換されます。

相対リンク

```
[here](/about)

```



これは、対象のページがプリフェッチされることを意味します。また、リンクをクリックすると、ページ全体を読み込むことなく、SPA のようにクライアント側にページが読み込まれます。



例

```
Click [here](/about) to read more.

```



----------------------------------------

# Next.js イメージ

Next.js Image – Nextra

https://nextra.site/docs/guide/image



Next.js イメージの標準的な使用方法 MDX 内でコンポーネントを直接インポートするには、次のようにします。



```
import Image from 'next/image'

<Image src="/demo.png" alt="Hello" width={500} height={500} />

```



## 静止画像


この機能は、デフォルトでNextra config の staticImage: trueが有効になっています。


```
![Hello](/demo.png)

```

Markdown 構文を使用した静的画像インポートの自動最適化をサポートしています。
画像の幅と高さを指定する必要はありません。




----------------------------------------

# Next.js SSG

Next.js SSG – Nextra

https://nextra.site/docs/guide/ssg

静的生成 (SSG)を使用してページを事前レンダリングできます。
パフォーマンスを最大化するために CDN によってキャッシュすることもできます。



----------------------------------------

# Next.js I18n

Next.js I18n – Nextra

https://nextra.site/docs/guide/i18n

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に国際化オプションを追加します：

```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>

```