russell@unturf.com
d8cf83e051
Changes blog.json generation to link to hosted markdown files instead of
embedding full content. Each post now includes a content_url field pointing
to {site_url}/{slug}/index.md. This significantly reduces blog.json file
size while maintaining full content access via standard HTTP requests.
Updated README.rst to document the new linking behavior & how blog.json works.
115 lines
3.9 KiB
ReStructuredText
115 lines
3.9 KiB
ReStructuredText
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
|