DataLog — A Data Science Jekyll Theme

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.

• 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

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.

.
├── _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 Index — every guide, grouped by what you want to do.
• Documentation Site — source for the live datalog-theme.github.io documentation hub with feature walk-throughs, interactive demos, and migration guides.
• User Guide — comprehensive documentation covering installation, notebooks, math, visualizations, research workflows, accessibility, performance, and collaboration best practices for DataLog users.
• Environment Setup Guide — configure environment variables, secrets, and integrations for analytics, testing, and deployment.
• Scripts Reference — complete reference for all build, test, import/export, and utility scripts.
• Changelog — release highlights and upgrade guidance for each published version of the DataLog theme.
• Template Repository Guide — instructions for publishing a GitHub template with starter content, configuration, and automated deployments.
• Installation Guide — adding the theme to a site, installing from a Git checkout, publishing with GitHub Actions, and local and Docker setup.
• Post Components — sharing buttons, breadcrumbs, author cards, the table of contents and difficulty badges.
• Migrating from Minimal Mistakes — 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 — understand the hook system and learn how to package extensions for reuse.
• Security Policy — report security vulnerabilities and learn about security best practices.
• Contributing Guidelines — contribution workflow, code standards, and community guidelines.

1. Install dependencies

   bundle install

2. Configure environment (optional)

   Copy .env.example to .env and fill in any keys you need — GA4 credentials, the Codecov token, 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 for the full reference.

3. Run the development server

   bundle exec jekyll serve

   JavaScript enhancements are bundled with esbuild. After modifying files under assets/js/, regenerate the production-ready scripts with:

   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/

Use the bundled bin/datalog helper to scaffold content and manage deployments:

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.

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.

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 page under /notebooks/<slug>/ 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
   • The build GitHub Pages runs by itself cannot load the theme's plugins, so build and publish with GitHub Actions: see Publish with GitHub Pages
   • .github/workflows/deploy.yml publishes this repository's demo site that way

• 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

• 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

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.
• Code blocks are highlighted by Rouge when the site builds, and the theme styles Rouge's output for light and dark mode, so code needs no settings.
• 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.

• 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).

Add the theme gem to your Jekyll site:

gem "datalog-theme", "~> 0.10.0"

The constraint takes the patch releases of the current minor series. Until 1.0 a minor release may include breaking changes, listed in the changelog.

Then enable it in _config.yml. Naming the theme under plugins: registers its Liquid tags, and the build needs an author name:

theme: datalog-theme
plugins:
  - datalog-theme
author:
  name: Your Name

The installation guide covers the files a site supplies itself, installing from Git (a release tag, main for the latest release, or develop for unreleased work), and publishing to GitHub Pages. GitHub Pages cannot build a site that uses this theme by itself, so the guide publishes it with GitHub Actions.

The Tests workflow (.github/workflows/test.yml) runs on every pull request:

• Vitest unit tests for the JavaScript, with coverage thresholds.
• A Jekyll build of the demo site, then the Minitest suite against the output: plugins, templates, the Content Security Policy, packaging and performance budgets.
• Playwright browser tests, including axe accessibility checks in both themes.
• ESLint and RuboCop.

Separate workflows audit dependencies and run CodeQL, Pa11y and Lighthouse. Run the unit and Ruby suites locally with:

npm test
bundle exec rake test

The repository doubles as a demo site and content laboratory, published at https://diogoribeiro7.github.io/analytics-blog-jekyll/. Explore the curated examples locally with bundle exec jekyll serve.

If you reference DataLog in research outputs, cite it using the metadata in CITATION.cff. Additional export formats are generated automatically in assets/publications/ when you build the site.

Use the release checklist in docs/distribution.md to publish new versions, submit the theme to the official Jekyll directory, and announce updates across data science communities.

DataLog is released under the MIT License. We welcome academic and industry contributions—see CONTRIBUTING.md for guidelines covering notebooks, datasets, visualization enhancements, and accessibility improvements.

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.

Released under the MIT License. Review the academic integrity guidance in docs/user-guide.md before publishing derivative datasets or research outputs.