Zenn使用開始

Masaki

Zennアカウントを作成した。
まず気軽に書けそうなスクラップから使ってみたいので、使用開始時のあれこれを書き留めてみる。

Masaki

Zennトップページの最下部の使い方のZennの2種類の執筆方法についてを読む。
手元の環境で編集したいので、「GitHubリポジトリとの連携機能」のほうを使いたい。

Masaki

GitHubリポジトリでZennのコンテンツを管理するのGitHubとの連携手順にしたがって設定する。
まず「1. リポジトリを作成する」を下記のとおり行った。

GitHubの自分のアカウントのページを操作して、適当な名前の空のリポジトリを作成
ローカル環境にcloneし、下記を行う
- 適当な中身のREADME.mdをmainブランチにcommit (Zenn連携としては必須ではないようだが、Gitリポジトリとして完全に空だと扱いにくいため)
- mainブランチからdevelopブランチを作成。mainブランチはZenn連携用に、developブランチは編集作業用に使う予定
ローカル環境からGitHubへとpush
GitHubのWebページ上でブランチの状態などを確認

Masaki

「2. ダッシュボードから連携する」を行う。

Zennにログインした状態で、ダッシュボードのデプロイ管理を開く
「リポジトリを連携する」を選択。「Only select repositories」をチェックし、目的のリポジトリを選択し、「Install & Authorize」を選択
ダッシュボードのデプロイ管理が表示される。設定したリポジトリが連携中のリポジトリとして表示されていればOK

なお、「デプロイ対象ブランチ」は、何も指定しなかったがmainになっていた。defaultブランチだからか?

Masaki

今日はここまで。続きは下記。

上記の2を読むと、Zenn CLIで扱えるのは記事(Article)と本(Book)の2つのようだ。
スクラップは対象外なのか。

Masaki

「Zenn CLIをインストールする」を行う。

手元の環境はDebian Bullseye (11.3) for amd64。
Node.jsを常用していないので、まずそのインストールから。

古くてイマイチと言われている、DebianそのままのNode.jsとnpmをインストールするところから開始。

$ sudo apt install nodejs npm

編集用リポジトリのワーキングコピーのディレクトリトップで、下記を実行。

$ npm init --yes
Write to .../package.json:
...
$ npm install zenn-cli
npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: 'zenn-cli@0.1.114',
npm WARN EBADENGINE   required: { node: '>=14.0.0' },
npm WARN EBADENGINE   current: { node: 'v12.22.12', npm: '7.5.2' }
npm WARN EBADENGINE }

added 1 package, and audited 2 packages in 1s

found 0 vulnerabilities
$

required: { node: '>=14.0.0' } とあるので、Node.jsの14.0.0以上をインストールする必要がある。やり直し。

Masaki

下記を参考に、Node.jsのv18.xをインストールすることにした。

手順はNodeSource Node.js Binary Distributionsにしたがう。
下記を実行した。

$ curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
$ sudo apt install -y nodejs

これにより、Node.js 18.4.0とnpm 7.5.2がインストールされた。

$ apt show nodejs
Package: nodejs
Version: 18.4.0-deb-1nodesource1
...
$ apt show npm
Package: npm
Version: 7.5.2+ds-2
...

なお、削除したいときは、/etc/apt/sources.list.d/nodesource.listを削除すればよさそう。
(鍵も消すならもう少し操作が必要)

Masaki

再度、「Zenn CLIをインストールする」の「1. CLIをインストールする」を行う。

編集用リポジトリのワーキングコピーのディレクトリトップで、下記を実行。

$ npm init --yes
Write to .../package.json:
...
$ npm install zenn-cli

added 1 package, and audited 2 packages in 1s

found 0 vulnerabilities
npm notice 
npm notice New minor version of npm available! 8.12.1 -> 8.13.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v8.13.2
npm notice Run npm install -g npm@8.13.2 to update!
npm notice 
$

今度は問題なく完了。

ついでに、noticeに出ているnpm更新も行っておく。
npmはシステム領域にインストールされているため、root権限で行う。

$ sudo npm install -g npm@8.13.2

Masaki

続いて「2. Zenn用のセットアップを行う」を実行。

$ npx zenn init
Generating README.md skipped.
...

問題なさそう。プレビューしてみる。

$ npx zenn preview
  http://localhost:8000

Webブラウザで http://localhost:8000 にアクセスしたら、無事に表示された。完了。

Masaki

Zenn CLIによって追加されたファイルとディレクトリを、編集用のdevelopブランチにcommitしておく。

$ git status
On branch develop
Your branch is up to date with 'origin/develop'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .gitignore
        articles/
        books/
        package-lock.json
        package.json

