improve theme: update deps, fix bugs, add a11y/perf/ci/dx/docs improvements

Author: abhinavs

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+indent_size = 4
+trim_trailing_whitespace = false

.github/workflows/build.yml

@@ -0,0 +1,23 @@
+name: Build
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build site
+        run: JEKYLL_ENV=production bundle exec jekyll build
+        env:
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pages.yml

@@ -0,0 +1,43 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Build site
+        run: JEKYLL_ENV=production bundle exec jekyll build -d ./_site
+        env:
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.ruby-version

@@ -0,0 +1 @@
+3.3.1

404.html

@@ -1,25 +1,8 @@
 ---
+layout: default
+title: Page not found
 permalink: /404.html
-layout: post
 ---
 
-<style type="text/css" media="screen">
-  .container {
-    margin: 1em auto;
-    max-width: 60em;
-    text-align: center;
-  }
-  h1 {
-    margin: 30px 0;
-    font-size: 4em;
-    line-height: 1;
-    letter-spacing: -1px;
-  }
-</style>
-
-<div class="container">
-  <h1>404</h1>
-
-  <p><strong>Page not found :(</strong></p>
-  <p>The requested page could not be found.</p>
-</div>
+<h1>404</h1>
+<p>Page not found. <a href="{{ "/" | relative_url }}">Head back home</a>.</p>

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## Unreleased
+
+### Added
+- GitHub Markdown Alerts (admonitions) support - NOTE, TIP, IMPORTANT, WARNING, CAUTION
+- Light mode syntax highlighting with proper contrast
+- Tag archive page with clickable tags in posts
+- 404 page with themed layout
+- Skip-to-content link for keyboard and screen reader users
+- `prefers-reduced-motion` support for theme transitions
+- `aria-label` and `aria-pressed` on theme toggle button
+- `robots.txt` with sitemap reference
+- `jekyll-sitemap` for automatic sitemap generation
+- `.ruby-version` file for consistent Ruby version management
+- `.editorconfig` for cross-editor formatting consistency
+- `bin/build` script for production builds
+- `Makefile` with setup, serve, build, and clean targets
+- `netlify.toml` deployment configuration
+- GitHub Actions workflows for build validation and Pages deployment
+- Font preconnect hints for faster loading
+- DNS prefetch for Soopr SDK
+
+### Changed
+- Moved Google Fonts from render-blocking SCSS imports to non-blocking link tags
+- Updated gem dependencies: Jekyll ~> 4.3, rouge ~> 4.2, jekyll-feed ~> 0.17, webrick ~> 1.8
+- Theme toggle button uses static positioning on mobile (no longer overlaps content)
+- Improved `bin/bootstrap` with Ruby version check
+- Improved `bin/start` with `--livereload` and passthrough flags
+- Soopr twitter handle now reads from `_config.yml` instead of being hardcoded
+- Tags in posts now link to tag archive page
+- Improved 404 page with minimal themed layout
+- Gemspec now includes `_data/` directory in packaged files
+
+### Fixed
+- Undefined CSS variable `--border` in blockquote styles (now uses `--text`)

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing to Moonwalk
+
+Bug reports and pull requests are welcome.
+
+## Development setup
+
+1. Fork and clone the repo
+2. Make sure you have Ruby installed (see `.ruby-version` for the recommended version)
+3. Run `bin/bootstrap` to install dependencies
+4. Run `bin/start` to launch the dev server at `http://127.0.0.1:4000`
+
+You can also use `make serve` and `make build` if you prefer.
+
+## Making changes
+
+- Keep the theme minimal - avoid adding heavy dependencies or complex JavaScript
+- Test both light and dark mode for any visual changes
+- Make sure the site builds cleanly with `bin/build`
+- If adding a new config option, document it in `_config.yml` with a comment
+
+## Pull requests
+
+- Keep PRs focused on a single change
+- Describe what the change does and why
+- Include a screenshot if the change is visual

Gemfile.lock

@@ -2,75 +2,93 @@ PATH
   remote: .
   specs:
     moonwalk (0.1.3)
-      jekyll (~> 4.2.0)
-      jekyll-feed (~> 0.15.0)
+      jekyll (~> 4.3)
+      jekyll-feed (~> 0.17)
+      jekyll-sitemap (~> 1.4)
       jekyll-soopr-seo-tag (~> 2.7.3)
-      rouge (~> 3.23.0)
-      webrick (~> 1.7)
+      rouge (~> 4.2)
+      webrick (~> 1.8)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.1)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.1.1)
     colorator (1.1.0)
-    concurrent-ruby (1.1.10)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.15.5)
+    ffi (1.17.4)
     forwardable-extended (2.6.0)
