VuePress 플러그인 개발 도전(로컬 편)

이 글은 North Detail Advent Calendar 2019 8일째 글입니다.
2020/04/02 추기
이 글도 North Detail 블로그에 투고되었습니다.
https://www.northdetail.co.jp/blog/448/

오프닝

지난해 VuePress를 알게 된 후 작은 문서를 정리하는 사이트를 만드는 데 자주 쓰인다.
마크다운으로 서류를 엉망진창으로 쓰면 금방 느낌이 좋은 사이트로 만들 수 있어 편리해요.
다만, 모든 내용을 내놓기 위해서는 사이드바에서 메뉴를 만들어야 하는데, 그게 상당히 귀찮다고 생각합니다.
"그럼 플러그인을 만들면 되겠죠?"
그래서 도전해 봤어요.
이번에는 NPM의 포장이 아니라 로컬에 배치된 모델입니다.
또한 작성된 Markdown 파일을 알파벳순으로 표시하기만 하면 됩니다.
(단지 이것뿐이지, 간단한 사이트라면 충분히 수월할 것이다.)

준비

우선 VuePress 프로젝트를 진행하겠습니다.

$ mkdir sample-project
$ cd sample-project
$ yarn add -D vuepress
$ mkdir docs

완료 후 다음 파일을 순서대로 작성합니다.
구축 등을 편리하게 하기 위해package.json에 추가"scripts".
package.json

{
  "devDependencies": {
    "vuepress": "^1.2.0"
  },
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

예를 들어 여러 Markdown 파일이 생성되었습니다.
docs/README.md

# 誰かの冒険

プラグイン作成のための冒険。

## 第1章: 旅立ち

[旅立ちます。](/01-departure)

## 第2章: 帰還

[ただいま。](/02-return)

docs/01-departure.md

# 第1章: 旅立ち

旅立ちます。

## 1.1: お城

王「ひのきの棒を与えよう。」

docs/02-return.md

# 第2章: 帰還

ただいま。

## 2.1: お城

王「死んでしまうとは何ごとだ。」

이 상태에서 개발 서버를 시작하고 화면을 보십시오.

$ yarn docs:dev

브라우저로 표시해 보세요 http://localhost:8080/.

현재 사이드바가 설정되어 있지 않아서 아무것도 표시되지 않습니다.

플러그인 만들기

그 전에 사이드바를 설정한 상태에서.

이런 느낌으로 쓰세요.
docs/.vuepress/config.js

module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/01-departure',
      '/02-return',
    ]
  }
}

그러면 브라우저는 당연히 사이드바에 메뉴를 표시합니다.

표시 확인 후 필요 없음 sidebar 을 삭제하십시오.

플러그인 설정 가져오기

그럼 플러그인을 만들어봅시다.
이번에는 로컬 플러그인의 JavaScript를 읽습니다.
Using a Plugin | VuePress
docs/.vuepress/config.js

module.exports = {
  plugins: [
    require('./auto-sidebar')
  ]
}

docs/.vuepress/auto-sidebar 디렉토리에 필요한 파일을 만듭니다.

쓰기 플러그인

말하자면, 어떻게 해야만 사이드바를 바꿀 수 있습니까?
실제로 한꺼번에 정보를 찾지 못해 상당한 시행착오를 겪었다...
그중에 App Level Enhancements의siteData를 조작하면 좋으니까 여기를 만지작거릴 거예요.
만든 페이지 정보는 siteData.pages 에 포함되어 있으며, 메뉴와 비슷한 그룹을 만듭니다.
생성된 그룹은 siteData.themeConfig.sidebar 에 저장하면 됩니다.
그러면 사이드바에 메뉴를 표시하는 플러그인을 실제로 작성해 봅시다.
다양한 설정 내용(API)이 있으므로 자세한 내용은 공식 문서를 확인하십시오.
Writing a Plugin | VuePress
이번에는 플러그인의 응용 프로그램 강화 기능을 설정합니다.
이것은 enhanceAppFiles로 설정하면 됩니다.
docs/.vuepress/auto-sidebar/index.js

const path = require('path')

module.exports = (option, context) => ({
  enhanceAppFiles: path.resolve(__dirname, 'enhanceAppFile.js')
})

이 설정에서 실제 처리는 같은 디렉터리enhanceAppFile.js에서 이루어진다.
그럼 우리 실제 처리를 한번 봅시다.
docs/.vuepress/auto-sidebar/enhanceAppFile.js

export default ({ Vue, options, router, siteData }) => {
  const sidebar = []

  // regularPath を使うと、ページトップの `#` で宣言した内容をタイトルとして使ってくれる。
  for (const page of siteData.pages) {
    sidebar.push(page.regularPath)
  }

  // regularPath を昇順にソート
  sidebar.sort((page1, page2) => {
    return page1.localeCompare(page2)
  })

  siteData.themeConfig.sidebar = sidebar
}

확인

개발 서버yarn docs:dev가 시작되면 잠시 종료하고 다시 시작하십시오.
그리고 다시 브라우저로 http://localhost:8080/ 를 표시합니다.
설정 쓸 때랑 똑같이 뜨네!
여기서 마크다운의 제목을 변경하고 파일을 추가하면 실시간으로 변경·추가되는 것도 확인할 수 있을 것 같습니다.
예를 들어, 다음 Markdown을 추가하면
docs/03-legend.md

# 終章: そして伝説へ

お星さまになります。

그것은 곧 브라우저에 반영될 것이다.

이렇게 하면 목적을 달성할 수 있다!
제작된 부분은 아래 자료고에 넣으세요.
https://github.com/tacck/vuepress-plugin-sidebar

앞으로

구조를 좀 더 중시하는 사이트에서 도입할 수 있도록 좀 더 하고 싶습니다.

옵션

추가 고정 메뉴 등일

그룹 지원

다국어 지원

NPM 패키징일

천천히 도전할게요.

FAQ

Q. 플러그인을 수정할 때 반영되지 않습니까?
A. 로컬 서버를 다시 시작합니다.좋은 방법이 있으면 저에게 알려주세요.
Q. 설정 요소가 어디에 있는지 모르겠다.
A.자신도 잘 몰라요.console.log() 열심히 했으니까 좋은 방법이 있으면 알려주세요.
Q. 순서를 좀 더 제어하고 싶습니다.
A. 파일 이름으로 노력하겠다는 구상입니다.정렬된 부분을 좋아한다면 마음대로 할 수 있으니 플러그인을 확장하십시오.
해봤어요.https://www.npmjs.com/package/vuepress-plugin-sidebar   ↩