diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 9f8158c..148a0a5 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -5,13 +5,13 @@ on: branches: [master] paths: - README.md - - "site/**" + - "explorer/**" - .github/workflows/pages.yml - .github/scripts/next-version.sh pull_request: paths: - README.md - - "site/**" + - "explorer/**" - .github/workflows/pages.yml - .github/scripts/next-version.sh workflow_dispatch: @@ -48,16 +48,16 @@ jobs: node-version: 22 - name: Test the README parser and map layout - run: node --test site/parser.test.mjs + run: node --test explorer/parser.test.mjs - name: Warn about README sections that are not on the map - run: node site/tools/coverage.mjs + run: node explorer/tools/coverage.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/ + cp explorer/*.html explorer/*.css explorer/*.js explorer/map.json README.md _site/ + cp -r explorer/fonts explorer/assets _site/ - name: Install Chromium run: | @@ -68,7 +68,7 @@ jobs: id: fingerprint # Rendered before build.json exists, so the revision line is not part of the fingerprint. run: | - node site/tools/render.mjs _site / fingerprint + node explorer/tools/render.mjs _site / fingerprint echo "sha256=$(sha256sum fingerprint/Embedded-Engineering-Roadmap.png | cut -d' ' -f1)" >> "$GITHUB_OUTPUT" - name: Decide the version @@ -87,7 +87,7 @@ jobs: run: | node -e 'console.log(JSON.stringify({ version: process.env.VERSION, date: process.env.DATE }))' > _site/build.json cat _site/build.json - node site/tools/render.mjs _site / _site + node explorer/tools/render.mjs _site / _site - uses: actions/upload-artifact@v4 with: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b423794..0f66f7b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,7 @@ Contributions from everyone are welcomed. To keep the roadmap practical, accessi - Contributions should match the topics and structure of the roadmap. - Areas where contributors have experience or genuine interest should be focused on. - If a new topic is thought to make the roadmap more complete, it may be suggested. New topics should be proposed thoughtfully, considering their usefulness and relevance for other learners. -- Connections between topics on the map are listed in `site/map.json` under `links` as `["Topic", "Other topic", "why they are related"]`, using the names shown on the map. Connect topics that a learner should study together or that depend on each other, and keep the reason to one short sentence. Tests fail if a name is misspelled, a pair is listed twice or a topic has no connection. +- Connections between topics on the map are listed in `explorer/map.json` under `links` as `["Topic", "Other topic", "why they are related"]`, using the names shown on the map. Connect topics that a learner should study together or that depend on each other, and keep the reason to one short sentence. Tests fail if a name is misspelled, a pair is listed twice or a topic has no connection. ## 6. How the README Feeds the Interactive Roadmap @@ -38,8 +38,8 @@ The [interactive roadmap](https://m3y54m.github.io/Embedded-Engineering-Roadmap/ - **Topics** come from heading depth: `##` is a group, `###` a main topic, `####` and deeper are subtopics. The emojis in headings (✳️ πŸ”΅ πŸ”Ά πŸ”Έ) are decoration only. Renaming a heading changes its link (`#/topic-name`). - **Resources** are list items in the form `- [πŸ“˜πŸ‘ΆπŸ’Ž Title](https://url)`, optionally followed by a dash and a short note. Symbols: πŸ“˜ book, 🎞️ video, πŸ“ article, πŸ”— link, 🎧 audio, πŸ‘Ά beginner, πŸ’Ž essential. `python3 .github/scripts/check_readme.py` checks the format and duplicates. -- **The map** (`site/map.json`) draws only the main topics. Each label on it opens the README heading with the same name. If the wording differs, or the label has no section of its own, add `"Label": ["README heading"]` to `readme` in `site/map.json`. A new main topic needs a README section and a box in `site/map.json` (and at least one entry in `links`), unless it should stay off the map: then list its title or group in `offMap`. CI warns about main topics that are neither. -- **Preview and test locally:** `python3 -m http.server 8765` from the repository root, then open `/site/`; `node --test site/parser.test.mjs` runs the checks CI runs. +- **The map** (`explorer/map.json`) draws only the main topics. Each label on it opens the README heading with the same name. If the wording differs, or the label has no section of its own, add `"Label": ["README heading"]` to `readme` in `explorer/map.json`. A new main topic needs a README section and a box in `explorer/map.json` (and at least one entry in `links`), unless it should stay off the map: then list its title or group in `offMap`. CI warns about main topics that are neither. +- **Preview and test locally:** `python3 -m http.server 8765` from the repository root, then open `/explorer/`; `node --test explorer/parser.test.mjs` runs the checks CI runs. ## 7. Versioning and Releases diff --git a/README.md b/README.md index 6116161..92b6a51 100644 --- a/README.md +++ b/README.md @@ -1622,4 +1622,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 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. +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 [`explorer/map.json`](explorer/map.json). Edit those files and the interactive explorer in [`explorer/`](explorer) renders the PNG and PDF automatically. diff --git a/site/app.js b/explorer/app.js similarity index 100% rename from site/app.js rename to explorer/app.js diff --git a/site/assets/cc-by-sa.svg b/explorer/assets/cc-by-sa.svg similarity index 100% rename from site/assets/cc-by-sa.svg rename to explorer/assets/cc-by-sa.svg diff --git a/site/assets/logo.svg b/explorer/assets/logo.svg similarity index 100% rename from site/assets/logo.svg rename to explorer/assets/logo.svg diff --git a/site/diagram.js b/explorer/diagram.js similarity index 100% rename from site/diagram.js rename to explorer/diagram.js diff --git a/site/dom.js b/explorer/dom.js similarity index 100% rename from site/dom.js rename to explorer/dom.js diff --git a/site/fonts/OFL.txt b/explorer/fonts/OFL.txt similarity index 100% rename from site/fonts/OFL.txt rename to explorer/fonts/OFL.txt diff --git a/site/fonts/SofiaSansSemiCondensed.woff2 b/explorer/fonts/SofiaSansSemiCondensed.woff2 similarity index 100% rename from site/fonts/SofiaSansSemiCondensed.woff2 rename to explorer/fonts/SofiaSansSemiCondensed.woff2 diff --git a/site/index.html b/explorer/index.html similarity index 100% rename from site/index.html rename to explorer/index.html diff --git a/site/layout.js b/explorer/layout.js similarity index 100% rename from site/layout.js rename to explorer/layout.js diff --git a/site/map.css b/explorer/map.css similarity index 100% rename from site/map.css rename to explorer/map.css diff --git a/site/map.json b/explorer/map.json similarity index 100% rename from site/map.json rename to explorer/map.json diff --git a/site/mapview.js b/explorer/mapview.js similarity index 100% rename from site/mapview.js rename to explorer/mapview.js diff --git a/site/parser.js b/explorer/parser.js similarity index 100% rename from site/parser.js rename to explorer/parser.js diff --git a/site/parser.test.mjs b/explorer/parser.test.mjs similarity index 100% rename from site/parser.test.mjs rename to explorer/parser.test.mjs diff --git a/site/styles.css b/explorer/styles.css similarity index 100% rename from site/styles.css rename to explorer/styles.css diff --git a/site/tools/coverage.mjs b/explorer/tools/coverage.mjs similarity index 77% rename from site/tools/coverage.mjs rename to explorer/tools/coverage.mjs index f459c91..1fb55c5 100644 --- a/site/tools/coverage.mjs +++ b/explorer/tools/coverage.mjs @@ -1,5 +1,5 @@ // Warns (never fails) about README sections that have no place on the map yet. -// Usage: node site/tools/coverage.mjs Sections listed in map.json "offMap" (titles or group names) are skipped. +// Usage: node explorer/tools/coverage.mjs Sections listed in map.json "offMap" (titles or group names) are skipped. import { readFileSync } from 'node:fs'; import { parseRoadmap } from '../parser.js'; import { linkDiagram } from '../diagram.js'; @@ -15,6 +15,6 @@ const skipped = new Set(map.offMap || []); const missing = data.root.children.filter((t) => !skipped.has(t.title) && !skipped.has(t.group) && !onMap(t)); for (const t of missing) { - console.log(`::warning file=README.md,title=Not on the roadmap map::"${t.title}" has no box on the map. Add it to site/map.json, or to "offMap" if it should stay off the map (see CONTRIBUTING.md).`); + console.log(`::warning file=README.md,title=Not on the roadmap map::"${t.title}" has no box on the map. Add it to explorer/map.json, or to "offMap" if it should stay off the map (see CONTRIBUTING.md).`); } console.log(missing.length ? `${missing.length} README section(s) are not on the map.` : 'Every README section is on the map or listed in "offMap".'); diff --git a/site/tools/render.mjs b/explorer/tools/render.mjs similarity index 93% rename from site/tools/render.mjs rename to explorer/tools/render.mjs index e61ffef..a4a4fe9 100644 --- a/site/tools/render.mjs +++ b/explorer/tools/render.mjs @@ -1,13 +1,13 @@ // Renders the roadmap map to an A4 PDF and a PNG with headless Chromium, straight from the site. -// Usage: node site/tools/render.mjs [rootDir] [pagePath] [outDir] -// defaults: repository root, /site/, ./dist (needs: npm install --no-save playwright) +// Usage: node explorer/tools/render.mjs [rootDir] [pagePath] [outDir] +// defaults: repository root, /explorer/, ./dist (needs: npm install --no-save playwright) import { createServer } from 'node:http'; import { mkdir, readFile } from 'node:fs/promises'; import { extname, join, resolve, sep } from 'node:path'; import { chromium } from 'playwright'; const root = resolve(process.argv[2] || '.'); -const pagePath = process.argv[3] || '/site/'; +const pagePath = process.argv[3] || '/explorer/'; const outDir = resolve(process.argv[4] || 'dist'); const NAME = 'Embedded-Engineering-Roadmap'; const PNG_SCALE = 2;