RubyGems - datalog-theme - Versions diffs - 0.6.0 - Mend

datalog-theme 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (180) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +162 -0
data/CITATION.cff +29 -0
data/LICENSE +21 -0
data/README.md +257 -0
data/_data/academic.yml +217 -0
data/_data/cdn-integrity.yml +51 -0
data/_data/config/author.yml +121 -0
data/_data/config/features.yml +262 -0
data/_data/config/site.yml +42 -0
data/_data/config/theme.yml +181 -0
data/_data/datasets.yml +28 -0
data/_data/i18n/en.yml +438 -0
data/_data/i18n/es.yml +438 -0
data/_data/i18n/pt.yml +438 -0
data/_data/js_manifest.json +22 -0
data/_data/js_meta.json +371 -0
data/_data/navigation.yml +145 -0
data/_data/projects.yml +41 -0
data/_data/publications.yml +28 -0
data/_data/social.yml +73 -0
data/_data/visualizations.yml +51 -0
data/_includes/analytics/dashboard.html +149 -0
data/_includes/analytics.html +9 -0
data/_includes/components/academic-dashboard.html +347 -0
data/_includes/components/advanced-search.html +682 -0
data/_includes/components/api-function.html +94 -0
data/_includes/components/author-bio.html +166 -0
data/_includes/components/bookmark-system.html +96 -0
data/_includes/components/breadcrumbs.html +89 -0
data/_includes/components/citation-tools.html +94 -0
data/_includes/components/comments.html +244 -0
data/_includes/components/content-provenance.html +43 -0
data/_includes/components/content-recommendations.html +228 -0
data/_includes/components/difficulty-badge.html +84 -0
data/_includes/components/email-preferences.html +200 -0
data/_includes/components/enhanced-code-block.html +212 -0
data/_includes/components/enhanced-metadata.html +228 -0
data/_includes/components/enhanced-toc.html +209 -0
data/_includes/components/hero.html +15 -0
data/_includes/components/language-switcher.html +396 -0
data/_includes/components/math-fallback.html +19 -0
data/_includes/components/navigation-enhancements.html +454 -0
data/_includes/components/newsletter-signup.html +178 -0
data/_includes/components/open-science-badges.html +16 -0
data/_includes/components/package-install.html +194 -0
data/_includes/components/performance-monitor.html +170 -0
data/_includes/components/popular-posts.html +233 -0
data/_includes/components/post-hero.html +62 -0
data/_includes/components/reading-progress.html +133 -0
data/_includes/components/reading-time.html +121 -0
data/_includes/components/responsive-image.html +63 -0
data/_includes/components/search-facets.html +307 -0
data/_includes/components/series-navigation.html +124 -0
data/_includes/components/social-proof.html +34 -0
data/_includes/components/social-share.html +119 -0
data/_includes/components/user-preferences.html +566 -0
data/_includes/components/visualization-card.html +24 -0
data/_includes/components/viz-table-fallback.html +19 -0
data/_includes/critical-css/default.html +0 -0
data/_includes/critical-css/home.html +0 -0
data/_includes/critical-css/post.html +0 -0
data/_includes/csp-meta.html +17 -0
data/_includes/footer/nav-column.html +31 -0
data/_includes/footer.html +76 -0
data/_includes/head.html +337 -0
data/_includes/header/navigation.html +48 -0
data/_includes/header.html +70 -0
data/_includes/helpers/array-to-sentence.html +21 -0
data/_includes/helpers/date-format.html +16 -0
data/_includes/helpers/link-with-icon.html +26 -0
data/_includes/layouts/default/article.html +67 -0
data/_includes/meta/language-attributes.html +25 -0
data/_includes/meta/math-config.html +21 -0
data/_includes/meta/schema.html +153 -0
data/_includes/meta/scripts-loader.html +52 -0
data/_includes/post/related-posts.html +63 -0
data/_includes/scripts.html +72 -0
data/_includes/skip-link.html +1 -0
data/_includes/toc.html +2 -0
data/_layouts/archive.html +282 -0
data/_layouts/dataset.html +52 -0
data/_layouts/default.html +33 -0
data/_layouts/home.html +48 -0
data/_layouts/notebook.html +173 -0
data/_layouts/package.html +238 -0
data/_layouts/page.html +16 -0
data/_layouts/portfolio.html +41 -0
data/_layouts/post-sidebar.html +183 -0
data/_layouts/post.html +338 -0
data/_layouts/project.html +252 -0
data/_layouts/research.html +504 -0
data/_plugins/analytics_dashboard.rb +315 -0
data/_plugins/config_validator.rb +397 -0
data/_plugins/csp_generator.rb +115 -0
data/_plugins/datalog_bibliography.rb +19 -0
data/_plugins/datalog_comments.rb +18 -0
data/_plugins/datalog_slides.rb +20 -0
data/_plugins/front_matter_compat.rb +109 -0
data/_plugins/i18n.rb +160 -0
data/_plugins/image_optimizer.rb +445 -0
data/_plugins/math_preprocessor.rb +185 -0
data/_plugins/notebook_converter.rb +1107 -0
data/_plugins/plugin_loader.rb +185 -0
data/_plugins/publications_generator.rb +234 -0
data/_plugins/reading_time.rb +15 -0
data/_plugins/search_normalizer.rb +74 -0
data/_plugins/sri_filter.rb +18 -0
data/_plugins/toc_filter.rb +68 -0
data/_plugins/warning_filter.rb +3 -0
data/_sass/_base.scss +142 -0
data/_sass/_components.scss +2380 -0
data/_sass/_header.scss +470 -0
data/_sass/_interactive.scss +344 -0
data/_sass/_layout.scss +1760 -0
data/_sass/_mathematical.scss +368 -0
data/_sass/_mixins.scss +99 -0
data/_sass/_package-docs.scss +715 -0
data/_sass/_phase1-enhancements.scss +721 -0
data/_sass/_phase3-enhancements.scss +874 -0
data/_sass/_phase4-enhancements.scss +1214 -0
data/_sass/_phase5-enhancements.scss +414 -0
data/_sass/_search.scss +654 -0
data/_sass/_syntax-highlighting.scss +128 -0
data/_sass/_theme.scss +79 -0
data/_sass/_typography.scss +148 -0
data/_sass/_utilities.scss +334 -0
data/_sass/_variables.scss +153 -0
data/_sass/_visualizations.scss +242 -0
data/assets/css/main.scss +4 -0
data/assets/img/20220607123041_detail.001.png +0 -0
data/assets/img/favicons/android-chrome-192x192.png +0 -0
data/assets/img/favicons/android-chrome-512x512.png +0 -0
data/assets/img/favicons/apple-touch-icon.png +0 -0
data/assets/img/favicons/favicon-16x16.png +0 -0
data/assets/img/favicons/favicon-32x32.png +0 -0
data/assets/img/favicons/favicon.ico +0 -0
data/assets/img/favicons/site.webmanifest +21 -0
data/assets/img/portfolio-placeholder.svg +20 -0
data/assets/js/academic.js +262 -0
data/assets/js/analytics-dashboard.js +382 -0
data/assets/js/core/dark-mode.js +79 -0
data/assets/js/core/github-cards.js +123 -0
data/assets/js/core/language-filter.js +69 -0
data/assets/js/core/navigation.js +184 -0
data/assets/js/core/scroll-progress.js +45 -0
data/assets/js/core/search-hotkeys.js +62 -0
data/assets/js/core/skip-links.js +62 -0
data/assets/js/loader.js +163 -0
data/assets/js/main.js +23 -0
data/assets/js/math.js +818 -0
data/assets/js/notebook.js +158 -0
data/assets/js/search/analytics.js +91 -0
data/assets/js/search/app.js +271 -0
data/assets/js/search/autocomplete.js +120 -0
data/assets/js/search/engine.js +260 -0
data/assets/js/search/filters.js +38 -0
data/assets/js/search/render.js +217 -0
data/assets/js/search/utils.js +99 -0
data/assets/js/search.js +354 -0
data/assets/js/visualizations.js +816 -0
data/assets/publications/datalog-publications.bib +8 -0
data/assets/publications/datalog-publications.ris +9 -0
data/assets/publications/publications.bib +30 -0
data/assets/templates/diogo-ribeiro-cv.md +31 -0
data/assets/templates/diogo-ribeiro-cv.tex +32 -0
data/bin/datalog +26 -0
data/datalog-theme.gemspec +72 -0
data/lib/datalog/cli.rb +563 -0
data/lib/datalog/plugin_system/dependency_resolver.rb +223 -0
data/lib/datalog/plugin_system.rb +237 -0
data/lib/datalog/plugins/citations.rb +182 -0
data/lib/datalog/plugins/comments.rb +183 -0
data/lib/datalog/plugins/search.rb +45 -0
data/lib/datalog/plugins/slides.rb +121 -0
data/lib/datalog/theme/theme.rb +18 -0
data/lib/datalog/theme/version.rb +7 -0
data/lib/datalog/warning_filter.rb +28 -0
data/lib/datalog-theme.rb +17 -0
metadata +555 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 874bd029803fe40f44c18c940b5b7bd68b09aa30f93701157489606d588e6910
+  data.tar.gz: 05442a3323747f722dea8ce44bd3fe2fb3aa27b95cb1d80ef86d750dffbbb8bf
+SHA512:
+  metadata.gz: 5a65616289705e0e7bd754fd6b88b699932eb7c90b28ea0c758e0f9e7a231d6f8a9d32707323746d7fe200c6f239257ab3bb291073b0005b466953baa20f8f0f
+  data.tar.gz: 0706167a0c44b2bd49ac70139eb909972468824389afa4eb2c8388e514f7bed244a76e16a7b2d966af75e61e013c535020925996492f848f1720166838f7404c

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,162 @@
+# Changelog
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.6.0] - 2026-09-11
+### Added
+- `tocify` Liquid filter (`_plugins/toc_filter.rb`): the table-of-contents includes called `content | tocify` but no plugin defined it, so the aside rendered the whole article. The filter builds nested `toc-list` lists from the rendered headings within the requested level range.
+- `show_author: false` in front matter hides the byline in the article meta, for pages that are site chrome rather than articles.
+- The footer's "Explore" column reads `footer:` from `_data/navigation.yml` when present, falling back to the demo sections.
+### Fixed
+- Prism was blocked on every page by a stale integrity hash for `prism.min.js` in `_data/cdn-integrity.yml`; the hashes are regenerated.
+- The `<head>` emitted every SEO tag twice (title, description, Open Graph, Twitter, canonical, JSON-LD) because `{% seo %}` duplicated the theme's own markup; the tag is gone.
+- The Content Security Policy blocked MathJax's accessibility data (`connect-src` now allows jsDelivr) and logged an error for a `report-uri` directive that `<meta>` policies cannot carry.
+- The home-page hero set its background through a `style` attribute the policy blocks; it now uses a nonced style element.
+- The header's search row overflowed the viewport on phones; it wraps below the brand now.
+- `<body data-theme>` stays in sync with the effective theme when either theme control is used.
+- The visualizations gallery's Plotly block gained the status, meta and toolbar markup the script and the docs expect.
+- The `<head>` now writes the `<title>` itself for every page (`Page | Site`, or the site title on the home page); it used to rely on the removed SEO tag when no `seo_title` was set.
+- Google Analytics was loaded with an empty measurement id because `google_analytics: ""` is truthy in Liquid; the tag is emitted only when an id is set.
+- Google Fonts CSS and `gtag.js` are exempt from subresource integrity (both are served per-browser); the generator also ignores scratch directories, and the validator skips the notebook iframe documents nbconvert writes.
+- Internal links written as root-absolute paths (the 404 page, the getting-started and tools pages, two posts, and the portfolio, post, package and project layouts) now go through `relative_url`, so the site works under a base path. A `browserconfig.xml` reference to a file that does not ship is gone.
+- The deploy workflow builds the published artifact with the Pages base path, and runs the integration suite without the Percy-only `@visual` specs. `npm run test:integration` excludes those specs too, and the runner can start its static server on Windows.
+- The archive layout grouped posts with `where_exp` expressions containing filters, which Jekyll's Liquid cannot parse; posts are now grouped by year and month with plain loops. Posts without a `difficulty` no longer trigger "Empty `slug` generated" warnings.
+- The page layout printed the title and subtitle a second time above the article scaffold, which already renders them.
+- The math preprocessor hooked both `documents` and `posts`, so every post was processed twice and display math came out nested. The inline pattern also matched the `$` of a `$$` block; it now requires single delimiters on both sides.
+- `{% t %}` with a quoted key leaked the closing quote into the first option name, so `{% t 'post.reading_time' minutes=... %}` printed a literal `{{minutes}}`.
+- Overlay post heroes set the background through an inline `style` attribute, which the Content Security Policy blocks. The image is now applied by a nonce'd `<style>` element scoped to the hero's id.
+- Card thumbnails on card grids were stretched by the `height` attribute the image optimizer adds and by the grid stretching card bodies. Cards now keep their intrinsic thumbnail ratio and align their content to the top.
+- The skip link peeked into the viewport before it received focus; it is now moved fully out of view until focused.
+## [0.5.0] - 2026-09-11
+### Added
+- Minimal Mistakes front-matter compatibility (`_plugins/front_matter_compat.rb`): `header.image`, `header.overlay_image`, `header.teaser`, `header.og_image` and `header.twitter_image` map to a `post_hero` hash, `teaser`, `image`, `og_image` and `twitter_image`; `seo_description` fills `description`; a string `classes` value becomes a list. Explicit DataLog fields always win.
+- Post hero component (`components/post-hero.html`): a title-over-image hero for overlay images and a figure for plain header images, with the Minimal Mistakes overlay filter syntax.
+- `seo_title` support: when set, the `<title>` element and the social titles use it while the heading keeps the real title.
+- `subtitle` rendered under the post title, and inside overlay heroes.
+- Editorial provenance note (`components/content-provenance.html`) from `why_this_exists`, `evidence`, `methodology` and `reviewed_at`, with translations in all locales.
+- Teaser thumbnails on home-page cards and related-post cards when a post has a `teaser`.
+- `body.wide` styling so `classes: wide` lifts the reading measure inside the article.
+- `jekyll-redirect-from` as a runtime dependency and demo plugin, so `redirect_from` front matter keeps old URLs alive.
+- Tag and category links honour `site.tag_archive.path` and `site.category_archive.path`, the keys Minimal Mistakes uses, defaulting to `/tags/` and `/categories/`.
+- A demo post written entirely in Minimal Mistakes front matter, a migration guide (`docs/migrating-from-minimal-mistakes.md`) and `tests/test_front_matter_compat.rb`.
+### Fixed
+- The image optimizer re-serialised any page containing a local image from an HTML fragment, which dropped the `<!DOCTYPE>`, `<html>` and `<head>` elements from the output. Full documents are now parsed and written back as documents.
+### Changed
+- The meta description now prefers an explicit `description` (or `seo_description`) over the auto-generated excerpt; previously the excerpt won even when a description was set.
+## [0.4.0] - 2026-04-25
+### Added
+- Full author profile on the about page: photo placeholder, skills grid, experience timeline, education cards, and expanded `_data/config/author.yml` with skills/education/experience/bio fields.
+- Sun/moon SVG icons for the dark mode toggle.
+- Consolidated `requirements.txt` for Python dependencies, replacing duplicated `pip install nbformat jupyter` invocations across 7 workflows, both Dockerfiles, and `scripts/setup-dev.sh`.
+- Test-tier matrix in `TESTING.md` documenting which workflows gate merges versus run on cron or release events.
+- Repository layout table in `README.md` clarifying which paths ship in the gem versus which are demo content.
+- Top-level link to `.env.example` from `README.md`.
+- `bin/datalog` CLI executable is now tracked in git so the `datalog-theme` gem actually ships its declared executable.
+### Changed
+- Dependabot now targets the `develop` branch across all four ecosystems.
+- `INSTALL.md` and `PLUGIN_DEVELOPMENT.md` moved under `docs/` (`docs/install.md`, `docs/plugin-development.md`).
+- `GISCUS_REPO_ID` and `GISCUS_CATEGORY_ID` placeholder strings in `_config.yml` are now empty defaults pointing to <https://giscus.app>.
+- `datalog-theme.gemspec` `spec.files` switched from a permissive deny-list to an allow-list. The packaged gem now ships only theme infrastructure (`_layouts/`, `_includes/`, `_sass/`, `_plugins/`, `_data/`, `assets/`, `lib/`, `bin/`) plus `LICENSE`, `README.md`, `CHANGELOG.md`, and `CITATION.cff` — down from ~440 files to ~175. Demo content (`_posts/`, `_pages/`, `_portfolio/`, `_datasets/`, `_packages/`, `_notebooks/`), tests, docs, scripts, CI configs, and frontend tooling no longer ship to RubyGems consumers.
+### Removed
+- Stale auto-generated `REPOSITORY_ANALYSIS.md` and `ANALYSIS_EXECUTIVE_SUMMARY.md` snapshots.
+- Tracked CSP test artifact `csp-report.html` (now gitignored).
+- Dead duplicate `_data/config/integrations.yml` (the live source is `site.integrations` in `_config.yml`).
+- Redundant `demo/` stub directory (its README only restated that the repo root is the demo site).
+## [0.3.0] - 2026-03-18
+### Added
+- Production Dockerfile with multi-stage nginx build and `.dockerignore`.
+- ESLint flat config for browser JS, Node scripts, and Vitest tests.
+- RuboCop config with auto-fixed style issues across all Ruby files.
+- Unit tests for 6 previously untested Ruby plugins: reading_time, sri_filter, math_preprocessor, image_optimizer, publications_generator, warning_filter (69 tests, 199 assertions).
+- Navigation module tests improving coverage from 84% to 96%.
+- Search engine tests improving coverage from 79% to 97%.
+- Skip-links accessibility tests improving coverage from 88% to 96%.
+- Search engine test suite with 48 tests covering scoring, filters, fuzzy matching, and edge cases.
+- Quarterly coverage review process with Q1 2026 baseline snapshot.
+- Monthly security audit issue template.
+- Stale issue/PR automation workflow with safe label exemptions.
+- Release workflow for promoting develop to main with changelog gate.
+- Project automation workflow for syncing priority labels to project fields.
+- Branch-trigger policy, action-pinning policy, npm audit policy, Gemfile.lock strategy, and release process documentation.
+- Issue SLA policy (P0–P3) in CONTRIBUTING.md with issue template link.
+- Coverage review GitHub issue template.
+- Security audit GitHub issue template.
+- Top-level TESTING.md with quick-reference commands.
+- Missing /research/ page for navigation.
+- Missing favicon files (favicon.ico, 16x16, 32x32, 512x512, apple-touch-icon).
+### Changed
+- Redesigned homepage hero with background image and gradient overlay.
+- Redesigned header as compact two-row layout with horizontal nav links.
+- Redesigned footer from 11 sections to 4 clean sections plus copyright bar.
+- Redesigned blog page with card grid layout matching homepage.
+- Redesigned research page with citation metrics, area cards, submissions, and profiles.
+- Redesigned projects page with featured project cards and performance metrics.
+- Redesigned datasets page with license badges, schema info, and external resources.
+- Redesigned packages page with theme-consistent card grid.
+- Redesigned academic ops page with citation chart, submissions, events, and funding.
+- Redesigned about page with data-driven header, publication cards, and community cards.
+- Switched font family from Roboto to IBM Plex (Sans, Serif, Mono).
+- Rebalanced color palette from all-blue to warm neutrals with teal/purple accents.
+- Recalibrated coverage gates from 80/70/75/80 to 88/78/83/88 with per-module thresholds.
+- Expanded config validator schema to cover markdown, highlighter, paginate, sass, features, notebooks, and SEO.
+- Updated all CI workflows to target develop as default branch.
+- Pinned all 16 GitHub Actions to commit SHAs across 11 workflow files.
+- Upgraded lint-staged to run ESLint instead of echoing messages.
+- Updated husky pre-commit hook: removed deprecated shebang, audit production deps only.
+- Stripped console calls from production JS bundles via esbuild drop option.
+- Made bundler-audit fail CI on actionable vulnerabilities.
+- Guarded Codecov upload with secret availability check.
+- Migrated deprecated Sass darken() calls to color.adjust().
+### Fixed
+- Main stylesheet loading synchronously when critical CSS is disabled (was deferred behind useless placeholder comment).
+- SRI filter producing malformed HTML with doubled quote characters.
+- Liquid syntax errors in research layout (Python-style and/or operators).
+- Excluded docs/ directory from Jekyll build (eliminated missing 'doc' layout warnings).
+- Broken documentation URL in site config.
+- Date format test made locale-independent in search-render.
+- RuboCop auto-fix that incorrectly renamed @identifier to @id in plugin system.
+- Removed simulated social-proof metrics (fabricated view counts, active readers, completion rates).
+- Removed newsletter subscribe form with no backend.
+### Security
+- Replaced 29 of 36 innerHTML usages with safer DOM APIs (replaceChildren, createElement, insertAdjacentHTML).
+- Ran npm audit fix resolving 10 safe vulnerabilities.
+- Created npm audit severity policy with exception process.
+- Added action-pinning policy for supply-chain hardening.
+## [0.2.0] - 2025-10-09
+### Added
+- Stability regression suite that validates notebook conversion, math rendering, search indexing, and visualization embeds during CI.
+- GitHub Actions workflow that provisions notebook tooling and runs the new stability suite on every push and pull request.
+- Comprehensive installation guide covering GitHub Pages deployment, local development, Docker workflows, configuration, and first-post authoring.
+- Interactive `bin/datalog` command-line tool for scaffolding content, verifying dependencies, publishing to GitHub Pages, and updating the theme.
+### Changed
+- Bumped the theme version metadata and citation to publish the 0.2.0 release artifacts.
+## [0.1.0] - 2024-02-29
+### Added
+- Initial public release with the core DataLog Jekyll theme, demo content, and documentation.