-    http_parser.rb (0.8.0)
-    i18n (1.12.0)
+    google-protobuf (4.34.1)
+      bigdecimal
+      rake (~> 13.3)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    jekyll (4.2.2)
+    jekyll (4.4.1)
       addressable (~> 2.4)
+      base64 (~> 0.2)
       colorator (~> 1.0)
+      csv (~> 3.0)
       em-websocket (~> 0.5)
       i18n (~> 1.0)
-      jekyll-sass-converter (~> 2.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
-      kramdown (~> 2.3)
+      json (~> 2.6)
+      kramdown (~> 2.3, >= 2.3.1)
       kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (~> 0.4.0)
+      mercenary (~> 0.3, >= 0.3.6)
       pathutil (~> 0.9)
-      rouge (~> 3.0)
+      rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
-      terminal-table (~> 2.0)
-    jekyll-feed (0.15.1)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-feed (0.17.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
+    jekyll-sitemap (1.4.0)
       jekyll (>= 3.7, < 5.0)
-    jekyll-sass-converter (2.2.0)
-      sassc (> 2.0.1, < 3.0)
     jekyll-soopr-seo-tag (2.7.3)
       jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (2.4.0)
-      rexml
+    json (2.19.3)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    liquid (4.0.3)
-    listen (3.7.1)
+    liquid (4.0.4)
+    listen (3.10.0)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
     mercenary (0.4.0)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (5.0.0)
+    public_suffix (7.0.5)
+    rake (13.3.1)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
-    rouge (3.23.0)
+    rexml (3.4.4)
+    rouge (4.7.0)
     safe_yaml (1.0.5)
-    sassc (2.4.0)
-      ffi (~> 1.9)
-    terminal-table (2.0.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    unicode-display_width (1.8.0)
-    webrick (1.7.0)
+    sass-embedded (1.99.0)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
+    webrick (1.9.2)
 
 PLATFORMS
   ruby

Makefile

@@ -0,0 +1,13 @@
+.PHONY: setup serve build clean
+
+setup:
+	bin/bootstrap
+
+serve:
+	bin/start
+
+build:
+	bin/build
+
+clean:
+	bundle exec jekyll clean

README.md

@@ -8,13 +8,17 @@
 </h3>
 
 ## Features
-* Light & dark mode with theme switcher
+* Light & dark mode with theme switcher (respects `prefers-reduced-motion`)
 * Vertical list, horizontal list, card list
 * Landing page with navbar, footer, portfolio
 * Fast (very minimal CSS) - 100/100 on performance, accessibility, best practices and SEO, please see [Lighthouse Report](https://raw.githubusercontent.com/abhinavs/moonwalk/master/_screenshots/lighthouse-report.png) for more details
 * Responsive and mobile friendly
-* SEO optimized (uses [Jekyll Soopr SEO Tag](https://github.com/jekyll/jekyll-soopr-seo-tag))
+* SEO optimized with auto-generated sitemap
 * RSS feed (uses [Jekyll Feed](https://github.com/jekyll/jekyll-feed))
+* [GitHub Markdown Alerts](#github-markdown-alerts) (NOTE, TIP, IMPORTANT, WARNING, CAUTION)
+* Tag archive page with clickable tags
+* Light and dark mode syntax highlighting
+* Accessible - skip-to-content link, ARIA labels, keyboard friendly
 * Easy to extend
 * Fully compatible with [GitHub Pages](https://pages.github.com/) (see [GitHub Pages installation](#github-pages-installation))
 * Auto-generated share images for social media (using [Soopr](https://www.soopr.co))
@@ -118,17 +122,40 @@ html {
 
 <img src="https://raw.githubusercontent.com/abhinavs/moonwalk/master/_screenshots/twitter_card.png" />
 
+### GitHub Markdown Alerts
+
+Moonwalk supports [GitHub-style Markdown Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). Use them in your posts like this:
+
+```markdown
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+All five alert types are styled with color-coded left borders and icons, and work in both light and dark mode.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/abhinavs/moonwalk.
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
 ## Development
 
-To set up your environment to develop this theme, run `bundle install`.
-
-Your theme is setup just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
+1. Run `bin/bootstrap` (or `make setup`) to install dependencies
+2. Run `bin/start` (or `make serve`) to start the dev server with live reload at `http://127.0.0.1:4000`
+3. Run `bin/build` (or `make build`) for a production build
 
-When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled.
+When your theme is released, only the files in `_layouts`, `_includes`, `_sass`, `_data`, and `assets` tracked with Git will be bundled.
 To add a custom directory to your theme-gem, please edit the regexp in `moonwalk.gemspec` accordingly.
 
 ## Acknowledgement