nothing added to commit but untracked files present (use "git add" to track)
$ git add .gitignore articles books package-lock.json package.json
$ git commit -m 'Add files for Zenn CLI.'
[develop 377b285] Add files for Zenn CLI.
 5 files changed, 59 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 articles/.keep
 create mode 100644 books/.keep
 create mode 100644 package-lock.json
 create mode 100644 package.json

Masaki

記事の作成を試してみる。
テスト記事を作り、更新し、試し終わったら削除したい。

参考資料は下記。

GitHubリポジトリ連携を使う場合は、おおまかには下記のようになるようだ。

作成
1. ローカルで編集
2. 登録したブランチに反映させ、記事をデプロイ (投稿)
更新
1. ローカルで編集
2. 登録したブランチに反映させ、記事を更新
削除
1. Zenn.devのWebページ上のダッシュボードで操作して削除

Masaki

Zenn CLIで記事・本を管理する方法のCLI で記事（article）を管理するの記事の作成にしたがい、テスト記事を作成する。

まず、developブランチにて操作。

$ npx zenn new:article
created: articles/a31f8e8e1f91ad.md

作成直後のarticles/a31f8e8e1f91ad.mdの内容は下記のとおり。

---
title: ""
emoji: "😽"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: []
published: false
---

titleは"test"、topicsは"test"1つのみ、publishedはtrueにした。
emojiとtypeはそのまま。
末尾に本文として「テスト。」の1行のみを追加した。
なお、形式はyamlとのことなので、topicsに追加するものはダブルクォートで囲んでおいた。

編集後の内容は下記のとおり。

---
title: "テスト"
emoji: "😽"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: ["test"]
published: true
---
テスト。

プレビューを表示するために、下記を実行。

$ npx zenn preview
  http://localhost:8000

Webブラウザでhttp://localhost:8000を開いた。
ページ左のarticlesに作成中の記事「テスト」があり、クリックすると記事の内容が表示された。問題なし。
なお、やってみて気づいたが、プレビューを表示したまま元ファイルを編集・保存すると即時反映される。(そりゃそうか)

確認が終わったので、プレビューをCtrl-Cで止めて、ファイルをdevelopブランチにcommitし、GitHubに反映させる。

$ git add articles/a31f8e8e1f91ad.md
$ git commit -m 'Add a test article.'
$ git push

GitHubのWebページを操作し、developブランチからmainブランチへのpull requestを作成し、マージを実行。

Webブラウザにて、Zennの記事の管理を開く。
「テスト」という記事ができていることを確認した。

テスト目的だったので、publishedはfalseのほうがよかったかもしれない。
また、今回は記事作成時にシンプルにnpx zenn new:articleとしてslugを自動で付与させたが、実際の記事を書くときにはslugを自分で決めたしたほうが管理しやすい。slugについては、下記を参考にすればよさそう。

Zennのスラッグ（slug）とは

Masaki

記事の更新を試す。

手元のdevelopブランチにて操作。
articles/a31f8e8e1f91ad.mdに対して、下記の変更を行った。

publishedをtrueからfalseへと変更
末尾に「1行追加。」を追加

記事作成と同様に、commitし、pushし、GitHub上でpull requestを使ってdevelopからmainへとマージ、を行った。
Zenn上の自分の「テスト」という記事が「公開」から「下書き」に変わり、末尾に「1行追加。」が追加されていることを確認した。問題なし。

Masaki

Zenn CLIで記事・本を管理する方法の記事の削除にしたがい、テスト記事を削除する。

Webブラウザにて、Zennの記事の管理を開く。
テスト記事のタイトルの右端の下向き矢印をクリックしてメニューを開き、「削除する」を実行。
削除された。

手元のdevelopブランチでも記事を削除しておく。
articles/a31f8e8e1f91ad.mdを削除し、commit・pushし、mainにも反映させた。

Masaki

VSCode (Visual Studio Code)を使っているので、VSCode上でプレビューしながら編集できるようにする。
参考にした記事は下記。

Zenn の執筆を支援する VSCode 拡張 Zenn Editor

VSCode上の「拡張機能」にて、下記のZenn Editorをインストールする。

Zenn Editor - Visual Studio Marketplace

作成とプレビューしながらの編集を試してみた。下記のような感じ。

記事の作成
1. VSCodeのExplorerの最下段のZENN CONTENTSを開く
2. 紙のアイコンのZenn Editor: Create New Articleをクリックすると、新しい記事のファイルが作成され、VSCode上でそのファイルが開かれる
プレビュー付き編集
1. 編集画面の右上のzのついたアイコンのZenn Editor: Open Previewをクリックすると、画面が2分割されてZenn Editor Previewが表示される
2. ファイルを保存するたびにプレビューに反映される

記事に不備があると、例えば「title(タイトル)を文字列で入力してください」などとプレビュー画面に表示してくれるので便利。
ファイルとして保存したあとは、通常どおりGitやGitHubを使って記事に反映させればよいということのようだ。

