How sara-sabr/itstrategy works
Project type and purpose
• This is a documentation‐driven, static web site repository built with Jekyll (Ruby/GitHub Pages) and supplemented with a few Node.js scripts for link-checking and content validation.
• Its purpose is to manage and publish “IT Strategy” content: markdown pages (multi-language), blog posts, presentations, data tables, and static assets.
File structure
• Top‐level directories of interest:
• _layouts, _includes, _pages, _posts: Jekyll templating and content structure
• assets: CSS, JS, images, fonts, downloadable files
• _data: YAML data for tables, internationalization
• Root scripts: get-link-from-path.js, list-links.js, validate-broken-link.js
• CI config: .github/workflows/*, plus .markdown-link-check.json, .markdownlint.json
• Jekyll config: Gemfile, _config.yml
README insights
• CI tests are in place (Node.js CI workflow, link checks)
• Content is authored in markdown and then published in a generated HTML site via GitHub Pages
• Multi-language support (English/French) via separate directories and YAML i18n files
Main components
a. Source Code Repository (GitHub)
• Branches, PRs, content & code lives here
b. Developer Workstation
• Jekyll + Ruby + Node.js environment for local preview
c. Continuous Integration (GitHub Actions)
• Linting: markdownlint, style checks
• Link checking: markdown-link-check & custom Node.js scripts
• Test suite: file‐based validations
d. Build Engine (Jekyll & Node.js scripts)
• Reads: _config.yml, _data/*.yml, _includes, _layouts
• Processes: _pages, _posts, drawio (via export), presentations, wip-tec
• Outputs static HTML/CSS/JS into a build folder (e.g., /docs or _site)
e. Static Assets
• assets/css, assets/js, assets/images, assets/files served alongside HTML
f. Deployment Target (GitHub Pages)
• Serves the static site over HTTPS
• Optionally backed by a CDN
g. Consumers
• Web browsers, translators (French/English), external stakeholders
Relationships & Interactions
• Developer pushes markdown/JS/Ruby code to GitHub → triggers CI workflows
• CI workflows run linters → custom Node.js link validators → Jekyll build → artifact deployment
• Artifacts (HTML + assets) are published to GitHub Pages → public website
Architectural patterns/design principles
• Static Site Generation (SSG) pattern: decoupling of content authoring and runtime server
• Convention over Configuration via Jekyll directory naming
• CI/CD pipeline enforcing quality gates before deployment
• Separation of concerns: content (_pages, _posts) vs. presentation (_layouts, _includes) vs. data (_data) vs. assets
Technologies & frameworks
• Ruby/Jekyll for SSG
• GitHub Actions for CI/CD
• Node.js scripts (list-links.js, validate-broken-link.js)
• Markdown, YAML, SCSS, vanilla JavaScript
Elements
• Developer → GitHub → CI → Build → Deploy → Browser
• Content sources (green)
• Build tools & scripts (orange)
• Templates & config (blue)
• External services (purple)
• Output/hosting (grey)
Final checklist
• How _data feeds into templates in the build process
• CI stages in sequential order (lint → link-check → build → deploy)
• Clearly distinguish between local preview (developer workstation) and CI environment