Markdownで書いた職務経歴書を良い感じのWebサイトとPDFに自動変換するツールを作ってみた
こんにちは、つくぼし(tsukuboshi0755)です！
みなさん、職務経歴書は書いていますか？
私は社会人になってから職務経歴書を日々管理しておく事が大切だと感じており、万が一転職する場面に遭遇した時を考えて定期的に更新するようにしています。
その際に以下の記事が非常に分かりやすく、最近までこちらを参考に自身の職務経歴書を作成し公開していました。
こちらもGitHub PagesとMarkdownで職務経歴書を管理する方法ですが、PDFの生成やテキストの校正は手元でyarnコマンドを実行する形になっています。
そのため職務経歴書を更新する度に、ローカルの開発環境を用意して操作する必要がありました。
今回たまたま私自身が職務経歴書を再整理する機会があったため、この点を自動化した上でデザイン性も高められないかと考えました。
そこで今回は、Markdownで書いた職務経歴書をWebサイトとPDFに自動変換するツールを作成したので紹介します！
本ツールの概要
今回開発したツールはこちらになります。
このツールを使う事で、GitHubアカウントさえ持っていれば以下のような職務経歴書のWebサイトを誰でも作れるようになっています！
このツールを使って私の職務経歴書を以下の通り公開しています。
なかなかいい感じのWebサイトになっているのではないでしょうか。
さらに今回このツールを使う事で、以下のようなメリットがあります。
- GitHubの無料枠で利用できる機能(GitHub Actions/GitHub Pages)のみを使用しているため、GitHubアカウントさえあれば追加費用なしで職務経歴書のWebサイトとして公開可能
- 本ツールで職務経歴書を展開する際の手順が全てGitHubのWebサイト上で完結するため、ローカルで開発環境を構築する必要がなく、アプリケーション開発に詳しくない方でも利用可能
ただしGitHub Freeプランの場合、GitHub Pagesでサイトを公開できるのはPublicリポジトリに限られます。
そのため本ツールで作成した職務経歴書は、URLを知っている人だけでなく誰でも閲覧できる状態になります。
職務経歴書には勤務先や経歴といった情報が含まれるため、記載する内容は公開されて差し支えない範囲に留めて頂ければと思います。
本ツールの仕組み
本ツールは以下の技術スタックで構成されています。
| 項目 | 使用技術 |
|---|---|
| フレームワーク | HonoX |
| ビルドツール | Vite |
| スタイリング | Tailwind CSS |
| PDF生成 | md-to-pdf |
| CI/CD | GitHub Actions |
| ホスティング | GitHub Pages |
HonoXはHonoとViteを基盤としたメタフレームワークで、ファイルベースルーティングとIslandsアーキテクチャによるクライアント側のハイドレーションを備えています。
GitHub Pagesは静的ファイルのみを配信するホスティングサービスであるため、本ツールでは@hono/vite-ssgプラグインを使い、ビルド時に職務経歴書を静的HTMLとして書き出しています。
一方で後述する「全て開く」「全て閉じる」といった折りたたみ操作にはブラウザ側での処理が必要になるため、この部分のみをHonoXのIslands(app/islands配下のコンポーネント)として実装しています。
静的HTMLを基本としつつ、動きが必要な箇所だけをブラウザ上で動かす構成です。
職務経歴書がWebサイトとPDFに変換されるまでの流れは以下の通りです。
- mainブランチへのプッシュを契機に、GitHub Actionsのワークフローが起動する
-
md-to-pdfが職務経歴書の元データであるpublic/README.mdをPDFに変換する - Viteが同じ
public/README.mdを読み込み、独自のパーサーで見出し単位のセクションに分割した上で静的HTMLを生成する - 生成物一式を
gh-pagesブランチにプッシュし、GitHub Pagesが配信する
Webサイト・Markdownファイル・PDFファイルの3つが全てpublic/README.mdという単一のファイルから生成されるため、更新する箇所はこのファイル1つだけで済みます。
本ツールの機能
Webサイトへの自動公開
GitHubの無料ホスティング機能であるGitHub Pagesを使って、Webサイトとして自動公開できるようにしています。
ツールで展開した後に公開されるGitHub PagesのURLhttps://<GitHubユーザー名>.github.io/<GitHubリポジトリ名>/を共有するだけで、他の人も職務経歴書を確認できるようになっています。
Markdown/PDFファイルのダウンロード
Webサイト上部のMarkdownをダウンロード/PDFをダウンロードボタンを押す事で、別途職務経歴書のMarkdownファイル及びPDFファイルをダウンロードできます。
それぞれ以下の通りになっており、こちらはWebサイトとは逆にシンプルなデザインとなっています。
- Markdownファイル
- PDFファイル
Webサイトからそのままダウンロードできるので、MarkdownファイルやPDFファイルを求める企業に対しても、手間なく職務経歴書を提出できるようになっています！
本ツールの使い方
本ツールを使って、Webサイトを公開する手順は以下の通りです。
全てWebサイト上で完結するので、PCさえ触れれば誰でも簡単に公開できます！
GitHubアカウントの作成
まだGitHubアカウントを持っていない方は、以下のURLからアカウントを作成してください。
アカウントの作成方法については、以下の記事が参考になります。
リポジトリの作成と初期化
GitHubアカウントを作成したら、以下のURLをクリックしてください。
以下のようなテンプレートリポジトリ画面が表示されるので、Use this TemplateのCreate a new repositoryをクリックし新しいリポジトリを作成します。
以下の新規リポジトリ作成画面に移ったら、次の3項目を設定した上でCreate repositoryをクリックします。
-
Include all branchesにチェックを入れる(本ツールはWebサイトの配信元としてgh-pagesブランチを使用しており、このブランチがコピーされないとWebサイトの自動生成が開始されません) -
Repository nameに任意のリポジトリ名を入力する(後のWebサイトのURLパスに反映されるので、分かりやすい名前を付けておくと良いです) -
Publicを選択する(前述の通りGitHub FreeプランではPublicリポジトリのみ公開対象となるため、PrivateにするとWebサイトが公開されないので注意！)
クリックすると新規のリポジトリの作成が開始され、完了すると新規リポジトリのCode画面に切り替わります。
この時点でリポジトリの初期化が始まり、サンプルの職務経歴書を元にしたWebサイトの自動生成が開始されます。
Webサイトの自動生成の状況を確認するため、以下のリポジトリ画面上部のActionsのタブをクリックして確認します。
Actions画面のInitial commitの上にあるpages build and deploymentの先頭に緑のチェックマークが付いていれば、Webサイトの生成が正常に完了しています。
そのまま以下の画面でpages build and deploymentをクリックしてください。
以下の画面のdeployの下にある青いURLをクリックすると、サンプルのWebサイトが表示されます。
以下のようなWebサイトが表示されていれば、正常にリポジトリが初期化されています！
職務経歴書の更新
リポジトリの初期化が完了したら、各個人に合わせて職務経歴書を更新していきます。
GitHubの新規リポジトリで画面上部のCodeタブをクリックし以下のCode画面に戻った後、今度はpublicというディレクトリをクリックします。
すると以下の画面の通り、職務経歴書の元データであるREADME.mdファイルが下部に表示されます。
このREADME.mdを編集する事で更新がかかるため、鉛筆マークをクリックして編集していきます。
以下のようにEditタブの状態で職務経歴書の中身をいじる事ができるので、内容を更新していきます。
なおこちらのREADME.mdの内容の書き方については、後述の「本ツールでの職務経歴書の書き方」の項目を参考にしてください！
Previewタブに切り替えるとプレビュー画面を確認できるので、更新した内容でMarkdownが崩れていないか事前にチェックしてください。
問題なければ右上のCommit Changes...をクリックします。
その後以下の画面でコミット内容について聞かれるので、Commit directly to the main branchを選択しCommit Changesをクリックしてください。
コミットが完了するとまたWebサイトの自動生成が始まります。
「リポジトリの作成と初期化」の項目と同じ要領で、Actionsタブからpages build and deploymentをクリックし、deployの下にある青いURLを開いてください。
今度は先ほど更新したREADME.mdファイルの内容を元に、Webサイトがアップデートされているはずです。
また職務経歴書の内容を更新したくなった場合は、「職務経歴書の更新」の項目の手順を繰り返せばOKです！
(オプション)ローカル検証手順/テンプレートリポジトリ追従手順
本ツールの使用において必須の手順ではないですが、ローカルで事前にWebサイトを起動し確認したい方や、テンプレートリポジトリの更新を定期的に取り込みたい方向けに手順を整備しています。
特に自分で色々いじってみたいというエンジニアの方は、ぜひご確認頂けますと幸いです。
本ツールでの職務経歴書の書き方
今回職務経歴書の元データとなっているpublic/README.mdファイルでは、Markdown記法をベースとしつつ、よりデザイン性の高いWebサイトに変換するため一部独自記法を取り入れています。
なおサンプルの職務経歴書tsukuboshi.github.io/honox-resume-template/の書き方は、Markdownをダウンロードボタンよりファイルを確認できます。サンプルで利用されている記法を参考にしながら、職務経歴書を更新してみてください！
一般的なMarkdown記法
本ツールでのMarkdown記法の対応状況は以下の通りです。
| 記法 | 書き方 | 対応 |
|---|---|---|
| 見出し |
#から####まで |
✅ |
| 見出し |
#####以上 |
❌ |
| 段落 | 通常の文章 | ✅ |
| リンク | [表示テキスト](URL) |
✅ |
| 順序なしリスト |
- (マーカーの後ろに半角スペースが必要) |
✅ |
| 順序なしリスト |
*および+のマーカー |
❌ |
| 順序付きリスト |
1.、2. (同じくマーカーの後ろに半角スペースが必要) |
✅ |
| タスクリスト |
- [ ]や- [x]
|
❌ |
| テーブル |
| ヘッダー1 | ヘッダー2 |の形式 |
✅ |
| インラインコード | `code` |
✅ |
| コードブロック | ``` |
✅ |
| 引用 |
>から始まるブロック (>の後ろに半角スペースが必要) |
✅ |
| 太字 | **bold** |
✅ |
| イタリック | *italic* |
✅ |
| 打ち消し線 | ~~text~~ |
❌ |
| 水平線 | --- |
✅ |
| 水平線 | *** |
❌ |
| 脚注 |
[^1]および[^1]: 脚注の内容
|
❌ |
未対応の記法については、職務経歴書では使用する可能性が低いと考え現時点では対応していません。
なお####の見出しは、後述の通りWebサイト変換時にトグルセクションへ変換されます。
また#####以上の見出しについては、見出しレベルに応じた表示の出し分けに対応していません。
記載した場合は最上位の見出しと同じ大きさで表示されてしまうため、####までの範囲で構成する事をオススメします。
独自記法①：トグルセクション
#### セクション名を記載すると、Webサイト変換時にトグルセクションが作成され、次の段落までの内容が折りたたみ可能になります。
さらに### セクション名と#### セクション名の両方を記載した場合、### セクション名の右に「全て開く」「全て閉じる」ボタンが表示され、配下のトグルを一括で開閉できます。
独自記法②：バッジ埋め込み
以下の形式でアカウントのプロフィールURLを記載すると、Webサイト変換時にshields.ioによるアイコンとして埋め込まれます。
| 対応サイト | 書き方 |
|---|---|
| Zenn | [バッジ名](https://zenn.dev/<ユーザー名>) |
| Qiita | [バッジ名](https://qiita.com/<ユーザー名>) |
| GitHub | [バッジ名](https://github.com/<ユーザー名>) |
| DevelopersIO | [バッジ名](https://dev.classmethod.jp/author/<ユーザー名>) |
| SpeakerDeck | [バッジ名](https://speakerdeck.com/<ユーザー名>) |
| Docswell | [バッジ名](https://www.docswell.com/user/<ユーザー名>) |
| X | [バッジ名](https://x.com/<ユーザー名>) |
独自記法③：ブログ埋め込み
以下の形式でリストアイテムとして記載すると、Webサイト変換時に該当記事がはてなブログカードとして埋め込まれます。
| 対応サイト | 書き方 |
|---|---|
| Qiita | - [記事名](https://qiita.com/<ユーザー名>/items/<記事ID>) |
| Zenn | - [記事名](https://zenn.dev/<ユーザー名>/articles/<記事ID>) |
| DevelopersIO | - [記事名](https://dev.classmethod.jp/articles/<記事ID>) |
独自記法④：スライド埋め込み
以下の形式でリストアイテムとして記載すると、Webサイト変換時に該当スライドが埋め込まれます。
| 対応サイト | 書き方 |
|---|---|
| SpeakerDeck | - [スライド名](https://speakerdeck.com/player/<スライドID>) |
| Docswell | - [スライド名](https://www.docswell.com/slide/<スライドID>/embed) |
独自記法⑤：動画埋め込み
以下の形式でリストアイテムとして記載すると、Webサイト変換時に該当動画が埋め込まれます。
| 対応サイト | 書き方 |
|---|---|
| YouTube | - [動画名](https://www.youtube.com/embed/<動画ID>) |
参考資料
まとめ
今回は、Markdownで書いた職務経歴書をWebサイトとPDFに自動変換するツールについて紹介しました。
本ツールを使用する事で、Markdownの書き方さえ知っていれば、GitHubアカウント上で誰でもデザイン性のある職務経歴書のWebサイトを作成・公開できます。
本ツールについて試しに使って頂いて「良いね！」と思って頂けたら、tsukuboshi/honox-resume-templateにスターを付けて頂けると励みになります。
以下の赤枠をクリックする事でスターを付ける事ができるので、ぜひよろしくお願いします！
職務経歴書の管理や更新を効率化したい方は、ぜひ一度お試しください！
以上、つくぼし(tsukuboshi0755)でした！
Discussion