Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/noraworld/devlog
A repository where articles for developers are managed
https://github.com/noraworld/devlog
blog devlog devlogs github markdown
Last synced: about 2 months ago
JSON representation
A repository where articles for developers are managed
- Host: GitHub
- URL: https://github.com/noraworld/devlog
- Owner: noraworld
- Created: 2021-02-20T05:24:49.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-06T07:41:35.000Z (9 months ago)
- Last Synced: 2024-05-02T05:54:13.450Z (8 months ago)
- Topics: blog, devlog, devlogs, github, markdown
- Language: SCSS
- Homepage: https://zenn.dev/noraworld
- Size: 1.03 MB
- Stars: 4
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
# 技術記事置き場 (日本語)
日本語の技術記事のマスタデータを管理するためのリポジトリである。
[このリポジトリの GitHub Webhook のステータス](https://github.com/noraworld/developers-blog-content-ja/settings/hooks/285310144)
## Git リポジトリで管理する理由
Qiita のような技術記事を投稿するプラットフォームはいろいろあるし、なんなら技術記事専用のプラットフォームでなくとも、はてなブログのようなブログプラットフォームに投稿することもできる。
しかし、これらのプラットフォームがサービス終了したり、または、すでに利用しているプラットフォームよりも魅力的に感じた別のプラットフォームを見つけたりした際に、今まで投稿したすべての記事を移行しなければならない。サービスが終了してしまえばデータは失われるし、別のプラットフォームに移行する際はデータの移行がめんどくさいと感じる。データの安全性・利便性を考慮して、技術記事のマスタデータは Git で管理したいと思った。
## Git リポジトリで管理しようと思ったきっかけ
きっかけとしては、メインで利用するプラットフォームを Qiita から Zenn に移行しようと思ったことである。そのため、技術記事のマスタデータとしての役割を果たすが、現時点ではディレクトリ構成やファイル構成などは Zenn のフォーマットに準拠する形で管理されている。
2016 年 2 月 16 日に Qiita に技術記事を初投稿してから 2021 年 2 月 20 日現在でちょうど 5 年経つが、この 5 年間、技術記事は Qiita に投稿してきた。
Qiita は SEO がとにかく強力で、かなりの頻度で Qiita の記事がヒットするし、検索クエリによっては自分自身の技術記事がトップに表示されることも稀ではない。だからたくさんの人に見てもらえるし、IT 企業へのアピールにも利用できるし、逆に「Qiita の記事を拝見しました」というメッセージを企業側からいただくこともある。
しかし、知名度や転職の材料にはなるが、いくら Qiita で記事を投稿しても、お金を稼ぐことはできない。それで Qiita から Zenn に移行しようと決めた。1 ヶ月ほど前に友人が Zenn に技術記事を投稿しているのを見て、Zenn について調べてみると、GitHub リポジトリをマスタデータとして記事を投稿できる点と、お金を稼ぐことができる点に魅力を感じて移行を決意した。実際、Zenn としても、[情報を発信するエンジニアが対価を得られるようにすることをコンセプトとしている](https://zenn.dev/about)。
「移行」という言葉を使用しているが、実際には Qiita はやめない。今のところは、今後も継続して Qiita に投稿しようと思っている (つまり Qiita と Zenn の同時投稿) が、あくまでメインは Zenn で、Qiita はサブみたいな位置づけにしようと思っている。Qiita は知名度向上や転職材料のために継続し、Zenn は副業として技術記事でお金を稼ぐため、あるいはマスタデータとして Git で技術記事を管理するついでとして、開始する。
なお、Qiita への投稿は自動で行われる。GitHub Webhook & GitHub API v3 & Qiita API v2 を利用して、このリポジトリに記事が追加されたら自動投稿される仕組みになっている。詳細は下記を参照のこと。
[Qiita に投稿する技術記事を GitHub で管理する方法](https://zenn.dev/noraworld/articles/github-to-qiita)
## リポジトリ内で使用する言語について
このリポジトリは日本語の技術記事を管理するためのリポジトリなので、README や Git のコミットメッセージも日本語で記述することにする。このリポジトリ内でわざわざ英語を使用する必要はないし、そのほうがわかりやすいと思うからである。
## 過去記事 (Qiita に直接投稿していた記事) について
Qiita に直接投稿していた過去記事に関しては、**編集履歴含め** このリポジトリに移行した。
編集履歴を追いながらすべての記事を Git に移行するのは骨が折れた。Qiita の記事をすべてダウンロードできるツールがあったのだから、それを使って一気に移行すれば良かったものを、編集履歴も管理したいからという理由で手動で移行したらとんでもなく大変な作業になってしまった。事前にどれだけ大変かを把握してから作業するか判断すべきだった。もうこんなエンジニアらしからぬ苦痛な作業は今後しないようにしよう。
それはさておき、過去記事の移行が完了した時点で 399 commits だった。そしてこの項を README に追加する変更で合計 400 commits だ。ここからは Git で管理するのをメインとし、Qiita へは API 経由で投稿する。
## 執筆の方法
久しぶりに技術記事を執筆するときに忘れてしまうのでメモしておく。
まず始めに Zenn で slug 名が重複していないことを確認する。ブラウザで `https://zenn.dev/link/articles/` にアクセスして 404 Not Found が返ってくることを確認する。記事が見つかった場合は slug 名が重複しているので別の名前を検討する。
以下のコマンドを実行しテンプレート付きのファイルを新規作成する。
```shell
npx zenn new:article --slug
```
## 執筆する際のアドバイス
* 最初に見出しだけを書く
* 上から順番に文章を書こうとするとダラダラと長く書きがちになるので
* 見出しの次に実行するコマンドやコードだけを書く
* 画像や表が必要な場合は文章を書く前に追加する
* 最後に必要な文章を付け足す
* 文章はなるべく短く簡潔に書き、補足情報は重要な文章と混ざらないようにする
* 可読性向上のため
## Zenn における記事執筆時のルールについて
### HTML を使用しない
Qiita と違って、Zenn では HTML を解釈しないので、以下のような理由で HTML を使用することはできない。
* リンクを新しいタブで開かせる
* 画像のサイズを設定する
* 文字を着色する
* `` タグを利用した、折りたたみ表現
### 絵文字はマルチバイト文字を使用する
Zenn では `:smile:` のようなショートコードでの記法では絵文字に変換されない。そのため `😀` のようにマルチバイトの絵文字を直接入力する必要がある。
### 記事内リンクに絶対パスを使用しない
絶対パスを指定すると Zenn の URL になってしまうため、相対パスで表現する。
これにより、どこに記事を公開しても、記事内のリンクは常に参照できるようになる。今後、Zenn 以外のプラットフォームに移行する際に少しでも楽をするため。
ただし、自分自身の他の技術記事に関しては、Qiita のようにプラットフォーム独自に記事 ID を生成して URL に使用している場合があるため対応不可能。そのため、現時点ではとりあえず、自分自身の他の技術記事のリンクは Zenn の絶対パスを指定することにする。
相対パスだと、Qiita からアクセスできなくなってしまう (リンク切れになってしまう) ので、絶対パスを指定するしかない。
### 画像を Zenn にアップロードしない
他のプラットフォームへの移行柔軟性を考えると、画像もプラットフォームに直接アップロードするのは得策ではない。
なぜなら、そのプラットフォームが運営されている限りは、画像の URL に外部 URL を使用しても参照できるが、そのプラットフォームが終了してしまうとリンク切れになってしまうからである。
そのため、画像も GitHub に置きたいと考えているが、GitHub はストレージサービスではないため、1 つのリポジトリであまり多くのストレージを使うのは良くない。
[私のディスク容量はいくつですか？](https://docs.github.com/ja/github/managing-large-files/what-is-my-disk-quota)
そのため、画像専用のリポジトリを作り、そこに画像を置くのが良いのではないかと考えている。そのリポジトリのストレージを使いすぎてしまったら、また新しいリポジトリを作成する、といった具合に。
### Zenn 独自の Markdown 拡張記法は使用しない
Zenn オリジナルの記法は使用しないようにする。理由は以下の通り。
* 他のプラットフォーム (Qiita) との互換性のため
* Zenn から別のプラットフォームに今後移行することになった際に記事を修正する手間を極力減らすため
別のプラットフォームへの移行だけを考慮するなら、移行時に全記事内の Zenn 独自記法を変換するマイグレーションスクリプトを用意すれば良いが、Qiita との同時投稿をしているため、Qiita 側でおかしな表記になるのを避けたい。
一応、Zenn の Markdown 記法についての記事のリンクをここに貼っておく。あくまで参考程度に。
[ZennのMarkdown記法](https://zenn.dev/zenn/articles/markdown-guide)
ついでに Zenn CLI の利用方法 (ディレクトリ構造) も参考になるのでここに貼っておく。
[Zenn CLIで記事・本を管理する方法](https://zenn.dev/zenn/articles/zenn-cli-guide)
### topics に記号は利用可能
topics に記号が入っていると、`zenn preview` ではエラーが出るが、一部の記号は無視しても問題なさそう。例としては以下のようなものが挙げられる。
* Node.js
* docker-compose
上記の 2 つはアイコンもちゃんと設定されていたので、むしろ積極的に使うべき topics だろう。
ただし、不用意に記号を入れたり、以下のようにバージョンを入れたりするのは得策ではないだろう。
* Ruby3
* Ruby-3
* Ruby3.0
* Ruby-3.0
見た目があまり美しくないというのと、アイコンが設定されないため。
#### 注意点
ただし、topics にスペースを入れると、Qiita に投稿されないので (スペースを含むタグは Qiita では不正なので) 使用しないこと。
### 記事のタイトルは 70 文字まで
60 文字を超えると `zenn preview` でエラーが出るが、実際には 70 文字まで設定可能。60 文字を超えてもプレビューでエラーが出るだけで、デプロイは成功する。
しかし 70 文字を超えるとデプロイに失敗し記事が公開されない。
### slug のルール
slug (ファイル名、かつ、Zenn の記事の URL になるもの) は以下のルールに従う。
* 半角英数字とハイフンの組み合わせ
* 12 〜 50 文字の範囲内
これは `zenn new:article --slug ` を実行せずに手動でファイル名を作ったとしても、このルールを守っていないとエラーになって Zenn に投稿できない。