画像のアップロードは、まだ試していない。必要になったら試す。

Masaki

スクラップの下書きを手元の別の場所で管理していたが、Zennコンテンツ管理用のリポジトリにまとめることにした。
単に置き場所を統合して一元管理するだけで、実際のスクラップへの転記はこれまでどおり手動で行う。

リポジトリ内のarticlesとbooksの並びにscrapsディレクトリを作り、いくつかファイルを置き、mainブランチに反映させた。

Webブラウザにて、Zennのダッシュボードのデプロイ管理を開き、最近のデプロイを確認。
デプロイが成功して、「更新されたファイルはありません」となっていればOK。
scrapsディレクトリを変更しても、記事や本に影響が及ぶことはない。

Masaki

GitHubリポジトリ連携で画像をアップロードする方法を参考に、記事に画像を貼ってみる。

リポジトリ内のarticlesとbooksの並びにimagesディレクトリを作り、適当なJPEG形式の画像ファイルをexample.jpgとして置く。

新しいテスト用の記事を作成し、下記のような内容にする。

---
title: "画像埋め込みのテスト"
emoji: "🙆"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: ["image"]
published: false
---
画像を貼ってみる。
![example](/images/example.jpg)

プレビューで適切に表示されることを確認する。

mainブランチに反映させ、下書き記事として反映されたことを確認した。
だが、下書きの状態ではプレビューしても画像が表示されなかったため、公開にして保存。
画像が表示されたことを確認した。問題なし。

後片付けとして下記を行った。

Zennのダッシュボードでテスト用の記事を削除
リポジトリからテスト用のファイル群を削除

なお、VSCode拡張のZenn Editorの[画像アップロードページを開く]という機能は使用しなかった。この記事の公開日は2021-04-29、GitHubリポジトリ連携で画像をアップロードする方法の記事の公開日は2021-07-19であることから察するに、GitHubリポジトリ連携での画像アップロード機能の実装のほうが後だということだろうか。

Masaki

Zennを使う準備がだいたい整った。当面、下記のように使おうと考えている。

ある程度まとまった内容があれば、記事にする
- 長くても短くてもよいが、何か1つのまとまりをもっていて、それを題名に示せることを条件にする
何らかのまとまりのある作業を始めたときは、スクラップを作成して記録をつける。完了後は:
- 単なる作業記録どまりなら、そのまま閉じる
- 作業記録からまとまった知見を抽出できるなら、記事にする。複数取り出してもよい

まず記事とスクラップに慣れるようにする。
本については、そのうち考えてみたい気はするが、少なくともしばらくは除外。

Masaki

「なぜZennで記事やスクラップを書くのか」については、下記のように考えている。
たまに迷ったり変わったりすることもあるので、今の考えをまとめておく。

なぜ作業記録を書くのか
- 以降に似た作業をするときに読み返す価値があるため (公開することとは無関係)
なぜ記事を書くのか (価値があると思ったものだけ記事にする前提で)
- 読み返す価値があるため (これも公開することとは無関係)
- 単なる作業記録よりも価値が高いため
なぜ公開するのか
- 他人の目にさらされるプレッシャーがあると、品質が上がるため
- フィードバックを得られるかもしれないため
- 承認欲求を満たすため
なぜZennを選んだのか
- いろいろな公開手段から選択する際に、考慮した主な条件は下記のとおり
  - 読みやすい
  - 書きやすい
  - 規約と運営方針が適切
  - 継続性がある
    - 運営方針のよさと技術の高さの両方が求められる
  - 収益化の可能性がある
- 過去にスラッシュドット・ジャパン(現在はスラド)とはてなダイアリー(すでに閉鎖)を若干だが使っていたので、その経験を踏まえている
- Zennを選ぶにあたっては、僕がZennを選んだ理由を参考にさせていただいた

公開することのくだりについては、この手の手段で過去にフィードバックを得たことがほぼないため、経験が浅すぎて正直よくわからない。この観点でZennが他の手段と比較してどうなのかも、自分では判断がつかない。まあ、しばらく継続してみよう。

Masaki

記事やスクラップを作成するときに参考にするつもりのもの。
何を書くのかはまず自分で考えるつもりだが、投稿するまでには下記を決める必要がある。

トピックの選定
- Popular topicsを眺めて、適切なものを探す
- 検索する
記事の場合、絵文字の選定: 特定の技術について書く場合、それを表す絵文字は普通ないので、なにか選ぶ必要がある
- Emojipediaで探す
- 使いそうかなと思ったものは:
  - Tips: 💡 (Light Bulb)
  - 初心者: 🔰 (Japanese Symbol for Beginner)
  - メモ: 📝 (Memo)
  - 考え中: 🤔 (Thinking Face)

このスクラップは2022/07/09にクローズされました