Project Critique: The Digital Elf Project
Project Critique: The Digital Elf Project
What It Is
A Jekyll-based static blog/educational site hosted on GitHub Pages at digitalelf.org. It aims to teach healthcare professionals (particularly NHS radiologists and clinicians) about digital transformation through practical programming tutorials and the “Digital Elf” metaphor — software as tireless automated helpers.
Strengths
1. Clear mission and compelling metaphor
The “Digital Elf” concept is memorable and makes software concepts approachable for a non-technical healthcare audience. The site description and content consistently reinforce this vision.
2. Strong educational content
The 15 published posts form a well-structured learning path — from Excel basics through Python, Pandas, regex, Jupyter notebooks, and data exploration. Each tutorial is practical and grounded in real healthcare scenarios.
3. Solid deployment pipeline
The GitHub Actions workflow for Jekyll deployment is clean, uses proper caching, and follows best practices with concurrency controls to prevent overlapping deployments.
4. Distinctive visual identity
The retro pixel-art aesthetic with “Press Start 2P” font and OKLCH color system gives the site a unique, playful personality that aligns well with the “elf” theme.
Issues and Recommendations
Code Quality
1. Typo in _layouts/home.html (line 24): "Our Aricles" should be "Our Articles".
2. Typo in _includes/footer.html (line 13): "get on with with clever stuff" — double “with”.
3. Duplicate CSS declarations in assets/css/components.css. Lines 82-106 define .page-title, .post-title and .day-title, .home p:first-child with nearly identical properties. This should be a single shared class.
4. Orphaned CSS selector at end of assets/css/components.css (line 299): body > header > div > nav > div > a:nth-child(1) appears as an incomplete rule with no properties — this is a syntax error that could cause parsing issues.
5. Hardcoded color in assets/css/components.css (line 278): .article-excerpts uses rgb(17,19,24) while the rest of the file uses CSS custom properties. This should use var(--dark-gray) or a new variable for consistency.
6. Excessive !important declarations. The Mailchimp override section (lines 120-171) has many !important flags. Consider increasing specificity through selectors instead, or scoping with a wrapper class.
7. Invalid CSS in _includes/head.html (line 27): #mc_embed_signup{background:#fff; false;clear:left;...} — false; is not valid CSS and may cause unpredictable rendering.
Architecture & Structure
8. No README. A project hosted on GitHub should have a README explaining how to set up locally, contribute, and build. This is particularly important for a project that aims to teach technical skills.
9. Jekyll 3.9.3 is outdated. Jekyll 4.x has been the current major version for years. The github-pages gem pins to Jekyll 3.x, which limits features and may receive fewer security updates. Consider whether GitHub Pages’ built-in Jekyll is still the right deployment approach, or move to a custom build with Jekyll 4.
10. Missing jekyll gem in Gemfile. The Gemfile depends on github-pages (which bundles Jekyll), but doesn’t explicitly declare a Jekyll version. This makes the dependency implicit and harder to reason about.
11. Mermaid configuration points to a missing file. _config.yml references assets/mermaid.js but this file doesn’t exist in the repository. Either add the file or remove the configuration.
12. No .ruby-version file. The CI uses Ruby 3.1 but there’s no .ruby-version to ensure local development matches.
Content & SEO
13. Content gap since January 2024. All 15 posts are from a ~6-week window (Dec 2023–Jan 2024), with 5 drafts never published. A blog that stops updating loses credibility and search rankings. Consider publishing the drafts or adding a note about the project’s status.
14. Missing Open Graph / social meta tags. The `
` tag from jekyll-seo-tag handles basic SEO, but there are no custom OG images or Twitter cards defined. Sharing the site on social media would show generic or missing previews.
15. No alt text on many images. The footer VP logo has generic alt text ("VP Logo"), and post content images likely lack descriptive alt text. This hurts both accessibility and SEO.
Security & Performance
16. Mailchimp CSS loaded on every page. The Mailchimp stylesheet is loaded globally in _includes/head.html even though the subscription form only appears on the homepage. This adds unnecessary blocking CSS to every page load.
17. Google Fonts loaded without preloading. The Google Fonts import in components.css uses display=swap in the URL (good), but the font import is via CSS @import which is render-blocking. A <link rel="preload"> approach in the HTML head would be faster.
18. No Content Security Policy headers. The site loads scripts from Google Analytics and fonts from Google — a CSP header would provide defense-in-depth against XSS.
Missing Practices
19. No tests or linting. Even for a static site, HTML validation (e.g., htmlproofer), link checking, and CSS linting would catch issues like the orphaned selector and invalid CSS mentioned above. These could run in CI.
20. No robots.txt or custom sitemap.xml configuration. While jekyll-sitemap generates a sitemap, there’s no robots.txt to guide crawlers.
21. Images are not optimized. 57 images totaling ~7.5MB with no evidence of compression, WebP conversion, or responsive srcset usage. This significantly impacts page load on mobile.
Priority Recommendations
| Priority | Action |
|---|---|
| Quick wins | Fix typos (home.html, footer.html), remove orphaned CSS selector, fix invalid CSS in head.html |
| Short-term | Add README, optimize images, extract duplicate CSS into shared class, add .ruby-version
|
| Medium-term | Add htmlproofer to CI, publish or retire drafts, preload fonts, lazy-load Mailchimp CSS |
| Long-term | Evaluate Jekyll 4 migration, add social meta tags, implement CSP headers, establish content cadence |