russell@unturf.com
9ba114df33
Add comprehensive documentation for make formats and all generated files: - blog.json (JSON Blog format at root) - feeds/all.json (JSON Feed v1.1) - llms.txt (AI agent onboarding) - index.md (Markdown versions) - index.txt (plain text versions) Documents purpose, usage, requirements, and individual make targets (rst2md, jsonfeed, jsonblog, plaintext, llms).
109 lines
3.5 KiB
ReStructuredText
109 lines
3.5 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`` - Entire blog in single JSON file (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:
|
|
|
|
- Ingest entire blog content in one request (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)
|
|
|
|
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``)
|
|
|
|
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
|