DEV Community: Sanjay Singh

Add Runnable Code Examples to Your Technical Articles

Sanjay Singh — Mon, 09 Nov 2026 08:04:03 +0000

Add Runnable Code Examples to Your Technical Articles

Code samples make technical articles concrete, but readers often have to copy them into a separate project before they can experiment. That extra step can hide the relationship between the explanation, the files, and the result.

ZyVOP’s Runnable Examples feature lets authors place a small multi-file project inside an article. Readers can inspect the files and expand the saved test output alongside the explanation. It’s a practical way to make a focused example easier to explore without asking readers to set up a full repository first.

Choose an example that teaches one idea

An embedded project works best when it demonstrates a specific concept: a parser, a small utility, a validation rule, or a bug fix. Keep the example small enough for readers to understand in context.

Before adding one, decide what you want the reader to learn. A short function and a few tests may explain an edge case more clearly than a large application with framework setup and configuration unrelated to the point.

Add a project in the editor

While writing in ZyVOP’s editor, type /Runnable Example on a blank line to insert the project block. You can give it a display name, add the project files, and choose which file starts the example and which file contains its tests.

The runner supports up to 12 files, relative imports between .ts and .js files, and ZyVOP’s @zyvop/test helpers. This is enough for many self-contained demonstrations while keeping the project manageable inside an article.

Run the checks before publishing

Run the project from the editor and review the result before publishing. ZyVOP executes the example in an isolated browser worker, then saves the passing result with the project and test hash, compiler version, and run date. Readers can expand the saved output when they want to see what happened.

If you edit a project file, the saved result is cleared. Run the checks again after making changes so the result corresponds to the version readers will see.

Explain what readers should notice

The runnable block should support the article, not replace its explanation. Introduce the example, point out the important behavior, and connect the test result to the idea you’re teaching.

For instance, if an article explains input validation, tell readers which boundary case the project covers and why it matters. After the example, describe what the test confirms and what it does not cover. Readers should be able to understand the lesson without running the code, then use the project to explore further.

Know the runner’s boundaries

Runnable Examples are designed for focused browser demonstrations. The runner does not install packages or allow network access. Keep the project self-contained, use supported relative imports, and avoid relying on external services or dependencies that the browser worker cannot reach.

The saved result is an author browser run. Readers can inspect the files and expand the saved output, but the published article does not let each reader run the code. The result shows that the project’s saved checks passed in ZyVOP’s browser runner at the recorded time. It is not an independent CI run or a guarantee that the code works in every production environment. For production claims, continue to use your project’s normal CI and deployment checks.

Bring the explanation and code closer together

An interactive example gives readers something they can inspect in the same place they’re learning the concept. Keep the project narrow, run it after edits, and explain both its result and its limits.

Use ZyVOP’s /Runnable Example block when a small, testable project will make an explanation clearer. The article remains the guide; the embedded files and saved output give readers another way to follow along.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Turn a Long Technical Guide into a Reader-Friendly Series

Sanjay Singh — Sun, 08 Nov 2026 06:13:38 +0000

A detailed technical guide can be valuable and still be hard to read. Readers may want to understand one part of the system, try a specific technique, or return later to continue. A single long article makes every reader follow the same path through every detail.

Splitting a guide into a series can make that journey easier. The key is to divide the material around ideas readers can understand and use on their own, then make the connections between chapters clear.

ZyVOP’s Series feature gives related articles an ordered home, with chapter navigation to help readers move through the guide. Here’s how to plan that structure and set it up.

Decide whether the guide needs multiple parts

Length alone isn’t a good reason to split an article. A long tutorial may work well as one piece if readers need every step in sequence. A series is more useful when the material has natural stages, distinct goals, or sections that different readers may want to visit independently.

For example, a guide to building a production-ready service might break down like this:

Define the service boundaries and API.
Add persistence and data migrations.
Handle retries, timeouts, and failure recovery.
Add observability and operational checks.
Deploy the service and test its behavior in production.

Each chapter has a clear focus, while the full sequence takes readers from design to deployment.

Give every chapter a useful endpoint

Before writing, outline the series from the reader’s point of view. For each part, write down:

What will the reader understand or be able to do afterward?
What knowledge does the chapter assume?
What artifact will it produce, such as a design, code change, or test?
What should the reader know before moving to the next part?

If a chapter has no clear outcome, it may be supporting material for another part rather than a separate article. If it has several unrelated outcomes, consider dividing it further.

Each article should also orient readers who arrive from search or a shared link. Briefly explain where the chapter fits, summarize any essential context, and link to the series overview. Don’t make readers guess whether they need to read earlier parts first.

Create the series in ZyVOP

In the web dashboard, go to Dashboard → Series and choose Create Series. Add a title, a description that explains what the full guide teaches, and an optional cover image. ZyVOP creates a series page with an ordered chapter list and an overview for readers.

Then add your articles to the series. You can assign a post through its series settings, or include the series identifier in Markdown front matter:

---
title: "Part 1: Define the Service Boundary"
series: "production-service-guide"
status: "PUBLISHED"
---

Use the series slug or ID as the series value. If you manage articles as Markdown files, keeping this field beside each chapter’s content makes the relationship visible in your repository.

Put chapters in a helpful order

The chapter order should reflect what readers need to know next, not necessarily the order in which you wrote the articles. In ZyVOP’s Series Management view, reorder chapters to create the reading sequence. ZyVOP updates the sequence and the previous and next links shown on series articles.

Review the order from a new reader’s perspective. Check that each chapter has the context it needs and that the series description accurately sets expectations. If a later chapter is optional, say so in its introduction instead of making the sequence feel broken.

Help readers keep their place

When readers open an article in a series, ZyVOP can show its position, such as “Part 2 of 5,” provide previous and next links, and offer a drawer listing the published chapters. The series page gives readers a central place to see the guide’s scope and choose where to begin.

These connections are especially helpful when readers discover a middle chapter first. They can see the broader path and decide whether to go back, continue forward, or jump to another relevant part.

Publish the whole guide at a sustainable pace

You don’t have to finish every chapter before publishing the first one. You can release a series as chapters are ready, or prepare the full sequence in advance. In either case, give readers a clear indication of what is available and what the overall guide will cover.

Before releasing each part, check its links to the series and neighboring chapters. Keep titles consistent enough to signal that the articles belong together, while making each title meaningful on its own.

Make depth easier to navigate

A well-planned series preserves the depth of a technical guide while giving readers clearer stopping points and ways to navigate. ZyVOP’s Series feature connects the articles through an ordered series page, chapter position, and previous and next navigation.

Start with the outcomes you want readers to reach, divide the material into chapters that each deliver a useful result, and arrange those chapters into a path people can follow at their own pace.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How to Make Technical Articles Easier for AI Tools to Read

Sanjay Singh — Fri, 06 Nov 2026 06:46:40 +0000

Technical articles are written for people, but they can also be processed by search engines, feed readers, and AI tools. Clear structure helps all of them identify what an article covers, how its sections relate, and which sources support its claims.

There’s no reliable way to guarantee that an AI system will find, use, or cite a particular article. You can still make your work easier to understand by publishing accurate content with useful structure and machine-readable context.

ZyVOP provides clean article resources for compatible tools that choose to use them. Here are practical ways to make use of that support while keeping the article useful to human readers first.

Start with a clear question and answer

Give the article a specific title that tells readers what problem it addresses. Then use the opening paragraphs to explain the situation, the scope of the guide, and the main takeaway.

For example, “PostgreSQL Indexes” is broad. “How to Choose an Index for a PostgreSQL Query” tells readers more about the question the article will answer.

Avoid making readers infer essential context from a long introduction. State the environment, versions, and assumptions when they affect the advice. If a recommendation only applies to a particular setup, say so near the recommendation.

Use headings that describe the section

Organize the article with a logical heading hierarchy. Use a main title, then sections for the major steps or ideas, and subsections when they clarify a specific part.

Prefer descriptive headings such as “Measure the query before adding an index” over vague labels such as “Step 2”. A heading should help a reader scanning the page understand what they’ll learn in that section.

ZyVOP’s machine-readable article representation includes the article’s heading structure. Clear headings therefore help readers navigate the article and give compatible tools more context about its contents.

Make summaries and metadata accurate

An excerpt or subtitle should summarize what the article actually explains. Avoid stuffing it with keywords or promising results the article doesn’t demonstrate.

In a Markdown article, you can keep the summary in front matter:

---
title: "How to Choose an Index for a PostgreSQL Query"
subtitle: "A practical way to compare query plans before changing a production schema."
excerpt: "Use EXPLAIN ANALYZE and representative data to decide whether a PostgreSQL index is likely to help."
canonical_url: "https://engineering.example.com/postgres-indexes"
tags: [postgresql, databases, performance]
---

An explicit canonical URL identifies your preferred article address when the same content appears in more than one place. Canonical declarations are signals, not guarantees that every crawler will select that URL.

Support important claims with sources and examples

When an article makes a technical or time-sensitive claim, link to authoritative documentation, a relevant paper, or the source code that supports it. Show enough of your method for readers to judge the conclusion: versions, inputs, commands, measurements, and limitations can all matter.

For example, a performance claim is more useful when it includes the database version, table size, query plan, and test conditions. A brief statement of limitations helps prevent an example from being mistaken for a universal rule.

ZyVOP’s machine-readable resources

ZyVOP offers three resources for compatible agents and tools:

/llms.txt provides a plain-text overview, canonical links, timestamps, and links to selected articles.
/llms-full.txt provides an expanded index of up to 500 canonical articles, with author, date, topic, and excerpt information.
/api/geo/posts/{slug} provides a clean JSON representation of an individual published canonical article, including its title, author, timestamps, headings, references, and plain text content.

For example, you can request an article’s JSON representation with:

curl -H "Accept: application/json" \
  https://zyvop.com/api/geo/posts/postgres-zero-downtime

The exact article slug and host depend on the published article and publication domain. These resources give compatible consumers a cleaner way to access article information than extracting it from a rendered page with navigation and other interface elements.

Treat machine readability as part of good publishing

Machine-readable endpoints can make structured content available to tools that choose to use them. They don’t control crawler behavior, guarantee indexing or ranking, or ensure that an AI answer will include a link or citation.

The most reliable writing practices remain straightforward: answer a clear question, use descriptive headings, keep summaries honest, identify your preferred source, and support important claims. ZyVOP’s clean article resources add structured access to that content while the article remains readable and useful to people.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How We Built Fast Search for ZyVOP Without Elasticsearch or Algolia

Sanjay Singh — Thu, 05 Nov 2026 04:36:57 +0000

Search is one of those features that looks simple until people start using it. A developer might remember a tool by its name, search for a topic mentioned deep in an article, misspell a framework, or look for a writer instead of a post.

We wanted ZyVOP search to handle those everyday queries across posts, series, and authors. We also wanted to keep publishing and search on the same source of truth. That led us to a practical question: could PostgreSQL do the job without adding Elasticsearch or Algolia?

For our current workload, yes. The search experience is responsive, and the system is built from capabilities we already operate: PostgreSQL for search and Redis for short-lived result caching. There is no separate search index to synchronize with the database.

The problem with searching article text on every request

Our posts can contain long technical articles. The earlier query path rebuilt a text vector from post content while searching. That meant repeatedly processing large text values, including content PostgreSQL may store out of line in TOAST. The current search service calls out that rebuilding a vector from a full TOASTed article can take seconds.

The query should not have to parse every article from scratch each time someone types a term. We moved that work to writes: PostgreSQL now maintains a stored search vector for each post, and a GIN index makes that vector searchable.

