Mardown 문서 로컬 관리 및 동기화

개요

Markedown에는 문서를 편집하고 공개할 수 있는 서비스가 많지만, 브라우저가 아닌 로컬에서 문서를 쓰고 동기화하는 CLI 도구를 만들어 봤습니다.

marksync (GitHub)

목표(이런 사람에게)

숙련된 편집기로 편집하고 싶습니다.

공개된 문서의 모판을 손 옆에서 관리하고 싶다.

동일한 문서를 여러 서비스에 공개하고 싶습니다.(회사 내부 및 회사 외부 등)

꼼꼼하게 수정하고 제때에 반영해 주시기 바랍니다.

여러 문서를 정리하여 수정하고 싶습니다.

이미지 등 첨부파일을 수정할 때 다시 올리는 것은 번거롭다.

서비스가 죽었다가 다시 살아날 때 바로 옮겼으면 좋겠어요.

설치 방법

필요 환경

Java

npm

설치하다.

npm에서 공개됐습니다.다음은 갈 수 있을 것 같다.

npm install -g marksync

환경 구성 파일 만들기

문서에 배치된 디렉토리 구조의 맨 위에 있습니다.markesync 파일을 만들고 동기화된 서비스와 인증 정보를 기술합니다.

Qiita의 경우

SERVICE=qiita
QIITA_USERNAME=(Qiitaのユーザー名)
QIITA_ACCESS_TOKEN=(Qiitaのアクセストークン)

액세스 토큰은 설정 > 애플리케이션 > 개인 액세스 토큰으로 발송됩니다.

esa.의 경우

SERVICE=esa
ESA_TEAM=(esa.ioのチーム名)
ESA_USERNAME=(esa.ioのユーザー名)
ESA_ACCESS_TOKEN=(esa.ioのアクセストークン)

방문 영패는 SETTINGS 애플의 페르소나 access token이 발행한다.

Zenn의 경우

젠은 API가 아닌 지아이허브 창고를 통해 관리하기 때문에 사전에 창고를 만들어 협업한다.

SERVICE=zenn
ZENN_USERNAME=(Zennのユーザー名)
ZENN_GIT_DIR=(ローカルに保存するリポジトリパス)
ZENN_GIT_URL=(GitHubリポジトリのURL)
ZENN_GIT_BRANCH=(リポジトリのブランチ名)
ZENN_GIT_USERNAME=(GitHubのユーザー名)
ZENN_GIT_PASSWORD=(GitHubのパスワード)

Personal accesst token을 사용할 때는 다음과 같이 설정하면 됩니다.

ZENN_GIT_URL=https://(Personal access token)@github.com/(ユーザー名)/(リポジトリ名).git
ZENN_GIT_USERNAME=(Personal access token)

사용법

서비스에서 문서 가져오기

다음 명령을 사용하면 로컬에서 서비스에 등록된 모든 문서를 포착할 수 있습니다.그러나 문서에 사용된 이미지와 같은 첨부 파일은 가져올 수 없습니다.
각 문서 indexmd와marksync.xxx.yml 파일이라는 디렉토리를 생성합니다.

새 문서 작성

폴더를 만들고 그 안에 index를 만듭니다.MD 파일을 만듭니다.첫 번째 행은 반드시 #(제목)으로 지정해야 합니다.다음 명령을 사용하여 문서의 메타데이터 파일을 생성합니다.

marksync import -o (出力先ディレクトリ)

메타데이터 변경

Qiita의 경우

marksync.qiita.yml의 다음 내용을 편집합니다.자세한 내용은 API 문서를 참조하십시오.

marksync new

esa.의 경우

marksync.esa.yml의 다음 내용을 편집합니다.자세한 내용은 API 문서를 참조하십시오.

private: true
tags:
- name: "tag"
  versions: []

Zenn의 경우

marksync.zenn.yml의 다음 내용을 편집합니다.자세한 내용은 기사 작성Zenn CLI로 기사·문서 관리 방법을 참조하십시오.

tags:
- "tag"
category: "category"
wip: true

업데이트 확인

다음 명령을 사용하여 각 문서가 업데이트되었는지 확인합니다.

type: "tech"
topics: []
published: false

문서가 업데이트되면 다음 명령을 통해 차이를 확인할 수 있습니다.

$ marksync status
  ./docs/doc1: not modified.  ★変更なし
! ./docs/doc2                 ★変更あり
+ ./docs/doc3                 ★新規

동기

다음 명령은 문서를 서비스와 동기화(작성/업데이트)합니다.

$ marksync diff

도구 이외의 방법으로 서비스 문서가 편집된 것을 발견하면 안전을 위해 업데이트되지 않습니다.이 때-f 옵션을 추가하여 덮어씁니다.
문서에서 참조하는 로컬 파일을 첨부 파일로 자동으로 업로드할 수 있습니다.

esa.io에서 업로드 API를 사용하여 업로드합니다.특별한 설정은 필요 없어요.

Qita/Zenn에 파일을 업로드하는 API가 없기 때문에 AWS에서 자신의 공용 S3 구간을 준비해야 한다(후술).설정이 없으면 첨부 파일이 업로드되지 않습니다.

S3 통에 첨부 파일 업로드

업로드할 S3 통을 만듭니다.(예: hirose-public)

$ marksync update

.markesync에서 다음과 같이 설정합니다.

aws s3 mb s3://hirose-public

AWS 액세스 시 인증 정보는 AWS CLI 에서 설정한 정보를 사용합니다.

UML 변환

PlanetUML에 기술된 내용은 그림과 같습니다.

esa.io에서 그래픽으로 직접 표시됩니다.

Qita/Zenn에서 이미지로 변환하여 첨부 파일로 업로드합니다.

최후

자기만을 위한 도구라 문제가 많을 수 있어요.
수요는 없는지 모르겠지만 일단 공개했다.피드백을 받을 수 있었으면 좋겠어요!