Open5

Zennとgithub連携でやらかした件

初めての投稿を、投稿後にGithubと連携させようとした顛末記です。。。

ひとまず、Zennで一つ記事を書き上げた後、Githubと連携させようと、

https://zenn.dev/zenn/articles/setup-zenn-github-with-export

を参考にして作業開始。
ひとまず、Githubにリポジトリを作成しないと話にならないので、まずは
sakai-sktech/zenn-contents
を作成した
public、初期ファイルのデフォルトは全て無し(README.md等)

zenn編集用のローカル環境として、ホームフォルダ直下にzennを作成してそこで作業する

zenn-cliのインストール

ローカル環境では、vscodeで編集ープレビューしたかったので、zenn-cliをインストール
手元の環境はちょっとnodeのバージョンが低いけど問題なく動いてくれた

npm i zenn-cliでインストール
~/zenn$ node -v
v12.14.0
~/zenn$ npm -v
6.13.4

~/zenn$ npm i zenn-cli
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@~2.3.2 (node_modules/chokidar/node_modules/fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})
npm WARN markdown-it-anchor@8.4.1 requires a peer of @types/markdown-it@* but none is installed. You must install peer dependencies yourself.
npm WARN zenn@1.0.0 No description
npm WARN zenn@1.0.0 No repository field.

+ zenn-cli@0.1.98
added 128 packages from 104 contributors and audited 129 packages in 20.209s
npm i zenn-cliのWARN
npm WARN markdown-it-anchor@8.4.1 requires a peer of @types/markdown-it@* ...(以下略)

これについては、書いてあるとおり依存関係を手動でインストールすればいい

~/zenn$ npm install @types/markdown-it
...(途中略)
+ @types/markdown-it@12.2.3
added 3 packages from 8 contributors and audited 135 packages in 4.731s
...(以下略)
zenn-cliインストール後動作確認
~/zenn$ npx zenn init

  🎉  Done!
  早速コンテンツを作成しましょう

  👇  新しい記事を作成する
  $ zenn new:article

  👇  新しい本を作成する
  $ zenn new:book

  👇  投稿をプレビューする
  $ zenn preview
  

素晴らしい環境をありがとう!!!
(ここまでは良かった...)

zenn-cliとvscodeの統合

最近は、何でもかんでもvscodeで書く癖がついているので、

https://zenn.dev/negokaz/articles/aa4e12b76d516597a00e

を参考に「VS Code Zenn Editor」を入れました。

https://marketplace.visualstudio.com/items?itemName=negokaz.zenn-editor

negokazさん素晴らしい拡張機能をありがとうございます!!!

(実は、ここでちゃんとプレビューまで確認していればやらかさずに済んだ...笑)

先にエラー画面を公開

Zenn EditorでのWARN!!!

なぜこうなったか

Zennに登録してから、記事を一つ書いて公開しました。ここまでブラウザでの作業で完結していました。
で、記事の編集画面をそのままコピペでvscodeに貼り付け、保存した後、Zenn Editorでプレビューした結果が上の状態です。mdファイルとしては何ら問題は無いのですが、Zenn用の記事として認識するためのメタデータが無いために警告が出たのです(zenn-cliエライ!)。

Githubとの連携の説明にちゃんと書いてあります

ブラウザからコピペで記事内容のmarkdownの内容を貼り付けて使うのではなく、
Zennで途中からGitHubリポジトリ連携をはじめるときの手順:手順2にある「投稿データのエクスポート」機能を使って、投稿データをダウンロード(zipアーカイブされてたデータです)してください。articlesフォルダの中に投稿済みデータ(mdファイル)があるのでそれを使えばOKです。

今回の記事の場合

---
title: "DockerをUbuntu環境にインストールする"
emoji: "📗"
type: "tech"
topics: ["docker", "ubuntu"]
published: true
---

これがZenn用のメタデータで、記事mdファイルの先頭に記述されていないと駄目。前述のダウンロードデータの中にある記事ファイルにはちゃんと入っています。これで、一旦zenn-cliでプレビュー出来る状態にはなっています。

メタデータがキチンと入ったmdファイルをプレビューすると(当然ですが)、このように手元でプレビューしながら記事を書くことが出来ます。

Zenn Editor

そして、最後の難関、既存の投稿済み記事(ブラウザで編集したもの)がある時に、Githubと連携させるために注意しておく必要があるのが次のslugのお話しです。

slugのお話し

自分は、ブラウザで記事の投稿を完結させた後、記事の編集画面からコピペしてvscodeに持ってきて、いざ保存する時に「ファイル名はどうしたらいい??」となりました。ぱっと見、Zennの記事の一覧インターフェースには記事そのもののファイル名が分かるようなものは見当たりません(投稿した記事のurlを見に行かなかった自分に後から絶望しましたw)。

ブラウザから記事を作成、編集するときには「意識せずに」書くことに集中出来るようにしてあるんだなと自分は理解しました。

が、Githubと連携するのに記事とリポジトリ内のファイル名をどうやって紐付けるんだ?

slugはどうやって分かるかというと、ダウンロードデータのarticle内にある記事ファイル名(.mdを除いた部分)がslugそのものです(記事にアクセスしたurlの末尾部分でもわかります)。

自分の最初の投稿記事:「DockerをUbuntu環境にインストールする」の場合、slugは0eae52218f16feという文字列でした。

Githubとの連携

このスクラップの最初に示した

https://zenn.dev/zenn/articles/setup-zenn-github-with-export
通りに連携した。
メタデータについての理解もOK、slugも理解した。
後は、投稿記事用のmdファイルを編集して、いつもどおりのgitの使い方でgithubにpushすれば、記事を更新してくれます。

なんて便利な仕組みなんでしょうか!!!素晴らしい!!!

Githubとの連携が無事に出来た様子

上段:無事に連携後の様子(更新された情報がわかります)
下段:最初、slugは合わせたけど、メタデータが無い状態でgithubにpushしました。すると(当然ながら)連携できない旨のエラーが記録されています。
また、githubにコミットしたときのコメントも表示されているのがわかります。

最後に

何でもそうですが、説明はキチンと最後までよく読みましょう!!!>(自分)

皆さん、最初の投稿は、Zennがどんなものか試してみようとブラウザで完結させる方も多いと思います。そんな皆さんが、自分のような失敗しないようにという願いを込めて締めくくります。

ログインするとコメントできます