ALTER TABLE "posts"
  ADD COLUMN "search_vector" tsvector
  GENERATED ALWAYS AS (
    setweight(to_tsvector('english', COALESCE("title", '')), 'A') ||
    setweight(to_tsvector('english', COALESCE("excerpt", '')), 'B') ||
    setweight(to_tsvector('english', COALESCE("content", '')), 'C')
  ) STORED;

CREATE INDEX idx_posts_search_vector_published
  ON "posts" USING GIN ("search_vector")
  WHERE "status" = 'PUBLISHED';

The title, excerpt, and body are all searchable, and the vector stores a higher weight for the title than the excerpt or body. PostgreSQL updates the generated value when a post changes instead of rebuilding it for each search. The partial index focuses on published posts, which are the records public search can return. The weights are present in the vector; the current result score is calculated separately, as described below.

One query, several ways to find a post

Full-text search is good at finding words in an article body. It is not the whole search experience. A search for a slightly misspelled title, a tag, an author, or a category needs other match paths.

We gather candidate post IDs from a few sources and combine them:

Full-text matches use the stored vector to search titles, excerpts, and article content.
Title matches use pg_trgm similarity for near matches and case-insensitive partial matching for prefixes and substrings.
Metadata matches look through tags, categories, and author names or usernames. Tags, category names, and author names also use trigram similarity; usernames support case-insensitive partial matches.
Technical synonyms expand common variants such as nextjs / next.js, nodejs / node.js, and postgres / postgresql.

The query helper also sanitizes search tokens, turns them into prefix terms, and expands known synonyms before creating PostgreSQL text queries. That lets the application support common technical variants without passing raw user input into to_tsquery.

The key performance choice is to separate finding candidates from scoring them. PostgreSQL can use its indexes to reduce the result set first. We then calculate ranking signals only for those matching posts, rather than running expensive ranking work across the entire corpus.

Search should return useful results, not just matching text

After gathering candidates, ZyVOP assigns a score using a few understandable signals:

A title containing the query string gets a large boost.
Trigram similarity in the title raises likely typo and near-title matches.
A matching tag, category, or author adds a smaller relevance bonus.
Views contribute a modest popularity signal.

This means a post with the query in its title can rise above one that only matches in its body, while a tag or author search can still surface the right work. Once the top IDs are selected, the service loads their author, category, and tag relations and restores the score order for the response.

The current ranking is intentionally simple. Full-text search determines whether body content is a candidate, but the score does not add a separate body-relevance rank. A post that matches only in its body can therefore be ordered mainly by title similarity, metadata bonuses, and views. That is a clear area to improve if search behavior shows that content-only matches need finer ordering.

Candidate recall still needs a golden test set

A ranking score cannot recover a post that candidate selection has already dropped. The current automated checks verify that public post search uses the stored vector and excludes posts that are not eligible for discovery. They do not yet measure recall against a stable set of queries with known expected posts.

The next quality check should use a fixed, representative fixture and label the eligible posts expected for each query. It should include exact titles, body-only terms, tags and authors, uncommon technical terms, known synonyms, and realistic misspellings. We should inspect the candidate IDs before scoring and report candidate recall separately from ranking quality. A ranking metric such as MRR or NDCG is useful only after we know relevant posts survived candidate selection.

Until that evaluation exists, we can describe the matching paths implemented in code, but we should not claim measured recall or broad typo coverage.

Keeping the interface quick

The search modal waits until the user has paused typing for 300 milliseconds, then requests posts, series, and authors together. This avoids sending a request for every keystroke while keeping results feeling immediate.

For post search, the cache key includes the lowercased query and the requested page. ZyVOP’s cache service checks an in-process LRU cache and Redis, and keeps search results for up to 60 seconds. Repeated searches can therefore avoid rerunning the database query during that window. Search still works from PostgreSQL on a cache miss; Redis holds results, not a second search index.

The service also limits page sizes and only returns published posts that pass the public discovery rules, including distribution, no-index, length, and review-status checks. Drafts and posts that are not eligible for public discovery do not leak into search results.

There is also a fallback path. If the hybrid SQL query fails, the service logs the error and runs a simpler query-builder search across title, excerpt, author name, and tag name, ordered by publication date. This keeps a basic search path available, though it does not preserve the hybrid query’s body matching, fuzzy matching, category matching, or relevance score.

Why PostgreSQL was enough for us

Choosing PostgreSQL kept the search path close to the data it searches. A post edit updates its stored vector as part of the same database write. Search does not depend on an asynchronous export job catching up or on an external search service staying in sync. PostgreSQL still maintains its own GIN indexes, and those indexes add storage and write costs.

That does not mean a dedicated search product is never the right choice. Elasticsearch or Algolia may be a better fit when a product needs advanced language analyzers, complex faceting, extensive typo controls, semantic retrieval, or search scale and traffic that PostgreSQL cannot meet comfortably. Indexes also have a cost: they take disk space and add work when records change.

For ZyVOP’s current needs, PostgreSQL gives us the features we use—full-text search, typo-tolerant matching on short fields, filters, and relevance signals—without adding another system to deploy and maintain.

What “fast” means here

This case study describes the design behind ZyVOP’s responsive search, not a benchmark claim. We are not publishing a millisecond number because a useful figure needs a reproducible test against a defined corpus, database configuration, cache state, and traffic pattern. A number without those details would be easy to misread.

The practical lesson is simpler: before adding a dedicated search cluster, make sure the database is not doing avoidable work. Store derived search data, index the fields that need fuzzy matching, narrow the candidate set before ranking, and cache repeated queries. For our workload, that has been enough to make search feel fast while keeping the architecture straightforward.

If our data or search requirements change, we can benchmark the current path and make that decision with evidence. Until then, PostgreSQL remains both our application database and our search engine.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How to Monitor Client Domains and SSL Certificates for Free Before They Expire

Sanjay Singh — Wed, 04 Nov 2026 04:50:06 +0000

Picture this: you built a website for a client two years ago, and it has run quietly ever since. On a Friday evening they message you: "The site is down, and Chrome says it's not secure."

The SSL certificate expired yesterday. Or it is worse: the domain lapsed, and a parked page now sits where your client's business used to be. You may not even be the person who renews either one, but the client sees a broken site and thinks of you.

You cannot stop a declined card or a renewal email that lands in spam. You can make sure you hear about it 30 days early instead of 30 hours late.

This post builds a free monitor that checks every client site for domain expiry, SSL expiry and downtime, alerts you on Telegram, and tells you when the monitor itself has stopped working.

What we are building

A Python script reads a list of clients, runs the three checks and sends Telegram alerts. GitHub Actions runs the expiry checks daily, and an optional VPS cron job runs quick uptime checks. A heartbeat service emails you if the script ever stops reporting in. Everything fits inside free tiers.

You need:

A private GitHub repository, because the client list is confidential.
A Telegram account.
A free Healthchecks.io account. The free plan allows 20 checks, and this setup uses two. A self-hosted Uptime Kuma push monitor also works.
Python 3 on your machine for testing.
Optional: a VPS for frequent uptime checks. Without one, the daily expiry checks still deliver most of the value.

Step 1: List your clients

Create clients.yml in the repository root:

clients:
  - name: Acme Traders
    domain: acmetraders.com            # the registered domain, not a subdomain
    sites:
      - url: https://acmetraders.com
        expect: "Acme Traders"         # text that must appear on the page
      - url: https://www.acmetraders.com
      - url: https://app.acmetraders.com/login
        expect: "Sign in"

  - name: Example Studio
    domain: examplestudio.xyz
    domain_expires: 2027-03-14         # optional hand-entered date, see Step 3
    sites:
      - url: https://examplestudio.xyz

List every hostname that is actually served. The apex, www and app. can each have their own certificate and expiry date.
Write the registered domain explicitly. Guessing it from a hostname breaks on names like example.co.uk, so one explicit line per client is simpler and always correct.
Use expect to catch fake successes. It flags a server that returns status 200 but serves an error page, a parked page or a blank screen.

Step 2: Create the Telegram bot

In Telegram, open a chat with @botfather, send /newbot and copy the token it gives you.
Open a chat with your new bot and send it any message, such as "hello".
Open this URL in your browser, replacing <TOKEN> with your token:
```
https://api.telegram.org/bot<TOKEN>/getUpdates
```
Find "chat":{"id":123456789,...} in the response. That number is your chat ID.

Two gotchas: a bot cannot message you until you message it first (an empty getUpdates means you skipped step 2), and group chat IDs are negative, so copy the minus sign.

Treat the token like a password. If it leaks, send /revoke to BotFather. In your repository, open Settings, Secrets and variables, Actions and add two secrets: TELEGRAM_TOKEN and TELEGRAM_CHAT_ID.

Step 3: Write the three checks

Create monitor.py. This first part holds the imports and the checks.

from __future__ import annotations

import json
import os
import re
import socket
import ssl
import sys
import time
import urllib.error
import urllib.request
from datetime import date, datetime, timezone
from urllib.parse import urlencode, urlparse

import yaml

TIMEOUT = 15
HEADERS = {"User-Agent": "client-watchdog/1.0"}

# ---------- Check 1: SSL certificate expiry ----------

