📑

ZennにGitHub連携で記事投稿！ハマった点とメリット・デメリットを解説

に公開
Zenn
tech

概要

実務経験は積んできたものの、技術的な基礎部分の学び直しが必要だと感じていました。

学んだ知識の定着とアウトプットの場としてZennを選び、記事投稿を始めることに。

その際、GitHub連携での投稿が可能であることを知り、今回試してみました。本記事では、実際にGitHub連携を使ってみてハマった点や、そのメリット・デメリットについて詳しく解説します。

初めて記事を投稿するにあたって

初めての投稿なのでzennのガイドラインを読んで見ました。

初心者には大変ありがたいことにどのようなポイントを押さえた記事にすればいいかが書かれています。

ぜひ一度目を通されてから初投稿されてみたはいかがでしょうか？

参考記事

GitHub連携でハマったポイント

ZennのGitHub連携機能を使うには、Zenn CLIの規約に沿ったファイル管理が必要です。

筆者も手探りで試した結果、いくつかエラーに遭遇しました。ここでは、特にハマりやすかったポイントとその解決策を紹介します。

  • ディレクトリ名の規約にしたがっておらずエラー。直下に規定のディレクトリ名が必要みたいです。

    • 解決策: 記事はarticlesディレクトリ、本はbooksディレクトリ直下に配置する必要があります（例: articles/my-first-article）。

  • ファイル名の規約に従っていなくてエラー

    • 解決策: 記事のファイル名はYYYY-MM-DD-slug.mdの形式（例: 2023-10-27-zenn-github-post.md）で命名する必要があります。（slugとは英数字、アンダースコア、ハイフンからなる短いラベル文字列のこと）

  • 記事のメタデータの記述が足りなくてエラー

    • 解決策: ファイルの冒頭にFrontMatter（YAML形式のメタデータ）を正しく記述する必要があります。最低限、title, emoji, type, topics, publishedの項目は必須です。

  • FrontMatterとはmarkdownの冒頭に記述するメタデータ

---
title: "ZennにGitHub連携で記事投稿！ハマった点とメリット・デメリットを解説"
  emoji: "📑"
type: "idea"
topics: ["zenn"]
published: true
---

GitHub連携してみてのメリット・デメリット

メリット

  • githubの作業フローを通しての投稿になるため、レビューを受けてからの投稿ができる。チームで記事の品質を担保したい企業アカウントや、複数人で共同執筆する場合に特に有効そう。
  • 他の記事投稿サイトでもmarkdownを使うのでzennがサービス終了しても今までの投稿資産が失われない
  • 自分のエディターで書きたい人は良さげ
  • バージョン管理ができるため、記事の変更履歴を詳細に管理でき、安心して執筆を進められます。

デメリット

  • github連携設定の手間がかかる
  • ディレクトリやファイル名の規約に従う必要がある
  • 実際にzenn上で表示されるプレビューがしづらい。zenCLI使えばいいが環境構築に手間がかかる

まとめ

いくつかの学習コストはかかりますが、筆者は今後もGitHub連携での記事投稿を続けていく予定です。

普段からGitを使った開発に慣れているエンジニアにとっては、手慣れた作業フローで記事が書ける点が大きな魅力です。

また、Markdown形式で資産を管理できるため、Zenn以外のプラットフォームへの展開も容易になるでしょう。

初期設定でいくつかエラーに遭遇しましたが、それもまた記事のネタになるというポジティブな経験でした。勢いで行動した自分を褒めたいと思います。

今後の展望

他にも記事投稿サイトがあるので、apiが公開されているサイトについてはgithubActionsなどで連携ができたらマルチ記事投稿ができるかもしれません。

qiitaはapiが公開されているみたいなのでチャレンジしてみようと思います。

Discussion