📄

Reveal.jsでMarkdownスライドを作ってGitHub Pagesで公開してみた

に公開
GitHub
Markdown
slide
tech

Reveal.jsでMarkdownスライドを作ってGitHub Pagesで公開してみた

こんにちは、普段はPythonやQGISを使って業務支援ツールを開発している社会人1年目のエンジニアです。

今回は、PC初心者の知人にパソコンを紹介するという小さな相談をきっかけに、
Markdown・GitHub・スライド技術を活用して「使い始め支援まで含めたマニュアル公開」に挑戦してみました。

🎯 背景と目的

「パソコンおすすめしてほしい」と言われたとき、
普通なら「じゃあ予算と用途聞いて調べてみるよ」といった流れで終わると思います。

でも今回は、それだけでは不十分だと感じました。

相手はPC初心者。
つまり「スペック表やレビューを見てもよくわからない」状態で、
こちらの言うことを信じて買うしかない状況です。

だからこそ、「なんとなくおすすめされたから買った」ではなく、
“自分で理解して納得して選んだ”という実感を持ってもらいたいと思いました。

そのためには、ただ製品を調べるだけでなく、
私自身がパソコンの基本的な知識や用途、スペックの意味をちゃんと理解し、
わかりやすく伝える力を持つことが必要だと感じました。

さらに、使い始めた後に困らないように
「基本操作」や「設定」「トラブル対処」まで含めたサポート資料も届けたいという気持ちが生まれました。

せっかくなら、それを通じて自分のスキルアップにもつなげたいと考え、
マニュアル的な資料を作るだけでなく、それを“きちんと公開して届ける技術”も含めて学ぶプロジェクトとして取り組むことにしました。

🗂 プロジェクト全体の目的は次の3つです：

  • 💻 初心者でも扱いやすいノートPCを選定する（価格・性能・携帯性のバランス重視）
  • 📝 最低限のPCリテラシーを習得できるよう、操作手順や基本的な学習リソースを提供
  • 🛠️ トラブル対応やメンテナンス方法も含め、長期的なサポートにつながるようなガイドを作る

🔍 今回はその中で：

  • Markdownベースで支援スライドを作成（Reveal.js）
  • GitHub Actions × GitHub Pages による自動公開フローの構築

という“資料の制作と公開”に関わる部分にフォーカスして紹介します。

※動画の作成やナレーション収録等については今回は扱っていません。

人に理解してもらうには、自分がまず理解していなければならない。
その前提に立って進めた今回のプロジェクトの記録として、
使った技術・工夫・つまずいた点・今後の展望などを、この記事にまとめました。

🛠 やってみたこと

今回のプロジェクトでは、初心者向けにわかりやすく情報を届けるために、
Markdownベースでスライドを作成して、それをWeb上で公開できるようにするという流れに挑戦しました。

構成としては次の3ステップです：

① Reveal.js で Markdown からスライド作成

  • Markdownで書いた原稿を、Reveal.js を使ってスライド形式に変換
  • コードハイライト・箇条書き・画像埋め込みなどが簡単
  • テーマ（見た目）やフォントもカスタマイズ可能（日本語対応も調整）
  • スライドの章立ては以下のように構成
    → 例：PC選びのポイント / 操作の基本 / よくある設定 など

② GitHub Actions を使ってスライドを自動公開

  • main ブランチにPushしたら自動で dist/ を生成して GitHub Pages に公開されるようにCI/CD構築
  • ActionsのYAMLは以下のようなシンプルな構成：
name: Deploy Slides to Pages
on:
  push:
    branches: [ main ]
    paths: [ "slides/**" ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: |
          cd slides
          npm ci
          npx reveal-md index.md --static _site
      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: slides/_site

permissions:
  contents: write
  • GitHub Pagesの設定で gh-pages ブランチをソースとして選択することで公開URLが生成される
    例）https://ユーザー名.github.io/リポジトリ名/

③ デザイン・構成の調整（現在サンプル段階）

  • Reveal.js のカスタマイズ機能（テーマ・フォント・アニメーションなど）はまだ試し中
  • 現時点では サンプルスライドをいくつか作成したのみ で、全体構成やデザインは今後詰めていく予定
  • 特に日本語フォントの統一感、スライド切り替えアニメーション、コードブロックの読みやすさなどを改善したいと感じている

今回の時点ではまだプロトタイプですが、
Markdownで書いた内容がすぐWebスライドとして反映され、自動で公開できるという体験は、
「作って渡す」だけでなく「継続的に支援できる形」にもつながると感じました。

💡 学びと気づき、今後の展望

✅ やってよかったこと

  • Markdownで資料を作ることで、構成の修正や追記がめちゃくちゃ楽だった
  • Reveal.js の導入も想像以上にシンプルで、「HTMLスライド」のハードルがかなり下がった
  • GitHub Actions での自動デプロイにより、「更新すればすぐ共有できる」状態が作れて達成感があった

🤔 難しかったこと・課題

  • Reveal.js はプレゼン向けには良いけど、複数マニュアルを体系的に管理するのにはあまり向いていない
  • GitHub Pages を使った公開フローは便利な一方で、非エンジニアにとっては執筆・更新が難しい
  • スライド構成やテーマの調整、文章表現などは、「技術が伝わる＝わかりやすい」とは限らないと実感した

🔭 今後の展望

  • 継続的に複数のマニュアルを運用するなら、Reveal.jsよりも MkDocs や Docsify の方が向いているかも
  • GitHubが使えない人でも書けるように、Typora や Notion → GitHub反映の運用を模索したい
  • 今回は触れなかったけど、動画・ナレーション・操作デモも今後組み合わせていきたい

最終的に目指したいのは、
「初心者が安心してPCを使い始められるようになる」ことと、
その支援を通じて自分自身も学び続けられる仕組みを作ること。

今回はその一歩目として、
Reveal.js × GitHub Actions による“わかりやすく・届けやすい資料作成”を試してみたという記録でした。

🔗 公開スライドとリポジトリ

📎 スライド（Reveal.jsで作成・GitHub Pagesで公開）：
👉 https://shef-04.github.io/pc-recommend-for-beginners/

📎 開発用リポジトリ（Markdown原稿・GitHub Actions設定あり）：
👉 https://github.com/shef-04/pc-recommend-for-beginners

まとめ

誰かにパソコンをおすすめする
それを単なる情報提供ではなく、「相手が納得し、自信を持って使い始められる」ように支援したい。
その想いから始まった今回のプロジェクト。

Markdown・Reveal.js・GitHub Actions を組み合わせることで、
わかりやすく、伝わりやすい支援資料を作って公開する仕組みを作れたのは、大きな一歩でした。

今後はマニュアルの管理方法や、執筆しやすい仕組みづくりなど、
より実務的・継続的な運用に向けて改善していきたいと考えています。

最後まで読んでいただきありがとうございました！
コメント・ご意見・改善アドバイスなど大歓迎です🙌

Discussion