def ssl_days_left(host: str) -> int:
    """Days until the certificate served for `host` expires."""
    ctx = ssl.create_default_context()
    with socket.create_connection((host, 443), timeout=TIMEOUT) as sock:
        # server_hostname sends SNI, so we get the certificate for this exact name
        with ctx.wrap_socket(sock, server_hostname=host) as tls:
            cert = tls.getpeercert()
    expires = ssl.cert_time_to_seconds(cert["notAfter"])
    return int((expires - time.time()) // 86400)

# ---------- Check 2: domain expiry via RDAP ----------

def get_json(url: str):
    headers = {**HEADERS, "Accept": "application/rdap+json, application/json"}
    req = urllib.request.Request(url, headers=headers)
    with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
        return json.load(resp)

_bootstrap = None

def rdap_base_url(tld: str) -> str | None:
    """Ask IANA which RDAP server is responsible for this TLD."""
    global _bootstrap
    if _bootstrap is None:
        _bootstrap = get_json("https://data.iana.org/rdap/dns.json")
    for tlds, urls in _bootstrap["services"]:
        if tld in tlds:
            return next((u for u in urls if u.startswith("https://")), None)
    return None

def domain_days_left(client: dict) -> int | None:
    """Days until the domain expires, or None if we cannot tell."""
    manual = client.get("domain_expires")  # hand-entered fallback or override
    if manual:
        return (date.fromisoformat(str(manual)) - datetime.now(timezone.utc).date()).days

    domain = client["domain"].lower()
    base = rdap_base_url(domain.rsplit(".", 1)[-1])
    if base is None:
        return None  # this TLD has no RDAP server
    data = get_json(f"{base}domain/{domain}")
    for event in data.get("events", []):
        if event.get("eventAction") == "expiration":
            stamp = re.sub(r"\.\d+", "", event["eventDate"]).replace("Z", "+00:00")
            expires = datetime.fromisoformat(stamp)
            if expires.tzinfo is None:
                expires = expires.replace(tzinfo=timezone.utc)
            return (expires - datetime.now(timezone.utc)).days
    return None

# ---------- Check 3: is the site up and showing the right content? ----------

def check_http(url: str, expect: str | None = None) -> str | None:
    """Return a short problem description, or None if the site looks healthy."""
    problem = "unknown error"
    for attempt in range(2):  # one retry stops a single network blip from paging you
        try:
            req = urllib.request.Request(url, headers=HEADERS)
            with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
                body = resp.read(500_000).decode("utf-8", errors="replace")
            if expect is None or expect in body:
                return None
            problem = f'page loaded but "{expect}" was not found'
        except urllib.error.HTTPError as e:
            problem = f"HTTP {e.code}"
        except Exception as e:  # DNS failure, timeout, TLS error, and so on
            problem = f"{type(e).__name__}: {e}"
        if attempt == 0:
            time.sleep(5)
    return problem

Notes on the choices:

SSL. Python verifies the certificate during the handshake, so an already-expired certificate raises an error instead of returning a date. Step 4 handles that case.
Domain expiry. RDAP is the structured replacement for WHOIS. The script asks IANA's public bootstrap file which server handles the TLD, then reads the expiration event. Some country-code TLDs have no RDAP server, so for those, set domain_expires by hand (as an unquoted date).
Uptime. One retry after five seconds means a single dropped packet does not become a 3 a.m. alert.

Step 4: Decide when to alert, and send the message

The alert rule is deliberately stateless: alert at exactly 30, 14 and 7 days, then every day once three or fewer days remain. There is no "already alerted" file to corrupt, and the daily reminders at the end give you more than one chance if a run is ever skipped.

Add the rest of the script below the checks:

# ---------- Alert rules ----------

def should_alert(days_left: int) -> bool:
    """Alert at 30, 14 and 7 days, then every day once 3 or fewer remain."""
    return days_left in (30, 14, 7) or days_left <= 3

def when(days: int) -> str:
    return f"expired {-days} days ago" if days < 0 else f"expires in {days} days"

def expiry_messages(client: dict) -> list[str]:
    name = client["name"]
    msgs: list[str] = []

    # Domain
    try:
        days = domain_days_left(client)
        if days is None:
            msgs.append(
                f"[{name}] No expiry date found for {client['domain']}. "
                "Add domain_expires to clients.yml."
            )
        elif should_alert(days):
            msgs.append(f"[{name}] Domain {client['domain']} {when(days)}")
    except Exception as e:
        msgs.append(f"[{name}] Domain lookup failed for {client['domain']}: {e}")

    # SSL, once per HTTPS hostname
    hosts = sorted(
        {urlparse(s["url"]).hostname for s in client["sites"] if s["url"].startswith("https://")}
    )
    for host in hosts:
        try:
            days = ssl_days_left(host)
        except ssl.SSLCertVerificationError as e:  # expired, wrong host, bad chain
            reason = getattr(e, "verify_message", None) or str(e)
            msgs.append(f"[{name}] SSL for {host} is invalid: {reason}")
            continue
        except OSError as e:
            msgs.append(f"[{name}] SSL check for {host} could not connect: {e}")
            continue
        if should_alert(days):
            msgs.append(f"[{name}] SSL certificate for {host} {when(days)}")
    return msgs

def uptime_messages(client: dict, state: dict) -> list[str]:
    """Alert when a site goes down and when it recovers, not on every run."""
    msgs: list[str] = []
    for site in client["sites"]:
        url = site["url"]
        problem = check_http(url, site.get("expect"))
        now = "down" if problem else "up"
        before = state.get(url, "up")
        if now == "down" and before == "up":
            msgs.append(f"[{client['name']}] DOWN: {url} ({problem})")
        elif now == "up" and before == "down":
            msgs.append(f"[{client['name']}] RECOVERED: {url}")
        state[url] = now
    return msgs

# ---------- Telegram, state and heartbeat ----------

STATE_FILE = os.environ.get("STATE_FILE", "state.json")

def load_state() -> dict:
    try:
        with open(STATE_FILE) as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return {}

def save_state(state: dict) -> None:
    with open(STATE_FILE, "w") as f:
        json.dump(state, f, indent=2)

def send_telegram(text: str) -> None:
    token = os.environ["TELEGRAM_TOKEN"]
    chat_id = os.environ["TELEGRAM_CHAT_ID"]
    data = urlencode({"chat_id": chat_id, "text": text[:4000]}).encode()
    url = f"https://api.telegram.org/bot{token}/sendMessage"
    urllib.request.urlopen(url, data=data, timeout=TIMEOUT).read()

def ping_heartbeat() -> None:
    url = os.environ.get("HEARTBEAT_URL")
    if url:  # skipped while you test locally
        urllib.request.urlopen(
            urllib.request.Request(url, headers=HEADERS), timeout=TIMEOUT
        ).read()

# ---------- Main ----------

def main() -> None:
    mode = sys.argv[1] if len(sys.argv) > 1 else "expiry"
    if mode not in ("expiry", "uptime"):
        sys.exit("usage: python monitor.py [expiry|uptime]")

    with open("clients.yml") as f:
        clients = yaml.safe_load(f)["clients"]

    state = load_state() if mode == "uptime" else {}
    messages: list[str] = []
    for client in clients:
        if mode == "expiry":
            messages += expiry_messages(client)
        else:
            messages += uptime_messages(client, state)

    if messages:
        send_telegram("Client watchdog\n\n" + "\n".join(f"- {m}" for m in messages))
    if mode == "uptime":
        save_state(state)  # saved only after the alert went out
    print("\n".join(messages) or "All checks passed")

    ping_heartbeat()  # last line: reached only if everything above worked

if __name__ == "__main__":
    main()

Two ordering details matter:

The uptime state is saved after the Telegram message goes out. If sending fails, the next run alerts again instead of silently swallowing the outage.
ping_heartbeat() is the very last line, so if anything above it crashes, the ping never happens. Step 6 explains why that is the point.

Test it on your machine before scheduling anything:

pip install pyyaml
export TELEGRAM_TOKEN="your-token"
export TELEGRAM_CHAT_ID="your-chat-id"
python3 monitor.py expiry

If everything is healthy, it prints All checks passed and sends nothing. Step 7 forces an alert.

Step 5: Schedule it

Daily expiry checks with GitHub Actions

Create .github/workflows/watchdog.yml:

name: client-watchdog

on:
  schedule:
    - cron: "30 3 * * *"    # once a day, in UTC
  workflow_dispatch:         # adds a "Run workflow" button for manual runs

permissions:
  contents: read

jobs:
  expiry:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"
      - run: pip install pyyaml
      - run: python monitor.py expiry
        env:
          TELEGRAM_TOKEN: ${{ secrets.TELEGRAM_TOKEN }}
          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
          HEARTBEAT_URL: ${{ secrets.HEARTBEAT_URL }}

Action versions change over time, so check each action's GitHub page for the current major version before you copy this.

Three things to know about scheduled workflows:

They can run late. GitHub's scheduler is best-effort, so never depend on an exact minute.
Public repositories get paused. GitHub disables scheduled workflows in a public repository after 60 days with no repository activity. That is one more reason to keep this repository private.
Private repositories use your plan's free minutes. The Free plan has included 2,000 a month, and each run is rounded up to a full minute, so a daily job costs about 30. Check your plan's current allowance.

Do not run five-minute uptime checks on Actions. About 288 runs a day would burn through a private repository's free minutes quickly. Use a VPS for that part.

Frequent uptime checks on a VPS (optional)

On your VPS:

sudo apt install python3-yaml
git clone <your-private-repo> /opt/client-watchdog
cd /opt/client-watchdog

Create /opt/client-watchdog/.env with your secrets and lock it down:

cat > .env <<'EOF'
TELEGRAM_TOKEN=your-token
TELEGRAM_CHAT_ID=your-chat-id
HEARTBEAT_URL=https://hc-ping.com/your-uptime-check-id
EOF
chmod 600 .env

Then add this line with crontab -e:

*/5 * * * * cd /opt/client-watchdog && set -a && . ./.env && set +a && /usr/bin/python3 monitor.py uptime >> watchdog.log 2>&1

The state.json file lives in that folder, so an outage produces one DOWN message and one RECOVERED message, not one every five minutes.

If a client's firewall blocks your checks, give them your VPS's public IP to allowlist. If you followed my earlier guide on getting a stable public IP with a VPS and Tailscale, you already have exactly the kind of stable address clients are happy to allowlist.

Step 6: The mistake worth understanding

Here is the failure that makes monitoring dangerous: a dead monitor looks exactly like a healthy one.

If the workflow is disabled, the Telegram token is revoked, the VPS is rebuilt or the cron entry disappears, the alerts just stop. Silence feels like good news, so you assume every client is fine.

The fix is a dead man's switch: the script reports in every time it finishes, and a separate service raises the alarm when the reports stop.

Create a free Healthchecks.io account.
Create a check for the daily expiry job: period 1 day, grace time at least a couple of hours, because scheduled runs can be late.
Create a second check for the VPS uptime job: period 5 minutes, grace about 10 minutes.
Save the first ping URL as the HEARTBEAT_URL secret in GitHub and put the second in the VPS .env file.
Set the notification channel to email, not Telegram.

That last choice is deliberate. If your Telegram setup is what broke, an alert about it sent over Telegram would vanish too, so the watchdog's watchdog needs a different route.

Step 7: Verify that it actually works

Never trust an alert system you have not seen fire. Test each path on purpose.

1. Force an expiry alert. Temporarily change should_alert to return True, run python3 monitor.py expiry, and confirm Telegram lists every domain and certificate with its days remaining. Then revert it.

2. Check a broken certificate. Add this test client:

- name: Test
    domain: example.com
    domain_expires: 2099-01-01         # skips the RDAP lookup for this test
    sites:
      - url: https://expired.badssl.com/

You should get a message saying the certificate is invalid because it has expired. badssl.com hosts public test sites for exactly this. Remove the test client afterwards.

3. Check DOWN and RECOVERED. Add a site with an expect value that is not on the page, run python3 monitor.py uptime and confirm a DOWN message. Fix the text and run it again to get RECOVERED. A third run should send nothing.

4. Check the heartbeat. Create a throwaway Healthchecks check with a very short period, ping it once with curl, and wait. You should get an email saying the pings stopped. If not, fix your notification settings now, not during an outage.

Finally, open the Actions tab, click Run workflow, and make sure the job succeeds from GitHub's environment, not just from your laptop.

Limitations and security

Cloudflare can hide an expiring origin certificate. Behind Cloudflare's proxy, your script sees Cloudflare's edge certificate, not the one on your origin server. In Full (strict) mode, an expired origin certificate shows up as an HTTP 526 error, which the uptime check catches, but only if the uptime check is running.
You can warn about a domain but not renew it. It usually lives in the client's registrar account, so treat the alert as a prompt to forward, for example: "Your domain expires in 14 days; please check that your renewal payment method is current."
RDAP servers are not perfect. Registries can rate-limit or have outages. A failed lookup sends an alert saying so, and domain_expires is your fallback.
Tell clients you are checking their site. Bot-protection tools can block frequent requests, and a heads-up makes allowlisting easy.
Keep secrets out of the repository. Tokens belong in Actions secrets and the VPS .env file, never in clients.yml or the script.
This is a safety net, not a monitoring suite. It does not detect defaced pages, changed DNS records or slow responses, and it checks from one location only.

Troubleshooting

Symptom	What to check
No Telegram message ever arrives	Message the bot first, confirm the chat ID (negative for groups), and call the sendMessage URL by hand
Works locally but fails in GitHub Actions	Secret names match exactly, pip install pyyaml is present, and the job log shows the real error
"No expiry date found" for a domain	The TLD has no RDAP server, so add domain_expires (unquoted date) for that client
SSL check passes but visitors see a certificate error	The site is behind Cloudflare's proxy, so check the origin certificate and look for HTTP 526
Uptime alerts fire on every run	state.json is not persisting, so check the working directory, permissions and STATE_FILE
Heartbeat alert arrives but the script ran	The grace period is too short for a delayed scheduled run, or the ping URL is wrong

Conclusion

You no longer have to wait for a client to tell you their site is broken. A small script, a private repository and a few free accounts tell you about expiring domains and certificates weeks ahead, and about outages within minutes.

The part that matters most is the heartbeat, because it is what makes "no news" actually mean "good news".

One final rule: an alert you have never seen fire is an alert you cannot trust. Break something on purpose, watch the message arrive, and only then relax.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How to Measure Your Developer Blog Beyond Page Views

Sanjay Singh — Tue, 03 Nov 2026 07:50:02 +0000

Publishing a technical article and seeing the view count rise feels good. But views alone cannot tell you whether readers found the answer they needed, where they came from, or what to write next.

A useful blog measurement routine does not need dozens of dashboards. Pick a few signals that connect to your goals, review them consistently, and use what you learn to improve the next article.

Start with the question behind the metric

Before opening analytics, decide what you want the blog to do. You might want to:

Help engineers solve a specific problem.
Build a portfolio that shows how you reason about systems.
Reach more developers who work with a particular technology.
Bring readers to a project, newsletter, or product.
Build a durable library of technical references.

These goals call for different evidence. A tutorial may be useful even if it gets fewer views than a broad announcement. A portfolio post may help one hiring manager understand your work, even if it never trends in a community feed.

Use a small set of signals

Reach: Are people finding the article?

Track views over a defined period and note how readers arrived: search, direct visits, a community platform, social links, or an email newsletter. Referral information can show which distribution channels bring people to your site.

Treat referral data as incomplete. Privacy settings, apps, redirects, and browser behavior can hide or alter the source. Use it to spot patterns, not to reconstruct every reader’s journey.

Engagement: Did readers spend time with the work?

Depending on what your analytics setup supports, look at reading time, scroll or completion signals, reactions, comments, and newsletter signups. These are clues rather than a full account of what a person understood.

For example, a short visit could mean the article answered the question quickly, or that it was not a fit. Pair numbers with the article’s purpose and with reader feedback when you have it.

Outcomes: Did the article help someone take a useful next step?

Choose an action that fits the post. That might be opening a demo, reading a related guide, subscribing to an author newsletter, or trying a project. Keep the next step clear and relevant instead of adding calls to action everywhere.

If your goal is learning and discovery, a useful comment or a question from a reader may matter more than a click. Define success before publishing so you do not judge every article by the same number.

Compare articles fairly

New posts have had less time to collect views than older ones. Compare articles over the same period after publication—for example, the first 7 or 30 days—and group similar formats together. A news post and an evergreen tutorial often have different traffic patterns.

Use medians or look at several posts rather than relying on one viral outlier. Keep a simple spreadsheet with the article URL, topic, format, publication date, distribution channels, and a few metrics. Add a short note about what you tried and what you would change.

Avoid treating platform totals as directly equivalent. Each service may define views, reads, and engagement differently. A combined dashboard is useful for seeing broad trends, while each platform’s own report remains the source for its metric definitions.

Turn observations into edits

Look for patterns you can act on:

If readers arrive from search but leave quickly, check whether the opening answers the query and whether the page is easy to scan.
If community shares bring visits but few return later, make the article useful as a reference and link to relevant follow-up material.
If readers reach the end but do not take the intended next step, make that step more specific and explain its value.
If a post keeps attracting readers months later, refresh examples and links so it stays dependable.
If a topic consistently earns thoughtful questions, consider a follow-up that answers them.

These are hypotheses, not automatic diagnoses. Review the actual article and reader comments before changing it. A metric can point to a question; it rarely supplies the whole answer.

What ZyVOP can show

ZyVOP provides article and author analytics for your publication, including views and reader engagement signals. When connected DEV or Hashnode accounts are available, its omnichannel analytics can bring supported performance metrics into one view. The platforms still define and expose their own measurements, so compare trends with that context in mind.

ZyVOP Pro also reports detected referrals from supported AI services when a browser sends a recognizable referrer. That can show some visits that arrived through services such as ChatGPT, Perplexity, Claude, or Gemini. It cannot count every time an AI system mentions or cites an article: many referrals do not preserve their source, and a visit is not the same as a citation.

For a small blog, start with a 30-day view and a handful of recent articles. Look at which topics attract readers, which sources send engaged visits, and whether people take the next step you intended. Then choose one improvement to test in your next post.

Build a lightweight monthly review

Once a month, spend 20 minutes on these questions:

Which articles reached the readers they were written for?
Where did engaged visits come from?
What questions or feedback did readers share?
Which older article needs an update?
What single change will you try in the next article?

You do not need a perfect attribution system to become a better writer. A few consistent measurements, honest limits, and regular revisions are enough to make your blog more useful over time.

Explore ZyVOP: Publication and analytics features · Developer publishing hub

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Own Your Writing and Build a More Portable Audience

Sanjay Singh — Sun, 01 Nov 2026 04:37:58 +0000

Publishing platforms make it easy to reach readers. They also shape how people discover your work, how you communicate with followers, and what happens when a product or policy changes.

Creators can make their work more portable without giving up the reach of established communities. The aim is to keep usable copies of your writing and create a few reader relationships that do not depend on one feed, profile, or recommendation system.

Treat portability as part of publishing

Keep your articles in a format you can move, such as Markdown with images stored in a folder or repository you control. Include useful metadata—title, publication date, tags, and canonical URL—so another system can understand the post later.

Make regular backups and occasionally open a few files to confirm they are complete. A backup you have never restored or inspected may be missing assets, metadata, or recent changes.

When you publish on several platforms, decide which copy is the primary version. Keep links between versions consistent, and review canonical settings when a platform supports them. These signals help search engines understand the relationship between copies, though search engines choose what to index.

Give your work a stable home

A domain you control gives readers a consistent place to find your writing, even if the software behind it changes. Use clear URLs, keep an index or archive of your posts, and provide an About page that explains what you write and how readers can follow along.

If you change publishing platforms, plan how old links will work. Keep the old site or configure redirects when you control the domain. If redirects are unavailable, update important profile links and add a short notice that points readers to the new home.

Build direct reader relationships with consent

Followers on a social or publishing platform are useful, but access to them depends on that platform. A newsletter or mailing list can provide a direct way to send updates, provided readers knowingly choose to subscribe and can unsubscribe easily.

Keep the signup promise specific: say what you will send and how often. Confirm subscriptions, respect preferences, and avoid adding addresses collected for another purpose. Export your subscriber records periodically if your email provider allows it, and store them securely.

An email list is not a license to interrupt people. Treat it as a relationship that readers can pause or end, and make every message worth receiving.

Use platforms for discovery

You can publish a full article on your own site and share a useful excerpt or discussion in communities where your readers already spend time. Follow each platform’s rules, link to the original when appropriate, and adapt the post to the conversation rather than pasting the same promotion everywhere.

Different channels serve different purposes: a community feed can help a new article get noticed, search can bring readers to older work, and email can reach subscribers directly. Track which sources bring engaged readers, then spend time on the channels that fit your goals.

How ZyVOP supports portable publishing

ZyVOP brings a publication home, content backups, and distribution tools together for technical writers. You can keep an optional GitHub backup of published articles as Markdown, then publish to connected destinations such as DEV, Hashnode, Medium, and WordPress.

ZyVOP also offers an author newsletter with double opt-in. Verified subscriber records can be exported as CSV, giving you a portable copy of the readers who chose to hear from you. Followers and conversations on other platforms remain in those communities, so keep using them for discovery and discussion.

Keep a simple creator portability checklist

Keep a local or repository copy of every article and its assets.
Use a domain or profile URL you can maintain over time.
Record each post’s original URL and any republished versions.
Back up subscriber data only where permitted, and protect it carefully.
Keep a list of the platforms where you publish and how to export your work.
Review your links and backups a few times each year.

You do not need to leave every platform or build a complicated publishing stack. Start by making one copy of your writing portable, setting up one direct subscription option, and linking your profiles to a stable home. Those small habits give you more choices when your publishing needs change.

Readers decide where they spend their attention. Your part is to make your work easy to find, keep it available in formats you can move, and give people a clear, respectful way to hear from you again.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How to Move Your Blog from Hashnode or DEV.to to ZyVOP

Sanjay Singh — Sat, 31 Oct 2026 08:06:59 +0000

Moving a blog can feel risky when you have years of posts, code samples, and images tied to one platform. A safer approach is to copy your articles first, review them in their new home, and decide what to do with the originals afterward.

ZyVOP imports articles as private drafts, so you can check the results before publishing. Your Hashnode or DEV.to posts stay where they are during the import.

Before you start

Make a list of the posts you want to move and decide which platform should be the primary home for each article. Keep your original blog available while you review the imported drafts.

Also decide how you want to handle duplicate versions. ZyVOP retains the source article URL as the canonical URL during import. If you plan to keep the original post live, that may be the right setting. If ZyVOP should become the primary version, review the canonical URL before publishing. Canonical URLs help search engines understand your preference, but search engines make the final choice. Google Search Central explains canonicalization.

Move your articles from DEV.to

Open the DEV.to migration page.
Enter your DEV.to username or profile URL, such as dev.to/yourusername.
Preview the articles ZyVOP finds. You can also paste an individual article URL to import one post.
Choose the option to import the archive as private drafts.
Open your drafts and review the imported posts before publishing.

The archive import works with publicly published articles. It carries over article content, tags, cover image references, publication dates, and the original article URL. Private DEV.to drafts aren’t included. DEV-specific Liquid tags may be converted to standard Markdown, so check those sections in the imported copy. See the DEV.to migration details.

Move your articles from Hashnode

For a full Hashnode archive, the most reliable route is a GitHub backup ZIP:

As a publication owner or admin, open Publication Dashboard → GitHub in Hashnode.
Select Connect, install the Hashnode GitHub Backup app, and choose a repository. Create an empty repository first if you need one.
Run Backup all posts. If you also want drafts, run Backup all drafts.
Check Deliveries in Hashnode to confirm the backup succeeded.
Download the repository as a ZIP.
In ZyVOP, upload it from Dashboard → Posts → Import Articles → Hashnode Backup.

Hashnode lists GitHub backups as a Pro feature, and its backup includes Markdown files with publishing metadata. Read Hashnode’s Pro announcement.

You can also preview a public Hashnode publication by entering its domain on the Hashnode migration page. If the archive can’t be accessed, try importing individual public article URLs instead. Access to public articles can vary.

Review the imported drafts

Before publishing, check a few posts from different parts of your archive:

Make sure headings, code blocks, lists, and links render correctly.
Open images and verify the cover image. Replace externally hosted images if you want copies that don’t depend on the original platform.
Check tags, publication dates, and canonical URLs.
Review older posts for embeds or platform-specific formatting that may need editing.

Imports copy your articles; they don’t move your comments, reactions, or followers into ZyVOP. Keep your original profile available if readers still use it to find you or discuss older posts.

Publish when you’re ready

Once your drafts look right, decide which ones to publish and what to do with the originals. If you control the old domain, redirects can help send readers to the new URLs. If the articles remain live on both platforms, make sure the canonical settings match the plan you chose.

A staged move gives you time to check the details before changing where readers find your work. Start with a small batch, review it, and then import the rest of your archive.

Learn more: Import from DEV.to · Import from Hashnode · Google’s guide to canonical URLs

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How to Turn Your Git Repository into a Multi-Platform Publishing CMS

Sanjay Singh — Thu, 29 Oct 2026 02:29:32 +0000

As software engineers, we rely on Git for virtually everything: version control, code review, collaborative branches, and CI/CD pipelines. Our favorite environments are Neovim, VS Code, and Obsidian—distraction-free tools where we think and write in clean, plain-text Markdown.

Yet, when it comes to publishing technical articles, we are often forced into one of two extremes:

The Isolated Static Blog: You set up an Astro, Hugo, or Next.js blog. You get 100% control and Git versioning, but you face the harsh "cold-start" reality: zero organic traffic. Without an existing audience, your articles sit on an empty digital island.
The Walled-Garden Grind: You publish directly on platforms like Dev.to, Hashnode, or Medium to tap into their built-in reader networks. But now you're stuck writing inside web dashboards, wrestling with proprietary WYSIWYG editors, manually copy-pasting across tabs, and risking platform lock-in.

The solution is not to choose between ownership and distribution. The solution is GitOps for publishing: treat your Git repository as the authoritative single source of truth, and let automated pipelines handle distribution.

In this guide, you’ll learn how to transform any Git repository into an automated, multi-platform publishing engine using ZyVOP and GitHub Actions.

The GitOps Publishing Workflow

Instead of logging into multiple web CMS dashboards, your entire publishing workflow lives right in your terminal and repository:

Author: Write your post in local Markdown with standard YAML frontmatter.
Commit & Push: Commit your draft and push to your main branch.
Automate: GitHub Actions triggers the zyvop CLI to parse and validate your article.
Distribute: ZyVOP publishes the post to your canonical publication domain and syndicates copies across Dev.to, Medium, Hashnode, and WordPress—injecting rel="canonical" tags everywhere to safeguard your SEO.

Step 1: Structure Your Writing Repository

Create a clean repository (or a dedicated content/ folder in your existing monorepo):

my-tech-blog/
├── .github/
│   └── workflows/
│       └── publish.yml
├── posts/
│   ├── 2026-10-distributed-locks-redis.md
│   └── 2026-10-postgres-full-text-search.md
├── assets/
│   └── redis-architecture.png
├── .gitignore
└── README.md

Writing Your Post with YAML Frontmatter

ZyVOP parses standard YAML frontmatter to configure tags, publication details, and cross-posting targets.

Create posts/2026-10-distributed-locks-redis.md:

---
title: "Understanding Distributed Locks with Redis and BullMQ"
subtitle: "A deep dive into avoiding race conditions in background job workers."
slug: "distributed-locks-redis-bullmq"
date: "2026-10-27"
tags:
  - redis
  - backend
  - nodejs
  - system-design
canonical_url: "https://blog.yourdomain.com/posts/distributed-locks-redis-bullmq"
cross_post:
  devto: true
  hashnode: true
  medium: false
ai_disclosure: "none"
---

# Understanding Distributed Locks with Redis and BullMQ

When scaling background queue workers across multiple container instances, race conditions are inevitable...

Step 2: Validate Locally with `npx zyvop`

You don’t need to install heavy CLI dependencies globally. ZyVOP provides a zero-install CLI via npx:

# Authenticate your terminal
npx zyvop login

Run a Local Dry Run

Before pushing anything live, run a dry run to inspect the payload, ensure relative image links resolve properly, and verify cross-posting flags:

npx zyvop publish ./posts/2026-10-distributed-locks-redis.md --dry-run

The CLI inspects your frontmatter, renders Markdown AST nodes, validates media references, and prints the exact destination plan without contacting external publishing APIs.

Step 3: Automate Publishing with GitHub Actions

Now connect your repository to CI/CD so that every merged commit to main publishes your content automatically.

1. Generate a ZyVOP Developer Token

Go to your ZyVOP Dashboard → Settings → Developer API.
Generate a new Developer Token (zyvop_live_...).
In your GitHub repository, navigate to Settings → Secrets and variables → Actions.
Add a repository secret named ZYVOP_TOKEN with your token value.

2. Create the GitHub Actions Workflow

Create .github/workflows/publish.yml:

name: Publish Content via ZyVOP

on:
  push:
    branches:
      - main
    paths:
      - 'posts/**.md'

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2 # Fetch previous commit to detect file diffs

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Publish changed articles
        env:
          ZYVOP_TOKEN: ${{ secrets.ZYVOP_TOKEN }}
        run: |
          # Identify added or modified Markdown files
          CHANGED_FILES=$(git diff --name-only --diff-filter=AM HEAD~1 HEAD | grep '^posts/.*\.md$' || true)

          if [ -z "$CHANGED_FILES" ]; then
            echo "No Markdown files changed. Skipping publish."
            exit 0
          fi

          for FILE in $CHANGED_FILES; do
            echo "Publishing $FILE..."
            npx zyvop publish "$FILE"
          done

Step 4: The Crucial Difference — Automated Canonical SEO Protection

If you cross-post articles manually by copying text into Dev.to or Medium, Google can penalize your blog for duplicate content or rank the aggregator's domain above your own.

To prevent this, every syndication target must explicitly define a rel="canonical" link pointing back to your home publication.

When ZyVOP processes your article:

It sets your custom domain (https://blog.yourdomain.com/...) as the canonical root.
It communicates with the Dev.to REST API and sets canonical_url.
It connects to Hashnode GraphQL and attaches canonicalArticleURL.
It posts to Medium via its API and sets canonicalUrl.

Search engines recognize that your domain is the original intellectual author. Aggregator views generate top-of-funnel discovery, while all search authority flows directly back to your brand.

Step 5: Full Two-Way Peace of Mind (Automated Git Backup)

What happens if you make a quick typo fix or update tags directly in ZyVOP's web editor while away from your laptop?

ZyVOP includes Automated GitHub Backups. When enabled in your settings:

Every post created or updated on the web automatically commits a versioned Markdown file back to your designated GitHub repository.
Your Git repo never falls out of sync with your live publication.
You maintain 100% data sovereignty without manual export routines.

Summary: A Workflow Built for Developers

Publishing consistently as an engineer shouldn't mean spending your weekend fighting clunky CMS dashboards.

With a GitOps publishing stack:

Your editor remains your sanctuary: Write in Neovim, VS Code, or Obsidian.
Git handles your history: Diff changes, collaborate via pull requests, and keep backups.
ZyVOP handles the distribution: 1-click multi-platform syndication, automated rel="canonical" injection, and zero SEO headaches.

To start, run:

npx zyvop login
npx zyvop publish ./your-post.md --dry-run

Keep your thoughts in Git, and let automation do the publishing heavy lifting.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Schedule Technical Articles with ZyVOP: From Draft to Release

Sanjay Singh — Wed, 28 Oct 2026 11:16:39 +0000

Technical writing often happens in bursts. You might finish an article days before a feature launch, or write several posts during a quiet week and want to release them over time. Scheduling helps separate the moment you finish writing from the moment readers see the article.

ZyVOP supports scheduled publishing through its web editor and its Markdown publishing workflow. You can prepare an article, choose when it should go live, and let ZyVOP handle the release when that time arrives.

Schedule from the web editor

If you write in ZyVOP’s editor, open your draft and use the publishing drawer:

Choose Schedule for Later.
Select the date and time you want the post to go live.
Choose the time zone for that scheduled time.
Review the selected destinations.
Confirm with Schedule Article.

The editor is useful when you prefer a visual calendar-style decision and want to review destinations as part of the publishing step.

Schedule from Markdown

For a Git-based workflow, put the scheduled time in the article’s YAML front matter. Use an ISO 8601 timestamp with an explicit time zone offset; Z means UTC.

---
title: "Announcing Our New API"
status: "SCHEDULED"
scheduled_at: "2026-11-12T14:00:00Z"
tags: [api, engineering, release]
cross_post:
  devto: true
  hashnode: true
  bluesky: true
ai_disclosure: human_written
---

# What changed

Explain the release and what developers need to know...

Publish the file through the ZyVOP CLI:

npx zyvop publish posts/new-api.md

ZyVOP registers the article as scheduled using the scheduled_at value. An explicit offset prevents ambiguity when the person preparing the post and its readers are in different time zones.

What happens at release time

ZyVOP checks for scheduled posts regularly. When a post is due, its status changes from SCHEDULED to PUBLISHED. ZyVOP then starts cross-posting to the destinations enabled for that article. Other configured publication steps, such as follower notifications or newsletter delivery, can also run as part of publishing.

The destinations in front matter make the intended distribution visible alongside the article. Before scheduling, check that each selected platform is connected and that the content is ready for that destination.

Make a small release plan

Scheduling works best when the article is ready before its release time. A simple routine can help:

Draft and review the article first.
Confirm code samples, links, and release details.
Set the scheduled date and include an explicit time zone.
Review which destinations are selected.
Keep the Markdown source in Git so you can revise it before release.

For time-sensitive announcements, leave room for a final check before the scheduled time. Scheduling makes the release predictable, while a review keeps the information accurate.

Publish on your writing schedule

You can schedule one post in the editor or manage release dates next to Markdown articles in your repository. Either way, the goal is to make publishing fit around the work of writing, review, and product development.

Prepare the article, choose its release time, and let ZyVOP take care of the scheduled transition and configured distribution when it’s due.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Your VPN Doesn't Make You Private

Sanjay Singh — Wed, 28 Oct 2026 03:07:18 +0000

Every VPN ad makes the same promise. Click one button and you're private.

I don't buy it. I recently built a static IP setup with a VPN and Tailscale, and I found the whole project really interesting. It also got me thinking about what a VPN actually does, and what it doesn't.

A VPN is a useful tool. It just isn't a privacy strategy, and treating it like one leaves most people less protected than they think.

What a VPN actually does

Your traffic goes through an encrypted tunnel to the VPN's server, and then out to the internet from there.

Websites see the server's IP address instead of yours. Your internet provider sees that you're connected to a VPN, but not which sites you're visiting.

That's the whole trick. It's useful, but it's narrow.

You moved the trust, you didn't remove it

Before the VPN, your ISP could see where your traffic was going. After the VPN, the VPN company can. You haven't escaped anyone. You've picked a different party to trust.

That's fine if you pick well. The catch is that nearly every provider says it keeps no logs, and you usually can't check.

Sometimes the claim gets tested. In 2017, the FBI was investigating a cyberstalking case in Massachusetts and got help from PureVPN. The company advertised that it didn't keep logs that could identify or monitor a user's activity. According to reporting on the FBI's court filing, PureVPN was still able to confirm that the suspect's home IP address had connected to the VPN addresses involved, around the times investigators asked about. The records showed when he connected, not what he did online, but matched against logs from other services, that was enough.

Its privacy policy did mention connection logs, a detail the marketing skipped.

To be fair, PureVPN has since commissioned independent audits of its no-logs claims, which is the right move. But the case shows how thin a marketing line can be.

Now compare that with Mullvad. In April 2023, Swedish police arrived at its Gothenburg office with a search warrant, looking for customer data. According to Mullvad, the officers left without taking anything, because its systems don't hold that kind of data.

The point isn't that one brand is good and another is bad. "No logs" is a claim, and what counts is how the service is built, whether outsiders have audited it, and what happened when someone tested it.

Your IP address was never the main thing

Websites don't need your IP address to know who you are.

If you're logged in to Google, Amazon or Instagram, they know exactly who you are, whatever address you connect from. Cookies follow you around. On your phone, your advertising ID follows you from app to app.

Then there's browser fingerprinting. Your browser quietly shares details like your screen size, fonts, graphics hardware, language and time zone. Put together, they can make your browser look unique among millions of others.

A VPN changes none of that. Neither does a private browsing window.

You can see your own fingerprint on the EFF's Cover Your Tracks site. Run it with your VPN switched on and look at what comes back.

Free VPNs are often the worst offenders

Running servers around the world costs real money. If an app is free, ask how it pays for itself.

Researchers from the University of Michigan, the University of New Mexico and IIT Delhi tested 281 popular free Android VPN apps and presented the results at the NDSS security conference in February 2026. They found that 246 of the apps contacted known advertising or tracking servers, and 76 sent the phone's advertising ID. Twenty-nine leaked traffic outside the encrypted tunnel, including the DNS lookups that reveal which sites you visit.

People install a VPN to stop exactly this kind of thing. The Hacker News reported that the flagged apps have been installed more than 2.4 billion times.

It isn't a new problem. Researchers at Australia's CSIRO and partner universities looked at 283 Android VPN apps back in 2016 and found that three out of four used third-party tracking libraries.

The public Wi-Fi argument is weaker than it used to be

A lot of VPN marketing still leans on coffee shop Wi-Fi. That made sense when most of the web ran over plain HTTP.

It doesn't anymore. Google's Chrome security team says roughly 95 to 99 percent of page loads in Chrome use HTTPS on most platforms. The connection between you and the site is already encrypted, no VPN needed.

A VPN still hides which sites you visit from whoever runs the Wi-Fi, so it isn't useless there. It's just not the emergency it was sold as.

A static IP is the opposite of anonymous

This is the part my own project makes obvious.

A static IP never changes. If you route your traffic through one, every website sees the same address for you, every time. That's a stable identifier.

It's great for things like allowing only your own address to reach a server, or getting back into your home network. It's terrible for blending in.

Most commercial VPNs at least put you in a crowd, because many people share the same exit address. A VPN address that only you use takes the crowd away.

When a VPN does make sense

You want to hide your browsing from your ISP or from a network you don't control.
You need to get around IP-based blocking, censorship or a region lock.
You want a private path to your own things, like a home server or an office network. Tools like Tailscale are built for this, and it's a different job from privacy.
You need a fixed address so you can allowlist yourself somewhere.

What actually helps

Decide who you're hiding from. Your ISP, advertisers, a specific website and a government are different problems, and they need different tools.
Pick a provider with published independent audits and a real track record. Skip the one with the biggest ad budget, and be very careful with free apps.
Use a browser with fingerprinting protection and a tracker blocker.
Log out, or use separate browser profiles, for accounts you don't want tied to everything else you do.
Turn on HTTPS-only mode in your browser.

The bottom line

A VPN moves trust around and changes the address websites see. Sometimes that's exactly what you need.

But privacy comes from a stack of habits and tools, and a VPN is one small layer of it. The next time an ad says one click makes you private, ask the obvious follow-up: private from whom?

Sources

Mullvad, "Mullvad VPN was subject to a search warrant. Customer data not compromised" (April 2023): https://mullvad.net/en/blog/2023/4/20/mullvad-vpn-was-subject-to-a-search-warrant-customer-data-not-compromised/
ProPrivacy, "FBI Solves Case Thanks to PureVPN Lies": https://proprivacy.com/privacy-news/fbi-solves-case-vpn-lies
TechRadar, "Are VPNs safe? Not when you're a cyberstalker": https://www.techradar.com/news/are-vpn-safe-not-when-youre-a-cyberstalker
TechRadar, "PureVPN backs up no log claim with independent audit": https://www.techradar.com/news/purevpn-backs-up-no-log-claim-with-independent-audit
CSIRO and partners, "An Analysis of the Privacy and Security Risks of Android VPN Permission-enabled Apps" (2016): https://research.csiro.au/isp/wp-content/uploads/sites/106/2016/08/paper-1.pdf
NDSS Symposium 2026, "MVPNalyzer: An Investigative Framework for Auditing the Security & Privacy of Mobile VPNs": https://www.ndss-symposium.org/ndss-paper/mvpnalyzer-an-investigative-framework-for-auditing-the-security-privacy-of-mobile-vpns/
The Hacker News, "Study of 281 Free Android VPN Apps" (July 2026): https://thehackernews.com/2026/07/study-of-281-free-android-vpn-apps.html
EFF, Cover Your Tracks: https://coveryourtracks.eff.org
Google Online Security Blog, "HTTPS by default" (October 2025): https://security.googleblog.com/2025/10

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

I Built a Mini Git to Finally Understand How Version Control Works

Sanjay Singh — Tue, 27 Oct 2026 07:13:00 +0000

I had used Git for years by memorizing commands: commit, branch, checkout, and a quiet prayer whenever something went wrong. So I built a small version myself. minigit.py is a single file of about 400 lines of plain Python with no dependencies. It can init, add, commit, log, status, branch and checkout, and it stores everything in Git’s real on-disk format, so real Git can read the repositories it creates. This post walks through how it works, shows real output from it, and includes the complete code at the end. In the examples, mg is shorthand for python3 minigit.py; the setup is in the “Try it” section.

The big idea: Git is a key-value store

Underneath the commands, Git is a content-addressable filesystem: a key-value store where the key is the hash of the value. Everything else is built from a few simple pieces:

Blobs hold the contents of a file.
Trees hold a directory listing: names, modes, and the hashes of blobs and of other trees.
Commits point to one tree (a complete snapshot of the project) and to their parent commit, and carry an author and a message.
Refs are tiny files that give a name, like main, to a commit hash.
The index (the staging area) is the list of files that will go into the next commit.

A commit is not a diff. It points to a full snapshot, and Git avoids wasting space because identical content always has the same hash and is stored once. Diffs are computed on demand when you ask for them.

Step 1: The object store

Every object is stored the same way: a header with the type and size, a zero byte, then the content. Git hashes that with SHA-1, compresses it with zlib, and saves it under .git/objects, using the first two hex characters of the hash as a folder name. Here is my version, trimmed to the essentials:

def write_object(kind, data):
    store = kind.encode() + b" " + str(len(data)).encode() + b"\0" + data
    sha = hashlib.sha1(store).hexdigest()
    path = OBJECTS / sha[:2] / sha[2:]
    if not path.exists():  # same content -> same name -> stored only once
        path.parent.mkdir(parents=True, exist_ok=True)
        tmp = path.with_suffix(".tmp")
        tmp.write_bytes(zlib.compress(store))
        os.replace(tmp, path)  # atomic rename: never leaves a half-written object
    return sha

You can check the hash by hand. The file hello.txt contains the five letters of “hello” plus a newline, six bytes in all, so its blob header is blob 6:

import hashlib
data = b"hello\n"
print(hashlib.sha1(b"blob " + str(len(data)).encode() + b"\0" + data).hexdigest())
# ce013625030ba8dba906f756967f9e9ca394464a

Real Git gives the same answer: echo hello | git hash-object --stdin prints ce013625030ba8dba906f756967f9e9ca394464a. Decompressing the stored object shows exactly what was hashed:

>>> import zlib, pathlib
>>> zlib.decompress(pathlib.Path(".minigit/objects/ce/013625030ba8dba906f756967f9e9ca394464a").read_bytes())
b'blob 6\x00hello\n'

Because the name is the hash of the content, the same content always lands in the same place. When I added a second file with identical contents, no second object appeared; the index simply pointed at the one that was already there.

Step 2: Trees and commits

A tree is a list of entries sorted by name. Each entry is a file mode, a space, a name, a zero byte, and then the hash of the blob or subtree as 20 raw bytes. A directory is simply an entry that points to another tree. For a project with a hello.txt file and a src folder, cat-file prints:

$ mg cat-file 99555379c2fa0b5bd001e9240f3280d1b424e29b
100644 blob ce013625030ba8dba906f756967f9e9ca394464a    hello.txt
040000 tree ae6262de7e0cb6fb82ec1b206679365d55c44710    src
$ mg cat-file ae6262de7e0cb6fb82ec1b206679365d55c44710
100644 blob b80e3222ab264bd7cafb376749bd18814fd66776    main.py
040000 tree 4e6ce18496765b15fa5fd5d9ce54284bcfa814c5    utils

The code that writes a tree is short:

def write_tree(node):
    entries = []
    for name, value in node.items():
        if isinstance(value, dict):
            entries.append((name + "/", b"40000", name, write_tree(value)))
        else:
            entries.append((name, b"100644", name, value))
    # Git sorts entries bytewise, comparing directories as if their name ended in "/"
    entries.sort(key=lambda e: e[0].encode())
    body = b"".join(
        mode + b" " + name.encode() + b"\0" + bytes.fromhex(sha)
        for _, mode, name, sha in entries
    )
    return write_object("tree", body)

The sort line deserves attention. Git compares entry names as bytes, but it treats a directory as if its name ended in a slash. So in a folder containing a-b/, a.b, a/ and a0, the correct order is a-b, a.b, a, a0: the directory a sorts after a.b because / comes after . in ASCII. Sort by plain name and you get a different tree hash from real Git for the same files. I tested exactly that layout, along with a filename containing a space, a random binary file and a path three folders deep, and real Git’s git write-tree produced the identical tree hash.

A commit is a small text object. It names one tree, its parent commit if there is one, who made it and when, and the message:

def write_commit(tree, parent, message):
    lines = [f"tree {tree}"]
    if parent:
        lines.append(f"parent {parent}")
    who = identity()
    lines += [f"author {who}", f"committer {who}", "", message]
    return write_object("commit", ("\n".join(lines) + "\n").encode())

Here is a real one from my test session:

$ mg cat-file HEAD
tree b2ebf159fb11cd612e1c3e62636be14ce60424ad
parent ac81e445b2fa7e8ad7d6cb0c82ebb40d37e511c1
author Mini Git User <user@example.com> 1792911662 +0000
committer Mini Git User <user@example.com> 1792911662 +0000

say hello to the world

Because the parent’s hash is part of the text being hashed, history forms a chain. Hashing that exact text gives 84aecefd64e215f47906061afeaa4e1d54f0d081, the commit’s name. Change a single character of the parent hash and the same commit hashes to 71e59f5d44b5b906a602e17fd3b96f21a847a744. That is why amending or rebasing creates new commits instead of editing old ones: change anything, and every hash after it changes too.

I also rebuilt my first commit with real Git’s git commit-tree, feeding it the same tree, author and timestamp. The two commit hashes were identical, so my commit format matches Git’s byte for byte.

Step 3: Refs, branches and HEAD

A branch is a file that contains a commit hash. .minigit/refs/heads/main is a 41-byte file: 40 hex characters and a newline. HEAD is another file that says which branch you are on:

$ cat .minigit/HEAD
ref: refs/heads/main
$ cat .minigit/refs/heads/main
84aecefd64e215f47906061afeaa4e1d54f0d081

Committing writes the new commit’s hash into the branch file. Creating a branch writes the current hash into a new file. That is why branches are so cheap, and why branch needs only a few lines to create one. Checking out a raw commit hash instead of a branch name puts the hash straight into HEAD in place of the ref: line, and that is all a “detached HEAD” is.

Step 4: The index

The staging area is a list of every file that will be in the next commit, with the hash of its content. add stores the file as a blob and records its hash; commit turns that list into trees. Mine is a plain text file with one hash path pair per line:

$ cat .minigit/index.txt
ce013625030ba8dba906f756967f9e9ca394464a hello.txt
b80e3222ab264bd7cafb376749bd18814fd66776 src/main.py
7d4290a117a4ddcc11daae7ea675841033830c8f src/utils/helpers.py

Real Git uses a binary file called index. I learned the difference the hard way: my first version also named its text file index, and real Git’s fsck stopped with “index file corrupt” because it tried to parse my text as its binary format. Renaming mine to index.txt fixed it.

Step 5: The commands

commit builds the trees from the index, writes a commit object that points at the root tree and the current commit, and moves the current branch file forward. It refuses to commit when nothing has changed.
log starts at HEAD and follows parent pointers back to the first commit.
status compares three things: the last commit, the index, and the files on disk. That three-way comparison is why Git talks about changes that are “staged” and changes that are “not staged.”
checkout reads the target commit’s tree, deletes tracked files that are not in it, writes the files that are, rebuilds the index, and moves HEAD.

checkout is the dangerous one, because it overwrites your files. So before it touches anything, mine refuses if it would destroy work that no commit contains: staged changes, edits that are not staged, or an untracked file sitting where a file from the target commit needs to go. I tested all three cases, and each time it stops and lists the files at risk.

Try it

Save the complete code from the end of this post as minigit.py. It needs Python 3.9 or newer (I ran it on Python 3.12, on Linux). In a Linux or macOS shell, from the folder that contains the file, set up the shorthand and create an empty project folder:

alias mg="python3 $PWD/minigit.py"
mkdir demo && cd demo

Commits record an author. Set your own with environment variables, for example export MINIGIT_NAME="Ada Lovelace" and export MINIGIT_EMAIL="ada@example.com"; otherwise a generic default is used. Here is a real session:

$ mg init
Initialized empty minigit repository in .minigit/
$ echo "hello" > hello.txt
$ mg add hello.txt
$ mg commit -m "add hello"
[main ac81e44] add hello
$ echo "world" >> hello.txt
$ mg status
On branch main

Changes not staged for commit:
    modified:   hello.txt
$ mg add hello.txt
$ mg commit -m "say hello to the world"
[main 84aecef] say hello to the world
$ mg log
commit 84aecefd64e215f47906061afeaa4e1d54f0d081
Author: Mini Git User <user@example.com>
Date:   Sun Oct 25 07:01:02 2026 +0000

    say hello to the world

commit ac81e445b2fa7e8ad7d6cb0c82ebb40d37e511c1
Author: Mini Git User <user@example.com>
Date:   Sun Oct 25 07:01:02 2026 +0000

    add hello

$ mg branch experiment
$ mg checkout experiment
Switched to branch 'experiment'
$ echo "something risky" >> hello.txt
$ mg add hello.txt
$ mg commit -m "try something risky"
[experiment 4ead1cc] try something risky
$ mg checkout main
Switched to branch 'main'
$ cat hello.txt
hello
world
$ mg branch
  experiment
* main

Hashes and dates in your own session will differ, because commit hashes include the time and the author. Blob and tree hashes will match mine whenever the file contents match.

Looking inside the repository

After that session the repository holds nine objects: three commits, three trees (one per commit) and three blobs (one per version of hello.txt). Each is a file named after its hash:

$ find .minigit/objects -type f | sort
.minigit/objects/4e/ad1cc0a4d605366339238d6dcccc83a2e42c82
.minigit/objects/58/b9ac5a3c54a47a5c7425164e37c22d13588671
.minigit/objects/84/aecefd64e215f47906061afeaa4e1d54f0d081
.minigit/objects/86/caec1c87153c706021a1ca1e566f43dd155e6a
.minigit/objects/94/954abda49de8615a048f8d2e64b5de848e27a1
.minigit/objects/aa/a96ced2d9a1c8e72c56b253a0e2fe78393feb7
.minigit/objects/ac/81e445b2fa7e8ad7d6cb0c82ebb40d37e511c1
.minigit/objects/b2/ebf159fb11cd612e1c3e62636be14ce60424ad
.minigit/objects/ce/013625030ba8dba906f756967f9e9ca394464a

Proof that it is real Git

Setting GIT_DIR tells real Git to use .minigit instead of .git. After that, ordinary Git commands work on a repository that real Git never created:

$ export GIT_DIR=.minigit
$ git log --oneline --all
4ead1cc try something risky
84aecef say hello to the world
ac81e44 add hello
$ git fsck --full && echo "fsck: no problems found"
fsck: no problems found

Beyond that session, I checked three things against Git 2.43.0. A blob’s hash equals the output of git hash-object. A commit rebuilt with git commit-tree has the identical hash. A tree with awkward names and nesting has the identical hash from git write-tree. I also ran 19 edge-case checks covering binary files, filenames with spaces, deleted files, the checkout safety refusals and invalid branch names, and all of them passed. After a run of commits, branch switches and checkouts, git log and minigit.py log listed the same commit hashes in the same order. To repeat the check on your own repository, GIT_DIR=.minigit git fsck --full and GIT_DIR=.minigit git log --oneline --all are all you need.

What it can’t do

This is a learning tool, not a replacement for Git. It has no merge, no diff, no remotes (so no clone, push or pull), no tags and no .gitignore. Every object is stored loose, while real Git also packs history into compressed packfiles. Every file is stored as a regular file, so the executable bit and symlinks are not preserved. It must be run from the repository root, and it does not handle filenames that contain a newline. For real projects, use the real thing.

What building it taught me

Git stores snapshots, not diffs. Every commit points at a complete tree, and shared content is stored only once because of hashing.
Branches and HEAD are tiny text files. The history itself is a pile of compressed objects named by their hashes.
A branch is a sticky note. Moving or creating one is a single small write, which is why branching costs almost nothing.
Hashes chain history together. Changing an old commit changes every commit after it, which is why rewriting history produces new commits.
Detached HEAD is not scary. It only means HEAD holds a hash instead of a branch name.
checkout is where Git protects your work. The check that stops it from overwriting uncommitted changes is the most important part of the command.

If you use Git every day, I recommend building even a smaller version of this. After an afternoon with objects, trees and refs, the commands stop being magic.

The complete code

Here is the whole script, exactly as I tested it. Save it as minigit.py and follow the steps in “Try it” above.

#!/usr/bin/env python3
"""
minigit.py - a tiny Git in one file (Python 3.9+, standard library only).

Objects are stored in Git's real on-disk format, so real Git can read them:
    GIT_DIR=.minigit git log
    GIT_DIR=.minigit git fsck

Commands: init, add, commit, log, status, branch, checkout, cat-file
Run every command from the repository root:  python minigit.py <command> ...
"""
import argparse
import hashlib
import os
import sys
import time
import zlib
from pathlib import Path

GIT = Path(".minigit")
OBJECTS = GIT / "objects"

def die(msg):
    sys.exit(f"minigit: {msg}")

# ------------------------------------------------------------------
# 1. The object store: a key-value store where key = hash of the value
# ------------------------------------------------------------------
def write_object(kind, data):
    """Store data as '<kind> <size>\\0<data>', zlib-compressed, named by its SHA-1."""
    store = kind.encode() + b" " + str(len(data)).encode() + b"\0" + data
    sha = hashlib.sha1(store).hexdigest()
    path = OBJECTS / sha[:2] / sha[2:]
    if not path.exists():  # same content -> same name -> stored only once
        path.parent.mkdir(parents=True, exist_ok=True)
        tmp = path.with_suffix(".tmp")
        tmp.write_bytes(zlib.compress(store))
        os.replace(tmp, path)  # atomic rename: never leaves a half-written object
    return sha

def read_object(sha):
    path = OBJECTS / sha[:2] / sha[2:]
    if not path.exists():
        die(f"object {sha} not found")
    header, _, body = zlib.decompress(path.read_bytes()).partition(b"\0")
    return header.split(b" ")[0].decode(), body

def hash_blob(data):
    """The sha a file's content would get as a blob, without writing anything."""
    return hashlib.sha1(b"blob " + str(len(data)).encode() + b"\0" + data).hexdigest()

# ------------------------------------------------------------------
# 2. Trees (directories) and commits
# ------------------------------------------------------------------
def write_tree(node):
    """node = {name: blob sha, or a nested dict for a subdirectory} -> tree sha."""
    entries = []
    for name, value in node.items():
        if isinstance(value, dict):
            entries.append((name + "/", b"40000", name, write_tree(value)))
        else:
            entries.append((name, b"100644", name, value))
    # Git sorts entries bytewise, comparing directories as if their name ended in "/"
    entries.sort(key=lambda e: e[0].encode())
    body = b"".join(
        mode + b" " + name.encode() + b"\0" + bytes.fromhex(sha)
        for _, mode, name, sha in entries
    )
    return write_object("tree", body)

def parse_tree(body):
    """Raw tree bytes -> list of (mode, name, sha)."""
    entries, i = [], 0
    while i < len(body):
        space = body.index(b" ", i)
        nul = body.index(b"\0", space)
        entries.append((body[i:space].decode(), body[space + 1 : nul].decode(), body[nul + 1 : nul + 21].hex()))
        i = nul + 21
    return entries

def read_tree(sha, prefix=""):
    """Tree sha -> flat {path: blob sha} for every file below it."""
    files = {}
    for mode, name, entry_sha in parse_tree(read_object(sha)[1]):
        if mode == "40000":
            files.update(read_tree(entry_sha, prefix + name + "/"))
        else:
            files[prefix + name] = entry_sha
    return files

def tree_from_index(index):
    root = {}
    for path, sha in index.items():
        *folders, filename = path.split("/")
        node = root
        for folder in folders:
            node = node.setdefault(folder, {})
        node[filename] = sha
    return write_tree(root)

def identity():
    name = os.environ.get("MINIGIT_NAME", "Mini Git User")
    email = os.environ.get("MINIGIT_EMAIL", "user@example.com")
    offset = time.localtime().tm_gmtoff
    tz = f"{'+' if offset >= 0 else '-'}{abs(offset) // 3600:02d}{abs(offset) % 3600 // 60:02d}"
    return f"{name} <{email}> {int(time.time())} {tz}"

def write_commit(tree, parent, message):
    lines = [f"tree {tree}"]
    if parent:
        lines.append(f"parent {parent}")
    who = identity()
    lines += [f"author {who}", f"committer {who}", "", message]
    return write_object("commit", ("\n".join(lines) + "\n").encode())

def read_commit(sha):
    kind, body = read_object(sha)
    if kind != "commit":
        die(f"{sha[:7]} is a {kind}, not a commit")
    header, _, message = body.decode().partition("\n\n")
    info = {"parent": None}
    for line in header.split("\n"):
        key, _, value = line.partition(" ")
        info[key] = value
    info["message"] = message.rstrip("\n")
    return info

def format_date(who):
    _, stamp, tz = who.rsplit(" ", 2)
    offset = (1 if tz[0] == "+" else -1) * (int(tz[1:3]) * 3600 + int(tz[3:5]) * 60)
    return time.strftime("%a %b %d %H:%M:%S %Y", time.gmtime(int(stamp) + offset)) + " " + tz

# ------------------------------------------------------------------
# 3. Refs: a branch is just a file holding a commit sha; HEAD points at one
# ------------------------------------------------------------------
def head_ref():
    """'refs/heads/main' if HEAD is on a branch, None if HEAD is detached."""
    text = (GIT / "HEAD").read_text().strip()
    return text[5:] if text.startswith("ref: ") else None

def head_commit():
    ref = head_ref()
    if ref is None:
        return (GIT / "HEAD").read_text().strip()
    path = GIT / ref
    return path.read_text().strip() if path.exists() else None

def resolve(name):
    """Branch name, 'HEAD', or a (short) commit sha -> full sha, or None."""
    if name == "HEAD":
        return head_commit()
    branch = GIT / "refs" / "heads" / name
    if branch.is_file():
        return branch.read_text().strip()
    if len(name) >= 4 and all(c in "0123456789abcdef" for c in name):
        folder = OBJECTS / name[:2]
        found = [name[:2] + f.name for f in folder.iterdir() if f.name.startswith(name[2:])] if folder.is_dir() else []
        if len(found) > 1:
            die(f"'{name}' is ambiguous")
        return found[0] if found else None
    return None

# ------------------------------------------------------------------
# 4. The index (staging area) and the working directory.
#    Ours is a plain text file of "<sha> <path>" lines. Git's real index is a
#    binary file named "index", so we use "index.txt" to avoid confusing it.
# ------------------------------------------------------------------
def read_index():
    path = GIT / "index.txt"
    if not path.exists():
        return {}
    return dict(line.split(" ", 1)[::-1] for line in path.read_text().splitlines() if line)

def write_index(index):
    (GIT / "index.txt").write_text("".join(f"{sha} {path}\n" for path, sha in sorted(index.items())))

def working_files():
    found = []
    for root, dirs, names in os.walk("."):
        dirs[:] = [d for d in dirs if d not in (".minigit", ".git")]
        found += [os.path.relpath(os.path.join(root, n)).replace(os.sep, "/") for n in names]
    return sorted(found)

def is_modified(path, sha):
    return not os.path.isfile(path) or hash_blob(Path(path).read_bytes()) != sha

# ------------------------------------------------------------------
# 5. Commands
# ------------------------------------------------------------------
def cmd_init(_):
    if GIT.exists():
        die("repository already exists")
    (GIT / "objects").mkdir(parents=True)
    (GIT / "refs" / "heads").mkdir(parents=True)
    (GIT / "HEAD").write_text("ref: refs/heads/main\n")
    print("Initialized empty minigit repository in .minigit/")

def cmd_add(args):
    index = read_index()
    for arg in args.paths:
        rel = os.path.relpath(arg).replace(os.sep, "/")
        if rel == ".." or rel.startswith("../") or rel.split("/")[0] in (".minigit", ".git"):
            die(f"cannot add '{arg}'")
        if os.path.isdir(rel):
            inside = lambda p: rel == "." or p.startswith(rel + "/")
            targets = [p for p in working_files() if inside(p)]
            gone = [p for p in index if inside(p) and not os.path.exists(p)]
        elif os.path.isfile(rel):
            targets, gone = [rel], []
        elif rel in index:  # file was deleted: staging that removes it
            targets, gone = [], [rel]
        else:
            die(f"pathspec '{arg}' did not match any files")
        for path in gone:
            del index[path]
        for path in targets:
            index[path] = write_object("blob", Path(path).read_bytes())
    write_index(index)

def cmd_commit(args):
    if not args.message.strip():
        die("empty commit message")
    index = read_index()
    parent = head_commit()
    if not index and not parent:
        die("nothing staged: use `add` first")
    tree = tree_from_index(index)
    if parent and tree == read_commit(parent)["tree"]:
        die("nothing to commit: no changes staged since the last commit")
    sha = write_commit(tree, parent, args.message)
    ref = head_ref()
    (GIT / ref if ref else GIT / "HEAD").write_text(sha + "\n")
    print(f"[{ref.removeprefix('refs/heads/') if ref else 'detached HEAD'} {sha[:7]}] {args.message.splitlines()[0]}")

def cmd_log(_):
    sha = head_commit()
    if not sha:
        die("no commits yet")
    while sha:
        commit = read_commit(sha)
        print(f"commit {sha}")
        print(f"Author: {commit['author'].rsplit(' ', 2)[0]}")
        print(f"Date:   {format_date(commit['author'])}\n")
        print("\n".join("    " + line for line in commit["message"].splitlines()) + "\n")
        sha = commit["parent"]

def cmd_status(_):
    index = read_index()
    head = head_commit()
    committed = read_tree(read_commit(head)["tree"]) if head else {}
    ref = head_ref()
    print(f"On branch {ref.removeprefix('refs/heads/')}" if ref else f"HEAD detached at {head[:7]}")

    staged = []
    for path in sorted(set(index) | set(committed)):
        if path not in committed:
            staged.append(f"{'new file:':<12}{path}")
        elif path not in index:
            staged.append(f"{'deleted:':<12}{path}")
        elif index[path] != committed[path]:
            staged.append(f"{'modified:':<12}{path}")
    unstaged = []
    for path in sorted(index):
        if is_modified(path, index[path]):
            label = "modified:" if os.path.isfile(path) else "deleted:"
            unstaged.append(f"{label:<12}{path}")
    untracked = [p for p in working_files() if p not in index]

    for title, items in (
        ("Changes to be committed", staged),
        ("Changes not staged for commit", unstaged),
        ("Untracked files", untracked),
    ):
        if items:
            print(f"\n{title}:")
            for item in items:
                print("   ", item)
    if not (staged or unstaged or untracked):
        print("\nnothing to commit, working tree clean")

def cmd_branch(args):
    heads = GIT / "refs" / "heads"
    if args.name is None:
        for path in sorted(heads.rglob("*")):
            if path.is_file():
                name = path.relative_to(heads).as_posix()
                print(("* " if head_ref() == f"refs/heads/{name}" else "  ") + name)
        return
    if ".." in args.name or " " in args.name or args.name.startswith(("/", "-")):
        die("invalid branch name")
    sha = head_commit()
    if not sha:
        die("cannot create a branch before the first commit")
    path = heads / args.name
    if path.exists():
        die(f"branch '{args.name}' already exists")
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(sha + "\n")

def cmd_checkout(args):
    sha = resolve(args.target)
    if sha is None:
        die(f"unknown branch or commit '{args.target}'")
    target = read_tree(read_commit(sha)["tree"])
    index = read_index()
    head = head_commit()
    committed = read_tree(read_commit(head)["tree"]) if head else {}

    # Refuse to continue if checkout could destroy work that no commit contains.
    unsafe = {p for p in set(index) | set(committed) if index.get(p) != committed.get(p)}  # staged
    unsafe |= {p for p in index if is_modified(p, index[p])}  # edited or deleted, not staged
    unsafe |= {p for p in target if p not in index and os.path.exists(p)}  # untracked file in the way
    if unsafe:
        die("checkout would lose changes to: " + ", ".join(sorted(unsafe)) + "\ncommit or remove them first")

    for path in index:  # remove files that don't exist in the target commit
        if path not in target:
            os.remove(path)
            folder = os.path.dirname(path)
            while folder:  # and any directories left empty
                try:
                    os.rmdir(folder)
                except OSError:
                    break
                folder = os.path.dirname(folder)
    for path, blob in target.items():  # write files from the target commit
        if index.get(path) != blob:
            os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
            Path(path).write_bytes(read_object(blob)[1])
    write_index(target)

    if (GIT / "refs" / "heads" / args.target).is_file():
        (GIT / "HEAD").write_text(f"ref: refs/heads/{args.target}\n")
        print(f"Switched to branch '{args.target}'")
    else:
        (GIT / "HEAD").write_text(sha + "\n")
        print(f"HEAD is now at {sha[:7]} (detached)")

def cmd_cat_file(args):
    sha = resolve(args.object)
    if sha is None:
        die(f"unknown object '{args.object}'")
    kind, body = read_object(sha)
    if kind == "tree":
        for mode, name, entry in parse_tree(body):
            print(f"{mode.zfill(6)} {'tree' if mode == '40000' else 'blob'} {entry}\t{name}")
    else:
        sys.stdout.write(body.decode(errors="replace"))

def main():
    parser = argparse.ArgumentParser(prog="minigit", description="A tiny Git.")
    sub = parser.add_subparsers(dest="command", required=True)
    sub.add_parser("init").set_defaults(fn=cmd_init)
    p = sub.add_parser("add")
    p.add_argument("paths", nargs="+")
    p.set_defaults(fn=cmd_add)
    p = sub.add_parser("commit")
    p.add_argument("-m", "--message", required=True)
    p.set_defaults(fn=cmd_commit)
    sub.add_parser("log").set_defaults(fn=cmd_log)
    sub.add_parser("status").set_defaults(fn=cmd_status)
    p = sub.add_parser("branch")
    p.add_argument("name", nargs="?")
    p.set_defaults(fn=cmd_branch)
    p = sub.add_parser("checkout")
    p.add_argument("target")
    p.set_defaults(fn=cmd_checkout)
    p = sub.add_parser("cat-file")
    p.add_argument("object")
    p.set_defaults(fn=cmd_cat_file)
    args = parser.parse_args()
    if args.command != "init" and not GIT.is_dir():
        die("not a minigit repository (run `init` first, and run from the repo root)")
    args.fn(args)

if __name__ == "__main__":
    main()

Credits and sources

Git internals: the structure of blobs, trees, commits and refs follows Git’s own design as described in the Pro Git book by Scott Chacon and Ben Straub, chapter 10: Git Internals – Git Objects.
Prior art: Mary Rose Cook’s Gitlet, a Git implementation in JavaScript written to learn how Git works, and her article Introducing Gitlet. The script in this post is a much smaller take on the same idea, in Python.
Tested with: Git 2.43.0 and Python 3.12 on Linux.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

DEV Community: Sanjay Singh

Add Runnable Code Examples to Your Technical Articles

Add Runnable Code Examples to Your Technical Articles

Choose an example that teaches one idea

Add a project in the editor

Run the checks before publishing

Explain what readers should notice

Know the runner’s boundaries

Bring the explanation and code closer together

Turn a Long Technical Guide into a Reader-Friendly Series

Decide whether the guide needs multiple parts

Give every chapter a useful endpoint

Create the series in ZyVOP

Put chapters in a helpful order

Help readers keep their place

Publish the whole guide at a sustainable pace

Make depth easier to navigate

How to Make Technical Articles Easier for AI Tools to Read

Start with a clear question and answer

Use headings that describe the section

Make summaries and metadata accurate

Support important claims with sources and examples

ZyVOP’s machine-readable resources

Treat machine readability as part of good publishing

How We Built Fast Search for ZyVOP Without Elasticsearch or Algolia

The problem with searching article text on every request

One query, several ways to find a post

Search should return useful results, not just matching text

Candidate recall still needs a golden test set

Keeping the interface quick

Why PostgreSQL was enough for us

What “fast” means here

How to Monitor Client Domains and SSL Certificates for Free Before They Expire

What we are building

Step 1: List your clients

Step 2: Create the Telegram bot

Step 3: Write the three checks

Step 4: Decide when to alert, and send the message

Step 5: Schedule it

Daily expiry checks with GitHub Actions

Frequent uptime checks on a VPS (optional)

Step 6: The mistake worth understanding

Step 7: Verify that it actually works

Limitations and security

Troubleshooting

Conclusion

How to Measure Your Developer Blog Beyond Page Views

Start with the question behind the metric

Use a small set of signals

Reach: Are people finding the article?

Engagement: Did readers spend time with the work?

Outcomes: Did the article help someone take a useful next step?

Compare articles fairly

Turn observations into edits

What ZyVOP can show

Build a lightweight monthly review

Own Your Writing and Build a More Portable Audience

Treat portability as part of publishing

Give your work a stable home

Build direct reader relationships with consent

Use platforms for discovery

How ZyVOP supports portable publishing

Keep a simple creator portability checklist

How to Move Your Blog from Hashnode or DEV.to to ZyVOP

Before you start

Move your articles from DEV.to

Move your articles from Hashnode

Review the imported drafts

Publish when you’re ready

How to Turn Your Git Repository into a Multi-Platform Publishing CMS

The GitOps Publishing Workflow

Step 1: Structure Your Writing Repository

Writing Your Post with YAML Frontmatter

Step 2: Validate Locally with npx zyvop

Run a Local Dry Run

Step 3: Automate Publishing with GitHub Actions

1. Generate a ZyVOP Developer Token

2. Create the GitHub Actions Workflow

Step 4: The Crucial Difference — Automated Canonical SEO Protection

Step 5: Full Two-Way Peace of Mind (Automated Git Backup)

Step 2: Validate Locally with `npx zyvop`