## 経緯
[[🦉JINRAI]]のv1がそろそろ本当に近くなってきたと思うので、リリース方法を筆頭に色々と整理をしている。ドキュメントはREADME(日/英)を用意しているが、ボリュームも増えてきたし、すべて[[Codex CLI]]に任せて読みにくい箇所もあると思うので、この機会に整理したい。
## 方針
[[Zensical]]を使う。
- [[MkDocs v2では下位互換性が破壊されプラグインなどのエコシステムが使えなくなる]]し、[[ProperDocs]]や[[MaterialX]]は将来性があまりなさそうなので
- [[Zensical]]はまだv0.1にも到達していないが、[[Material for MkDocs]]のチームが開発しており信頼できる
- 実際に試してみたところ想像以上にしっかり動く実感があった
## 必要な要件
[[Zensical]]が対応しているかどうか。
- ❌ [[wikiリンク]]が使える
- `2026/06/07` 時点ではまだ対応してなさそう
- 参考: [[ZensicalでObsidianのWikiリンク]]
- [[Markdownリンク]]でも問題ない
- [[🦉Various Complements]]よりはボリュームがないと思うので、あとで置換するでもOK
- ❌ [[バックリンク]]が使える
- `2026/06/07` 時点ではまだ対応してなさそう
- ✅ 多言語対応できる
- できそうな気がするので要確認
## やること
- [x] インストール
- [x] READMEだけぶち込んだドキュメントをつくる
- [-] 日・英対応してみる
- [ ] [[Obsidian]]で編集できるようにしてみる (必要なら)
| 対象 | バージョン |
| ------------ | ------ |
| [[Zensical]] | 0.0.44 |
| [[uv]] | 0.11.9 |
| [[macOS]] | 26.5 |
## インストール
<div class="link-card-v2">
<div class="link-card-v2-site">
<img class="link-card-v2-site-icon" src="https://zensical.org/docs/assets/zensical.png" />
<span class="link-card-v2-site-name">zensical.org</span>
</div>
<div class="link-card-v2-title">
Zensical
</div>
<div class="link-card-v2-content">
Adaptive systems for evolving ideas – Zensical creates scalable Open Source systems for technical writing that a ...
</div>
<img class="link-card-v2-image" src="https://zensical.org/assets/social.png" />
<a href="https://zensical.org/docs/get-started/"></a>
</div>
```console
cd docs
uv init
uv add --dev zensical
uv run zensical
```
> [!info]- インストールバージョン
> ```
> Installed 10 packages in 230ms
> + click==8.4.1
> + deepmerge==2.0
> + jinja2==3.1.6
> + markdown==3.10.2
> + markupsafe==3.0.3
> + pygments==2.20.0
> + pymdown-extensions==10.21.3
> + pyyaml==6.0.3
> + tomli==2.4.1
> + zensical==0.0.44
> ```
プロジェクト作成。
```console
uv run zensical new .
```
`README.md` を `docs/docs/index.md` にコピーして実行。
```console
uv run zensical serve
```
色々リンクエラーはあるけど一旦表示された。
## 日・英対応
言語を切り替えられるようにしてみる。
> [Language - Zensical Documentation](https://zensical.org/docs/setup/language/?utm_source=chatgpt.com#site-language-zensicaltoml)
設定は一応できたけど、**`ja/` や `en/` のようにトップレベルでディレクトリを切って別々にビルドしないと厳しそう**。
そのうち[[Zensical]]が[[i18n]]に対応するかもしれないので、今は日本語だけにしておく。
## GitHub Actions 対応
> [!attention]
> 事前に[[リポジトリのドキュメントをGitHub Pagesで公開]]できるようにしておく必要あり。
[[GitHub Actions]]で[[GitHub Pages]]に公開できるようにする。
> [Publish your site - Zensical Documentation](https://zensical.org/docs/publish-your-site/)
リポジトリルートではなく `docs` 配下が[[Zensical]]のルートディレクトリになるので少し変更が必要。
`.github/workflows/docs.yml`
```yaml
name: Documentation
on:
push:
branches:
- main
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/configure-pages@v6
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with:
python-version: 3.x
- run: pip install zensical
- run: zensical build --clean
working-directory: docs
- uses: actions/upload-pages-artifact@v5
with:
path: docs/site
- uses: actions/deploy-pages@v5
id: deployment
```
https://tadashi-aikawa.github.io/jinrai/ にデプロイ。