くらげになりたい。

くらげのようにふわふわ生きたい日曜プログラマなブログ。趣味の備忘録です。

トップ > Nuxt.js > Webのドキュメントサイトを作るためにDocusに入門してみた

Webのドキュメントサイトを作るためにDocusに入門してみた

Nuxt.js Nuxt-Content Docus

Nuxtでできてるドキュメントサイト用のテーマの、
Docusがよさそうなのでいろいろ試したときの備忘録(*´ω｀*)

使われているNuxtモジュール

以下のモジュールをベースとしてる感じ。
それぞれのComposablesや設定なども見るといろいろできる。

プロジェクトの作成

ドキュメントにある通り、以下を実行すると、
テンプレートから作成してくれる。

$ npx nuxi@latest init -t themes/docus
$ cd docs
$ npm install
$ npm run dev

デフォルトのフォルダはdocs。
サンプルとしてDocusのサイトのデータが入っているよう。

事前準備/環境構築

上記を踏まえ、適宜ファイルを用意しておく。
VSCodeの拡張機能を無効化しておくか、 .prettierignoreや.markdownlint.ymlで無効化しておくと良い。

$ cat .prettierignore
**/content/**/*.md

$ cat .markdownlint.yml
default: false

ディレクトリ構成

content/         ... markdown file
  index.md
public/          ... static assets
  favicon.ico
app.config.ts    ... Docusの設定
tokens.config.ts ... デザイントークンの設定
nuxt.config.ts   ... Nuxtの設定

Docusの設定(app.config.ts)

サイト全体の設定関連。docus配下で設定。

titleやdescriptionのmeta関連以外にも、
ヘッダー(header)やサイドバー(aside)、フッター(footer)のレイアウト関連、

export default defineAppConfig({
  docus: {
    title: 'Docus',
    description: 'My Docus Project',
    url: 'http://docus.dev'
    // ...
  }
})

デザイントークンの設定(tokens.config.ts)

import { defineTheme } from 'pinceau'

export default defineTheme({
  color: {
    primary: {
      50: '#F1FCFF',
      // ...
      900: '#001A1F'
    },
  },
  // ...
})

こんな感じで色などのデザイントークンが用意されている。
変更したい部分を追加で定義すればOK。

細かい設定のドキュメントは無いため、以下を見ながら。

ページの設定

ページに関する設定はNuxt Content同様に、
Front-Matterで設定する。

---
# layout: page
title: Home
description: this is home page
# redirect: ""
image: https://my-docsite.com/ogp.png

### Docs layout options
## layout/default.vueを使っているときのみ有効
aside: true
toc: true
bottom: false  # 前後の記事のリンク

### Navigation options
## asideなどのナビゲーションの設定
# navigation: false
# or
navigation:
  title: ホーム
  icon: mdi:home # nuxt-iconも使える

#### override `docus.xxx` app.config.ts
### app.configの設定も上書きできる
main:
  fluid: true
titleTemplate: Home

#### Front-Matter of nuxt-content
### nuxt-contentのも使える
head:
  - meta:
    name: foo
    contnet: bar
---

index.mdがないディレクトリ

こんな感じで、/1.introduction/にアクセスされたときには、
/1.introduction/1.getting-started.mdを表示したときなど。

content/1.introduction/
├── _dir.yml
├── 1.getting-started.md
├── 2.project-structure.md
├── 3.writing-pages.md
└── 4.configuration.md

Nuxt Contentのお作法に従い、
_dir.ymlを配置して、リダイレクトさせればOK。

icon: ph:star-duotone
navigation.redirect: /introduction/getting-started

コンポーネントのカスタマイズ

同じ名前のコンポーネントを用意すれば、上書きできる。

例えば、カラーモードの切替を表示させたくない場合、
ThemeSelect.vueを空で作ればOK。

<!-- ThemeSelect.vue -->
<template>
  <div />
</template>

パスプレフィックスなどもあるので、
components配下が同じ構成になるように、
nuxt.config.tsを設定しておくといいかも。

export default defineNuxtConfig({
  components: [
    { path: './components/app', prefix: '', global: true, },
    { path: './components/docs', prefix: '', global: true, },
    { path: './components/', }
  ],
})

おまけ | その他、拡張機能

以上!!

絶賛開発中なので、まだまだドキュメントやconfigが追いついてないけど、
issueなどをみてるとどんどん機能が増えていきそうで楽しみ。

自分でカスタマイズできるので、だいぶ楽に作れそう(*´ω｀*)

参考にしたサイト様