How urbaninstitute/nccs works
Main components
• Repository & Source Files – This includes all the site content: the Jekyll configuration (_config.yml), Rakefile commands, Gemfile (Ruby gems), the SCSS and JS assets under public, and static webpages like index.html.
• Content Collections – Separate folders are used for different types of content (e.g., _stories for Quarto-supported content, catalogs for data-driven pages, and resources/datasets). In addition, custom data and people lists reside in _data.
• Quarto Integration – The _quarto.yml file and the .qmd files inside _stories that are rendered through Quarto (typically in RStudio).
• Templating Components – Jekyll uses _layouts, _includes (with various partials for nav, footer, and specialised components), and even hidden pages.
• Build/Development Tools – The Rakefile contains commands (like “rake dev” and “rake build”) to help spin up local Jekyll servers; the Ruby environment (managed via bundler) is specified through the Gemfile.
• Deployment – Github Pages is used for deploying the site. The build process (triggered upon commit to the main branch) takes care of generating the final static assets.
• Assets & Static Files – SCSS files (with separate component styles) and JavaScript modules (with ESM) that are processed by Jekyll’s supported mechanisms.
Relationships and interactions
• The source repository (code, content, configuration) is the origin point. When a developer triggers a render (via RStudio for Quarto or using the rake tasks), the Quarto tool takes the .qmd files and generates Markdown.
• Next, Jekyll takes the Markdown from both Quarto and native .md files together with Liquid templates defined in _layouts and _includes. This processing includes the SCSS styles, JavaScript modules, and any static assets.
• The output is then a full set of HTML/CSS/JS files – the static website that is pushed live via Github Pages.
• The rake commands serve as shortcuts to build and run the site locally before the final commit.
• Data files (in _data and _datasets) support the dynamic insertion of content in various pages (like author information and datasets details).
Important architectural patterns and design principles
• The project emphasizes simplicity by avoiding a complex build system (no Webpack/Vite or additional node-based tools). Instead, it relies on Jekyll’s native support for SCSS and the browser’s ability to handle native ESM modules.
• There is a clear separation of concerns: content (in various collections and data files), templating (using Jekyll’s Liquid, layouts, and includes), and static asset processing.
Relevant technologies
• Jekyll (for static site generation and Liquid templating)
• Quarto (for authoring rich, dynamic content through .qmd files)
• SCSS/CSS and ESM JavaScript (for styling and interactive client-side features)
• Ruby (bundler, Gemfile, and rake tasks for build orchestration)
• Github Pages (for deployment)
• Use clear labels for each major component:
• “Repository Source (Code, Content, Config)”
• “Quarto Rendering Engine” (input: .qmd files & _quarto.yml; output: Markdown)
• “Jekyll Build System” (input: Markdown, Liquid templates, SCSS, JS)
• “Static Assets (HTML, CSS, JS)”
• “Deployment (Github Pages)”
• “Rake Commands / Ruby Environment” (shortcut for build & development)
• From repository to Quarto for content processing.
• From repository (layouts, includes, SCSS, JS) to Jekyll.
• From Jekyll to the generated static website.
• A different style for configuration/build scripts (Rakefile, Gemfile, _config.yml).
• Another style for static assets (SCSS, JavaScript, images).