russell.ballestrini.net
#######################

This is the source code for `my blog <https://russell.ballestrini.net>`_. My blog is a static web site with just HTML!
This project uses Pelican (a static site generator) to produce HTML from ``.rst`` or ``.md`` files.

Pelican is written in Python and uses Jinja2 template engine by default.

The theme defaults to dark mode with a light mode toggle. Theme preference is saved to localStorage and persists across sessions. The dark mode toggle also passes the theme preference to embedded Remarkbox comments via the mode parameter.

Need a new blog post entry?
===============================

Try running:

.. code-block:: bash

 ./new_entry


development
===============================

**Setup (one command does everything):**

.. code-block:: bash

 make venv

This creates a ``venv/`` directory with Pelican, installs all dependencies, clones the theme, and configures everything automatically.

**Testing workflow (ALWAYS test before committing):**

.. code-block:: bash

 make clean && make html && make serve

This builds the site and serves it at http://localhost:8000

**Available commands:**

.. code-block:: bash

 make venv          # Setup virtual environment
 make html          # Build the site
 make clean         # Remove output directory
 make serve         # Serve site at localhost:8000
 make devserver     # Serve with auto-reload
 make resume        # Generate PDF resume
 make formats       # Generate all agent-friendly formats

agent-friendly formats
===============================

The blog automatically generates multiple formats optimized for AI agents & LLM consumption:

**Automated format generation (run via ``make formats``):**

.. code-block:: bash

 make rst2md        # Convert all RST to Markdown (index.md)
 make plaintext     # Generate plain text versions (index.txt)
 make jsonfeed      # Generate JSON Feed v1.1 (/feeds/all.json)
 make jsonblog      # Generate JSON Blog format (/blog.json)
 make llms          # Generate llms.txt for AI agent onboarding
 make formats       # Run all of the above

**Generated files:**

- ``/blog.json`` - Blog index with links to markdown files (jsonblog.dev format)
- ``/feeds/all.json`` - JSON Feed v1.1 alternative to Atom/RSS
- ``/llms.txt`` - AI agent onboarding documentation with API info
- ``/*/index.md`` - GitHub-flavored Markdown for every post
- ``/*/index.txt`` - Plain text (no markup) for direct LLM ingestion

**Purpose:**

These formats enable AI agents, LLMs, & automated systems to:

- Discover all posts & fetch markdown via ``content_url`` links (blog.json)
- Subscribe to updates via JSON instead of XML (feeds/all.json)
- Discover blog structure & available formats (llms.txt)
- Read posts without HTML parsing (index.txt, index.md)

**How blog.json works:**

The ``blog.json`` file uses the jsonblog.dev format & links to hosted markdown files instead of embedding content. Each post includes a ``content_url`` field pointing to ``https://russell.ballestrini.net/{slug}/index.md``. This keeps the JSON file lightweight while providing full access to all post content through standard HTTP requests.

All formats are automatically generated during CI/CD builds & kept in sync with the HTML content.

**Requirements:**

- ``pandoc`` - Needed for RST to Markdown conversion (``make rst2md``)

blah

production release process
===============================

we use Gitlab runners to build (look at .gitlab-ci.yml file) this site and Salt Stack to release the zipped artifacts.

Any web server may be used to host an HTML site. I choose nginx in production because it is known to be very fast at serving static files.

we use environment variables in my ``pelicanconf.py`` to store secrets.

For example: `Remarkbox comments <https://www.remarkbox.com>`_.

---

you should check out https://uncloseai.com for machine learning on your static web pages!

now with translation services!

nice,
dude