Skip to content

project-structure.md

Latest commit

 

History

History
170 lines (127 loc) · 5.93 KB

project-structure.md

File metadata and controls

170 lines (127 loc) · 5.93 KB
Raw

Project Structure — APH Slides

Repository root: static slide source + Node build tooling. No backend, no src/ alias — paths are literal.

APH_slides/
├── docs/                    # Project documentation (this folder)
├── scripts/                 # Node.js build & runtime setup
├── slides/                  # All slide source and assets
│   ├── assets/              # Topic-scoped media (~70 topic folders)
│   ├── backgrounds/         # Shared slide background JPGs (16 files on disk)
│   ├── icons/               # Deck catalog icons (57 SVGs)
│   ├── plugins/             # Reveal.js plugins (search, notes, pointer)
│   ├── themes/              # SCSS themes (aph, base, dark, light)
│   └── view/                # Pug templates
│       ├── chapters/        # Reusable chapter content (131 .pug files)
│       ├── mixins/          # Layout/title/quote mixins (6 files)
│       └── *.pug            # Top-level deck entry points (56 files)
├── .github/workflows/       # CI: tag → build → release zip
├── build/                   # Generated output (gitignored)
├── package.json
├── README.md
├── CHANGELOG.md
├── LICENSE
└── agents.md                # AI agent entry point

Top-Level Directories

scripts/ — Build pipeline

File Purpose
copydata.js Entry for npm run copydata
generate-index.js Entry for npm run generate-index
process-snippets.js Snippet → HTML preprocessing
process-equations.js LaTeX → SVG preprocessing
fix-links.js Post-build path fixup
reveal-setup.js Browser Reveal.js initialization (ES module)
utils.js Shared filesystem utilities
index_template.html Template for generated catalog pages
remove-unused-pics.js Not wired — manual orphan image cleanup

slides/view/ — Template entry points

Deck files (*.pug at this level only): compiled by Parcel into build/view/<name>.html.

.dontcopy marker: Prevents raw Pug from being copied into build/ during copydata. Parcel alone produces HTML.

Naming conventions:

Pattern Meaning
lectureNN.pug English lecture deck
lectureNN_cs.pug Czech lecture deck
minitalk_<topic>.pug English minitalk
minitalk_<topic>_cs.pug Czech minitalk
tutorial_<name>.pug Tutorial deck

slides/view/chapters/ — Shared content

One file ≈ one lecture section or minitalk segment. Included by deck wrappers:

include ./chapters/games_intro.pug

Chapters are not listed in generate-index.js — only top-level slides/view/*.pug decks are indexed.

slides/view/mixins/ — Reusable Pug components

Prefer extending existing mixins over inline markup. Key classes used in mixins:

  • Layout: height-*, width-*, top-*p, left-*p, fill, center
  • Reveal: fragment, fade-up
  • Emphasis: highlight, highlight-2, important-orange

slides/assets/ — Topic assets

Structure per topic:

slides/assets/<topic>/
├── chapter_<topic>.svg      # Chapter title graphic (common pattern)
├── *.jpg, *.png, *.svg      # Slide images
├── snippets/                # Source code (preprocessed)
│   └── example.ts
├── snippets_generated/      # Generated HTML (gitignored)
├── equations/               # LaTeX source (preprocessed)
│   └── formula.tex
└── equations_generated/     # Generated SVG (gitignored)

Include generated snippets in Pug:

include ../../assets/patterns_creational/snippets_generated/builder.html

slides/themes/ — Styling

themes/
├── base/           # Shared SCSS variables, fonts, print
├── aph/            # Primary course theme (theme_aph.scss)
├── default_dark/
└── default_light/

Decks select theme via themePath variable, passed to +header() mixin.

slides/icons/ — Catalog icons

Basename must match deck file (without extension):

  • lecture01.pug → lecture01.svg
  • minitalk_portal_cs.pug → minitalk_portal_cs.svg

Missing icon = build failure in generate-index.js.

slides/plugins/ — Reveal plugins

Bundled locally (not npm imports in browser):

  • search/search.js
  • notes/notes.js, notes/notes.html
  • pointer/pointer.js

slides/backgrounds/ — Shared backgrounds

Referenced as backgrounds/<name>.jpg from Pug (relative to slide context). Known missing files: tree.png, marioworld.jpg, minecraft_blocks.png are referenced but absent from disk.

Generated / Gitignored Artifacts

Path Producer In git?
build/ Parcel + copydata No
slides/slides-info.json generate-index No
slides/index.html generate-index No
**/snippets_generated/ process-snippets No
**/equations_generated/ process-equations No
.cache/, .parcel-cache/ Parcel No

Note: slides/index_cs.html may exist locally but only slides/index.html is listed in .gitignore.

Module Boundaries (for AI agents)

Boundary Rule
Deck vs chapter Decks = indexable entry points; chapters = included fragments
Source vs generated Never edit *_generated/ — edit source in snippets/ or equations/
View vs assets Pug in view/; media in assets/ co-located by topic
Build vs runtime scripts/*.js (Node) vs reveal-setup.js (browser, bundled by Parcel)
Theme vs content Visual styling in themes/; slide text/layout in Pug

Scale (approximate, May 2026)

Item Count
Deck .pug files 56
Chapter .pug files 131
Icon SVGs 57
Background JPGs on disk 16
npm dependencies 1 runtime + 5 dev
Automated tests 0

Related Docs