株式会社 IVRy （アイブリー） 社員番号 7 番 エンジニアのボルドーです。
今回は弊社が公開している コラム記事 の管理方法について、現状の課題と工夫している点等を交えながら紹介したいと思います。
記事管理の現状
今の所 入稿ツールのようなものは用意できていないため、以下のような流れで管理しています。
- ライターがマークダウン形式で執筆してエンジニアへ共有
- 📝 カスタムタグやメタデータを追加したオレオレマークダウン形式となっているものの 入稿ツールがないためカスタムタグのプレビューができない点が課題
- エンジニアが GitHub の対象リポジトリに該当ファイルを追加して検証環境へ反映
- 📝 細かい修正が重なるため、ライターとエンジニアのコミュニケーションコストやエンジニアの工数が課題
- 📝 ライターとエンジニアそれぞれがファイルを管理しており二重管理になってしまっている点も課題
- 検証環境にて確認が取れたら本番環境へリリース
- 記事は Next.js の Static HTML Export を利用し、react-markdown にてマークダウンを変換して生成しています
理想としては入稿ツールでライターが入稿、プレビュー、公開まで行えるようになること なのですが、開発チームとしてやりたいことが山のようにあるため、入稿ツールの開発は優先順位が上がらず実現できていません。
そんな中でもカスタムタグの記法に関する誤りは一般的なマークダウンエディタではプレビューができないため、記事として不適切な状態で公開されてしまうことが稀にあり問題になっていました。
誤りに気付くタイミングとしては 2 のエンジニアが GitHub のリポジトリに追加する際の PR （Pull Request） か検証環境での関係者による確認のどちらかになるのですが、複数人による確認を行っても見落とされてしまうことはあります。
現実的な対策
上述の通り、入稿ツールを開発して記事の一元管理、カスタムタグを含めたプレビュー等ができるようになることが理想なのですが、それを待っていたらそのうち運用工数が開発工数を上回ってしまいかねません。
そこで運用工数を減らす現実的な対策として 2 の PR 時点で最低限の自動チェックを行うことにしました[1][2]。
カスタムタグの自動チェック
カスタムタグの記法ミスを最小工数で防止するために導入したのが textlint です[3]。
このライブラリを利用することで独自の textlint ルールを作成したり、他の方が作成している複数のルールを容易に扱えるようになりますし、 .textlintrc.json という設定ファイルにて各ルールの細かいチューニングを行うことができます。マークダウン形式を標準サポートしている点も魅力的です。
将来的に入稿ツールを開発することになった際にもそのまま移植できそうです。
使用例
textlint に独自ルールを追加する方法については textlint/docs/rule.md に記載されています。
/**
* @param {RuleContext} context
*/
export default function (context) {
// rule object
return {
[context.Syntax.Document](node) {},
[context.Syntax.Paragraph](node) {},
[context.Syntax.Str](node) {
const text = context.getSource(node);
if (/found wrong use-case/.test(text)) {
// report error
context.report(node, new context.RuleError("Found wrong"));
}
}
};
}
Syntax はこちらに定義されているものが利用可能 なようです。
どのような文字列が 各Syntax にどうマッピングされるのかについては https://textlint.github.io/astexplorer/ にて確認できます。
https://textlint.github.io/astexplorer/ 利用の様子
そのため、検知したい条件を羅列していくだけで簡単に導入することができました。
その他、クラスメソッドさんの記事（ 【GitHub Actions】Markdown 執筆に textlintの自動校正を取り入れる ）も大いに参考にさせていただきました。
GitHub Actions にて追加・変更のあったファイルに textlint を当てる
これもクラスメソッドさんの記事（ 【GitHub Actions 小ネタ】プルリクエスト時に差分ファイルの一覧を取得する ）を参考にさせていただき、 GitHub Actions にて PR をトリガーとして差分ファイルの一覧に対して textlint を当てるようにしました。
そのまま転用させていただいただけなので本記事では特に触れないですが、PR 時にマークダウンファイルのみトリガーするように以下のように記述しています。
on:
pull_request:
paths:
- "**/*.md"
結果
雑な正規表現に引っ掛けているだけなのでエラー文言等 改良の余地がありますが、このような形で自動チェックしてくれるようになりました🎉
コラム記事の管理方法の紹介は以上となります。
ご覧いただきありがとうございました。
We are hiring!!
最後に、IVRy では一緒に働く仲間を絶賛募集中です。
今の所 順調に成長してきていますが、今後の更なる成長のためには圧倒的に仲間が不足しています。皆さまのご応募お待ちしております！
カジュアルに話を聞きたいという方は私の Meety から面談を申し込んでいただければ色々お話します。
代表の奥西とも話せます！
Discussion