Moonwalk Jekyll Theme

Included Features

• Retries: Automatic retries with exponential backoff.
• Scheduling: Supports both cron-style and one-off scheduled jobs.
• Deduplication: Prevents duplicate jobs using a job key.
• Dead-letter queue: Stores jobs that have exhausted all retry attempts.
• Observability: Includes a web dashboard for inspection and Prometheus metrics.

When to avoid Soniq

• Extreme Throughput: If you require more than ~10k jobs per second (Redis-backed queues are better for this).
• Cross-language requirements: If you need workers written in languages other than Python (e.g., Node, Go, Ruby).
• Complex DAG Orchestration: If you need to manage complex pipelines of dependent jobs (use Airflow or Prefect instead).

The jekyll-markdown-output plugin generates a clean Markdown version of every rendered post. For a post at /foo.html, it creates a sibling at /foo.md.

This file contains:

• A small YAML frontmatter block (title, date, url, summary, tags, category, author).
• The post's source Markdown with Liquid rendered.

It contains no HTML layouts, navigation, or theme scripts, making it ideal for agents to fetch directly.

The jekyll-llms-output plugin generates two discovery files at your site root:

1. /llms.txt: A curated index of important pages following the llmstxt.org spec. This acts as a sitemap for LLMs.
2. /llms-full.txt: A single file containing the concatenated content of all configured collections. This allows an agent to fetch your entire blog in one request.

Use the llms_output configuration key to specify which collections to include in the index and the full file.

Soniq is a Python library for running background jobs using Postgres instead of a separate broker like Redis. It uses SELECT ... FOR UPDATE SKIP LOCKED for concurrency and LISTEN/NOTIFY for low-latency job pickup.

To use Soniq:

1. Initialize the Soniq client with your database_url.
2. Define jobs using the @app.job() decorator.
3. Enqueue jobs using await app.enqueue(...).
4. Run the setup and worker commands via the CLI to finalize the environment.

from soniq import Soniq

app = Soniq(database_url="postgresql://localhost/myapp")

@app.job()
async def send_welcome(to: str):
    print(f"Sending welcome email to {to}")

await app.enqueue(send_welcome, to="dev@example.com")

Moonwalk (v0.2.0+) includes two plugins to make your site readable by LLMs and coding agents: jekyll-markdown-output (creates clean Markdown versions of posts) and jekyll-llms-output (creates llms.txt and llms-full.txt files).

To enable them, add them to your _config.yml under the plugins key and configure the collection settings as shown below.

plugins:
  - jekyll-markdown-output
  - jekyll-llms-output

markdown_output:
  collections: [posts]

llms_output:
  index:
    collections: [posts]
  full:
    collections: [posts]
    respect_markdown_output: true

To generate a Table of Contents for a specific post, add toc: true to that post's YAML front matter.

---
layout: post
title: My Great Post
toc: true
---

Your post content goes here...

After writing your Soniq code, you must perform the following steps to prepare the database and start processing jobs:

1. Initialize Tables: Run soniq setup once to create the necessary Postgres tables for jobs, retries, and dead-letter queues.
2. Start Worker: Run soniq worker to begin processing the enqueued jobs.

This approach eliminates the need for a separate broker (like Redis) or a result backend.

If you want a post to be visible to humans/search engines but want to prevent an agent from accessing its Markdown twin, add markdown_output: false to that post's YAML frontmatter.

--- 
layout: post
markdown_output: false
---
...

To run the Moonwalk theme locally on a Windows machine, you must use Ruby Devkit 3.0.3. Note that Ruby 3.1.x is known to be bugged for this setup and should be avoided.

Follow these steps:

1. Install Ruby: Download and install Ruby Devkit 3.0.3 from rubyinstaller.org.
2. Install Bundler: Open an elevated command prompt (Run as Administrator) and run:

   gem install bundler

3. Clone the Repository:

   git clone https://github.com/abhinavs/moonwalk

4. Bootstrap and Start: Navigate to the cloned directory and run the bootstrap and start scripts:

   cd moonwalk
   bin/bootstrap
   bin/start

5. Access the Site: Once the server starts, the theme will be hosted at http://127.0.0.1:4000.

Instead of using the auto-generated index, you can provide a hand-curated structure by creating a file at _data/llms.yml. The plugin will use this file verbatim to build your /llms.txt.

title: Your Site
description: >
  One paragraph about who you are and what readers
  (human or otherwise) will find here.

sections:
  - heading: Featured Writing
    links:
      - title: My best post
        url: https://example.com/best-post
        description: One line on what it covers

  - heading: About
    links:
      - title: About me
        url: https://example.com/about
        description: Background and contact