data/CITATION.cff ADDED Viewed

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+title: "DataLog Jekyll Theme"
+message: "If you use this theme, please cite it as below."
+authors:
+  - family-names: Ribeiro
+    given-names: Diogo
+    email: diogo.debastos.ribeiro@gmail.com
+    affiliation: ESMAD - Instituto Politécnico do Porto
+    orcid: https://orcid.org/0009-0001-2022-7072
+identifiers:
+  - type: url
+    value: https://github.com/DiogoRibeiro7/analytics-blog-jekyll
+repository-code: https://github.com/DiogoRibeiro7/analytics-blog-jekyll
+abstract: >-
+  DataLog is an academic-grade Jekyll theme created for data scientists and researchers.
+  It offers integrated notebook publishing, advanced math rendering, interactive
+  visualization workflows, and reproducibility tooling optimised for open science communities.
+license: MIT
+version: 0.6.0
+date-released: 2026-09-11
+keywords:
+  - data-science
+  - jekyll
+  - research
+  - reproducibility
+  - academic-blogging
+contact:
+  email: dfr@esmad.ipp.pt
+  name: Diogo Ribeiro

data/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2024 Diogo Ribeiro
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md ADDED Viewed

@@ -0,0 +1,257 @@
+# DataLog — A Data Science Jekyll Theme
+[![Tests](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/test.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/test.yml)
+[![Deploy](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/deploy.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/deploy.yml)
+[![Gem Release](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/gem-release.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/gem-release.yml)
+[![Lighthouse CI](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/lighthouse.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/lighthouse.yml)
+[![Accessibility Audit](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/accessibility.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/accessibility.yml)
+[![Broken Link Scanner](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/broken-links.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/broken-links.yml)
+[![Citation Sync](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/update-citations.yml/badge.svg)](https://github.com/DiogoRibeiro7/analytics-blog-jekyll/actions/workflows/update-citations.yml)
+DataLog is a modern, academic-inspired Jekyll theme tailored for data scientists, researchers, and technical writers who need a clean platform to publish reproducible analyses, research papers, tutorials, datasets, and project showcases. The theme emphasizes accessibility, performance, and beautiful code presentation while remaining fully compatible with GitHub Pages.
+## Features
+- **Research-ready layouts** for posts, pages, datasets, and portfolio case studies
+- **Jupyter Notebook integration**: `.ipynb` files in `_notebooks/` become sanitized, CSP-safe pages via the theme's notebook converter
+- **Advanced MathJax tooling** with accessible numbering, cross-references, equation editor, and LaTeX copy helpers
+- **Optimized syntax highlighting** for Python, R, SQL, and Julia code blocks
+- **Responsive and accessible UI** that meets WCAG 2.1 AA guidelines
+- **SEO friendly** metadata (Open Graph, Twitter cards, canonical links, JSON-LD) and sitemap generation
+- **Interactive visualization hub** with lazy-loaded Plotly, D3.js, Bokeh, Observable, R Shiny, and Jupyter widget support plus export tooling
+- **Portfolio section** for highlighting research projects, experiments, and case studies
+- **Dataset collection** for sharing curated datasets with download links
+- **English-first header experience** with accessible labels and data-driven navigation out of the box
+- **Dark mode toggle** with preserved user preference
+- **Theme gem distribution** with GitHub Actions validation across Ruby, Python, and Node environments
+- **Academic citation tooling** via `CITATION.cff`, BibTeX, RIS, and EndNote exports
+- **Analytics operations hub** with a GA4-powered `/admin/analytics/` dashboard for top content, search trends, events, and Scholar metrics cached for 24 hours
+## Repository Layout
+This repository serves a dual purpose: it ships the **`datalog-theme` gem**
+*and* runs as a working **demo site** that previews every feature. When you
+consume DataLog as a theme, only the gem-side files are installed into your
+site; the rest is reference content you can copy from.
+| Role | Paths |
+| --- | --- |
+| Theme (shipped in the gem) | `lib/datalog/`, `_layouts/`, `_includes/`, `_sass/`, `assets/`, `_plugins/`, `datalog-theme.gemspec` |
+| Demo content (this site only) | `_posts/`, `_notebooks/`, `_portfolio/`, `_datasets/`, `_packages/`, `_pages/`, `index.md`, `404.html` |
+| Starter scaffold | `template/` — minimal seed for the [GitHub template repository](docs/template-repository.md); excluded from this site's build |
+| Configuration | `_config.yml`, `_data/`, `Gemfile`, `package.json`, `requirements.txt` |
+| Tests & tooling | `tests/`, `scripts/`, `Rakefile`, `vitest.config.js`, `playwright.config.js`, `pa11yci.json`, `lighthouserc.json`, `percy.config.yml` |
+| Docs | `docs/`, `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, `TESTING.md` |
+```
+.
+├── _config.yml                # Theme configuration with MathJax and syntax highlighting
+├── _data/
+│   ├── navigation.yml         # Global navigation structure
+│   ├── social.yml             # Academic and community profiles
+│   ├── publications.yml       # Publication settings and manual entries
+│   ├── datasets.yml           # Dataset catalog configuration
+│   └── projects.yml           # Portfolio showcase configuration
+├── _datasets/                 # Collection for dataset descriptions
+├── _includes/                 # Reusable components (head, footer, analytics, etc.)
+├── _layouts/                  # Page layouts (default, post, notebook, portfolio, dataset)
+├── _notebooks/                # Source notebooks rendered by _plugins/notebook_converter.rb
+├── _pages/                    # Standalone pages (About, Contact, etc.)
+├── _plugins/                  # Custom helpers (accessibility, filters, etc.)
+├── _portfolio/                # Portfolio items for data science projects
+├── _posts/                    # Blog posts and research updates
+├── _sass/                     # Sass partials used by the theme
+├── assets/
+│   ├── css/main.scss          # Compiled stylesheet entry point
+│   ├── img/                   # Images and cover art
+│   └── js/main.js             # Progressive enhancement scripts
+├── lib/datalog/               # Theme gem source (published as `datalog-theme`)
+├── Gemfile                    # Ruby dependencies (GitHub Pages compatible)
+├── .gitignore                 # Ignore build artifacts and notebook outputs
+└── README.md                  # Theme documentation (this file)
+```
+## Documentation
+- [Documentation Site](docs/site/README.md) — source for the live `datalog-theme.github.io` documentation hub with feature walk-throughs, interactive demos, and migration guides.
+- [User Guide](docs/user-guide.md) — comprehensive documentation covering installation, notebooks, math, visualizations, research workflows, accessibility, performance, and collaboration best practices for DataLog users.
+- [Environment Setup Guide](docs/environment-setup.md) — configure environment variables, secrets, and integrations for analytics, testing, and deployment.
+- [Scripts Reference](docs/scripts-reference.md) — complete reference for all build, test, import/export, and utility scripts.
+- [Changelog](CHANGELOG.md) — release highlights and upgrade guidance for each published version of the DataLog theme.
+- [Template Repository Guide](docs/template-repository.md) — instructions for publishing a GitHub template with starter content, configuration, and automated deployments.
+- [Installation Guide](docs/install.md) — prerequisites, GitHub Pages, local, and Docker setup paths.
+- [Migrating from Minimal Mistakes](docs/migrating-from-minimal-mistakes.md) — the front-matter fields DataLog reads natively (hero and teaser images, SEO title and description, `classes: wide`, `redirect_from`) and the settings that keep existing URLs.
+- [Plugin Development Guide](docs/plugin-development.md) — understand the hook system and learn how to package extensions for reuse.
+- [Security Policy](SECURITY.md) — report security vulnerabilities and learn about security best practices.
+- [Contributing Guidelines](CONTRIBUTING.md) — contribution workflow, code standards, and community guidelines.
+## Getting Started
+1. **Install dependencies**
+   ```bash
+   bundle install
+   ```
+2. **Configure environment** (optional)
+   Copy [`.env.example`](.env.example) to `.env` and fill in any keys you
+   need — GA4 credentials, Percy/Codecov tokens, Playwright base URL, etc.
+   All values are optional; the site runs without them, and features that
+   require credentials will skip cleanly. See
+   [docs/environment-setup.md](docs/environment-setup.md) for the full reference.
+3. **Run the development server**
+   ```bash
+   bundle exec jekyll serve
+   ```
+   JavaScript enhancements are bundled with [esbuild](https://esbuild.github.io/). After modifying files under `assets/js/`,
+   regenerate the production-ready scripts with:
+   ```bash
+   npm install
+   npm run build:js
+   ```
+4. **Create content**
+   - Add Markdown posts to `_posts/`
+   - Place Jupyter notebooks in `_notebooks/` and they will automatically publish as rich blog posts
+   - Document datasets in `_datasets/`
+   - Showcase research projects in `_portfolio/`
+### Command-line toolkit
+Use the bundled `bin/datalog` helper to scaffold content and manage deployments:
+```bash
+bin/datalog --help
+```
+- `bin/datalog new post` — walk through the interactive post generator with best-practice front matter.
+- `bin/datalog new notebook` — create a notebook landing page and starter `.ipynb` in one step.
+- `bin/datalog new project` — scaffold a portfolio entry with metadata and placeholder sections.
+- `bin/datalog check` — validate runtime dependencies, configuration, and optional tooling like Node.js.
+- `bin/datalog publish` — build the site and push the `_site` artifacts to your GitHub Pages branch via git worktrees.
+- `bin/datalog update` — upgrade the `datalog-theme` gem and refresh npm packages when applicable.
+### Analytics dashboard
+The `/admin/analytics/` workspace combines Google Analytics 4, notebook telemetry, and Google Scholar metrics:
+- Set `GA4_PROPERTY_ID` in your environment or `_config.yml` under `analytics.ga4_property_id`.
+- Provide service account credentials via `GA4_CREDENTIALS_JSON` (raw JSON) or `GA4_CREDENTIALS_PATH` (file path).
+- Data is cached for 24 hours in `.jekyll-cache/datalog-analytics.json` to keep builds fast and avoid rate limits.
+- Citations are pulled from `_data/academic.yml`; run `scripts/update_google_scholar.py` to refresh them automatically.
+Once configured, Chart.js visualizations will highlight top-performing posts, search queries, visitor trends, notebook downloads, demo launches, and automatically generated monthly rollups.
+### Notebook publishing workflow
+DataLog ships with an opinionated notebook-to-post pipeline tailored for technical storytelling:
+1. **Drop `.ipynb` files into `_notebooks/`** — the custom generator transforms each notebook into a permalink under `/blog/` while keeping a downloadable copy at `/notebooks/<slug>.ipynb`.
+2. **Leverage notebook metadata** — optional fields like `title`, `tags`, `keywords`, `difficulty`, and execution metadata will surface in the rendered article header and sidebar.
+3. **Preserve interactivity** — HTML outputs, Plotly figures, and widget placeholders are embedded automatically with responsive styling and dark-mode aware formatting.
+4. **Launch live sessions** — configure `notebooks.repository` and `notebooks.branch` in `_config.yml` to enable Binder and Google Colab links for each notebook, alongside GitHub source references and clone instructions.
+5. **Highlight execution context** — kernel information, cell counts, runtime summaries, error outputs, and git history are extracted to help readers gauge reproducibility at a glance.
+Matplotlib/Seaborn plots, LaTeX, and code syntax highlighting are optimized for both desktop and mobile viewing, while cell numbering and input/output differentiation mirror the native Jupyter experience.
+4. **Deploy to GitHub Pages**
+   - Push the repository to GitHub
+   - Enable GitHub Pages on the repository settings (use the `develop` branch)
+   - GitHub Pages will automatically build the site using the `github-pages` gem
+## Data Science Workflow Integration
+- **Version-controlled notebooks** — store `.ipynb` files inside `_notebooks/`
+- **Reproducible environments** — document dependencies in `environment.yml` or `requirements.txt`
+- **Interactive visualizations** — embed Plotly, Altair/Vega-Lite, or Observable notebooks using `<iframe>` or custom scripts
+- **Dataset documentation** — use the dataset collection to provide metadata, download links, and provenance for each dataset
+- **Research pipelines** — highlight end-to-end workflows with diagrams, metrics, and evaluation summaries
+## Theming & Customization
+- Update `_data/navigation.yml` to manage the global navigation items
+- Curate academic, social, and contact details in `_data/social.yml`
+- Manage featured projects, GitHub repositories, and demo links via `_data/projects.yml`
+- Synchronize datasets with `_data/datasets.yml` and the dataset configuration options in `_config.yml`
+- Import publications automatically by pointing `_data/publications.yml` to a BibTeX file (`assets/publications/publications.bib`)
+- Modify `_sass/datalog.scss` to customize colors, spacing, and typography
+- Override partials in `_includes/` to add analytics, consent banners, or custom JavaScript
+- Configure SEO metadata, author details, and pagination in `_config.yml`
+### Flexible configuration system
+The `_config.yml` file exposes an opinionated set of options crafted for research teams:
+- `theme_options.math` toggles between **MathJax** and **KaTeX** engines, equation numbering, and accessibility defaults.
+- `theme_options.syntax_highlighting` defines the Prism CDN, theme pairings for light/dark modes, and the language components to preload.
+- `theme_options.visualizations` controls default behaviour for Plotly, D3, Bokeh, Observable, Shiny, and widget embeds.
+- `theme_options.taxonomy`, `content.research_areas`, and `content.methodologies` organize content by research area and methodology for archive navigation.
+- `integrations.github` enables live repository metrics with caching support for portfolio cards, while Binder/Colab/Kaggle toggles control interactive notebook links.
+- `localization` and `filters.languages` still power multilingual content in data files, while the bundled header ships with English labels that can be customized by overriding `_includes/header.html`.
+Data-driven configuration allows you to publish or reorder projects, datasets, social profiles, and publication lists without modifying templates—everything is sourced from `_data/` files and the theme options block.
+### Academic & professional integrations
+- The **Academic Operations Hub** (`/academic/`) aggregates Google Scholar, ORCID, ResearchGate, and Academia.edu profiles, syncing citation metrics, per-publication counts, and bibliography exports generated from BibTeX sources.
+- Submission tracking panels display conference and journal deadlines with collaborator context, while the academic calendar filters workshops, funding calls, and special issues by type.
+- Grant overviews, collaboration opportunities, mentorship programs, and networking channels are all driven by `_data/academic.yml`, making it easy to publicize professional initiatives without editing templates.
+- Open science and reproducibility badges appear automatically across posts, research articles, datasets, and projects, reinforcing transparency commitments alongside standardized citation export controls (BibTeX, RIS, EndNote).
+## Installation
+Add the theme gem to your Jekyll site:
+```ruby
+gem "datalog-theme", "~> 0.1"
+```
+Then enable it in `_config.yml`:
+```yml
+theme: datalog-theme
+```
+For GitHub Pages, pin the `github-pages` gem and allow the included workflow to build and deploy the site automatically.
+## Continuous Integration & Testing
+The repository ships with a multi-language CI pipeline located in `.github/workflows/ci.yml`. It performs the following checks:
+- Ruby matrix builds (3.1 & 3.2) to compile the theme, run lint-style verifications, and execute the `ci:verify` Rake task.
+- Python notebook validation to ensure `.ipynb` files retain kernel metadata and can be published.
+- Node.js checks that interactive visualizations (Plotly, Observable, Bokeh, R Shiny, ipywidgets) remain wired up.
+- Accessibility, math rendering, syntax highlighting, and performance budgets enforced through scripts in the `scripts/` directory.
+Run the suite locally with:
+```bash
+bundle exec rake ci:verify
+```
+## Demo Site
+The repository doubles as a demo site and content laboratory. Explore the curated examples locally via `bundle exec jekyll serve` or review the walkthrough in [`demo/README.md`](demo/README.md) for deployment and navigation tips.
+## Citation & Academic Metadata
+If you reference DataLog in research outputs, cite it using the metadata in [`CITATION.cff`](CITATION.cff). Additional export formats are generated automatically in `assets/publications/` when you build the site.
+## Distribution & Community Integration
+Use the release checklist in [`docs/distribution.md`](docs/distribution.md) to publish new versions, submit the theme to the official Jekyll directory, and announce updates across data science communities.
+## Licensing & Contributions
+DataLog is released under the [MIT License](LICENSE). We welcome academic and industry contributions—see [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines covering notebooks, datasets, visualization enhancements, and accessibility improvements.
+## Accessibility
+DataLog ships with semantic HTML landmarks, skip navigation links, proper color contrast, and focus-visible states. Please review custom components to ensure they remain compliant with WCAG 2.1 AA standards.
+## License
+Released under the [MIT License](LICENSE). Review the academic integrity guidance in [`docs/user-guide.md`](docs/user-guide.md) before publishing derivative datasets or research outputs.