Interactive roadmap explorer with generated PDF/PNG

.github/workflows/pages.yml

@@ -0,0 +1,104 @@
+name: Roadmap explorer
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - README.md
+      - "site/**"
+      - .github/workflows/pages.yml
+  pull_request:
+    paths:
+      - README.md
+      - "site/**"
+      - .github/workflows/pages.yml
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Test and build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Test the README parser and map layout
+        run: node --test site/parser.test.mjs
+
+      - name: Assemble the site
+        run: |
+          mkdir _site
+          cp site/*.html site/*.css site/*.js site/map.json README.md _site/
+          cp -r site/fonts site/assets _site/
+          # Revision shown in the credits: the release tag, or tag-commits-hash between releases.
+          VERSION="$(git describe --tags --always)" DATE="$(git log -1 --format=%cs)" \
+            node -e 'console.log(JSON.stringify({ version: process.env.VERSION, date: process.env.DATE }))' > _site/build.json
+          cat _site/build.json
+
+      - name: Install Chromium
+        run: |
+          npm install --no-save --no-package-lock playwright@1
+          npx playwright install --with-deps chromium
+
+      - name: Render the roadmap to PDF and PNG
+        run: node site/tools/render.mjs _site / _site
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: roadmap-render
+          path: |
+            _site/Embedded-Engineering-Roadmap.pdf
+            _site/Embedded-Engineering-Roadmap.png
+          if-no-files-found: error
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+
+  release-assets:
+    name: Attach PDF and PNG to the release
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: roadmap-render
+
+      - name: Upload release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: gh release upload "$TAG" Embedded-Engineering-Roadmap.pdf Embedded-Engineering-Roadmap.png --clobber

.gitignore

@@ -1,7 +1,3 @@
-# Visio and draw.io lock/backup files
-~$*
-*.bkp
-
 # Link checker cache
 .lycheecache
 
@@ -12,3 +8,4 @@ Thumbs.db
 
 # Local tooling
 node_modules/
+dist/

README.md

@@ -1550,7 +1550,7 @@ _Discrete Mathematics_ is a multi-semester course that involves subjects about t
 
 At first this was meant to be my personal reading list but as the list gradually became bigger and bigger, I wondered why not share it with others. So I did research on current job postings for embedded engineering roles, selecting the most frequent skills and including them on a roadmap. In order to make the roadmap more comprehensive I also added some basic skills and finally came up with what you see here.
 
-The idea of creating this roadmap came from [vazeri / Embedded-Engineering-RoadMap-2018](https://github.com/vazeri/Embedded-Engineering-RoadMap-2018) which was well designed but had some flaws and not updated for years. I took that idea, changed the structure of the roadmap and tried to improve it. The initial results can be accessed in [m3y54m / Embedded-Engineering-Roadmap-Archived](https://github.com/m3y54m/Embedded-Engineering-Roadmap-Archived) which is now archived. Early versions of the roadmap were created using [Balsamiq Wireframes](https://balsamiq.com) which is not suitable for these types of diagrams. So I decided to use Microsoft Visio instead and redrew the whole diagram.
+The idea of creating this roadmap came from [vazeri / Embedded-Engineering-RoadMap-2018](https://github.com/vazeri/Embedded-Engineering-RoadMap-2018) which was well designed but had some flaws and not updated for years. I took that idea, changed the structure of the roadmap and tried to improve it. The initial results can be accessed in [m3y54m / Embedded-Engineering-Roadmap-Archived](https://github.com/m3y54m/Embedded-Engineering-Roadmap-Archived) which is now archived. Early versions of the roadmap were created using [Balsamiq Wireframes](https://balsamiq.com) which is not suitable for these types of diagrams. Today the roadmap is drawn by the interactive explorer in this repository, directly from this README and the map definition.
 
 ## Copyright
 
@@ -1568,4 +1568,4 @@ Special thanks to my friends in the community of Iranian Embedded Engineers in T
 
 If you think that this roadmap can be improved in anyway or you know about some good learning resources that can be added here, please start an issue or a pull request. I’ll be maintaining and updating this repository frequently.
 
-The source file is created using [Microsoft Visio](https://office.com/visio) in `.vsdx` format and included in this repository for your contributions. If you do not have Microsoft Visio or you want to use free software, you can use [draw.io](https://draw.io) which can import and export `.vsdx` files.
+The roadmap image and PDF are generated from this repository. Topics, descriptions and learning resources come from this README; where each topic sits on the map and how important it is come from [`site/map.json`](site/map.json). Edit those files and the interactive explorer in [`site/`](site) renders the PNG and PDF automatically.