AnyLog Docs

Technical documentation for AnyLog Edge Data Fabric, built with Jekyll and hosted on GitHub Pages.

---

Goal

Build a proper documentation website at https://anylog.network/docs using Jekyll (same theme as OpenHorizon), replacing raw GitHub repo access with a structured, navigable site comparable to EdgeX or ReadTheDocs.

---

Source repositories

Repo	Purpose	Status
https://github.com/AnyLog-co/documentation	Old docs — ~279 files, comprehensive but unorganised, not a website	Source of truth for migration
EdgeLake documentation site	Ori's first Jekyll attempt — limited, semi-organised	To be deprecated
https://github.com/AnyLog-co/anylog-docs.github.io (branch: os-dev)	New Jekyll site — active development	Work in progress

---

Adding or Updating Content

1. Create or edit a page

All documentation lives in the _docs/ directory. Create a new Markdown file or edit an existing one:

_docs/<general-topic>/<specific-topic>.md

Every file must begin with this front matter block — the title field drives the Table of Contents:

---
title: Introduction to AnyLog
description: Understanding AnyLog's architecture, node types, and core concepts.
layout: page
---

2. Register it in the navigation

Open .github/scripts/navigation.py and add your page's slug to the appropriate section in ITEM_ORDER:

ITEM_ORDER = {
    "Getting Started": [
        "getting-started",
        "installing-anylog",
        "my-topic"       # ← add your slug here
    ],
    ...
}

The slug is the filename without the .md extension. The order of slugs within each section controls the order they appear in the sidebar.

navigation.py is consumed by validate_docs.py, which scans _docs/, reconciles it against ITEM_ORDER, and writes the nav block in _config.yml. This runs automatically on docker compose up — you do not need to invoke it manually.

---

Writing Guidelines

• Use relative paths for links between doc pages (e.g. [Install](installing-anylog.md))
• External links must open in a new tab:

  <a href="https://example.com" target="_blank">Link text</a>

• Keep front matter description to a single sentence — it appears as the subtitle under the page title

---

Contributing

This repo follows a PR-based workflow — do not push directly to main.

1. Make sure your local branch is in sync with main:

   git fetch origin
   git rebase origin/main

2. Create a feature branch, make your changes, then open a pull request against main
3. GitHub Pages builds and publishes automatically once the PR is merged

---

Prompting Claude to Update a Doc Page

A reliable pattern for getting Claude to rewrite or update a page while keeping it consistent with the rest of the docs:

1. Provide the raw GitHub URL of the file to update — in GitHub, open the file and click Raw, then copy the address bar URL
2. Provide the raw GitHub URL of an existing page whose layout you want the output to match
3. Include the required front matter block in your prompt
4. Ask Claude to rewrite the first file to match the structure and style of the second

Keep the prompt substantive — include at least a short paragraph describing the intent and audience for each major section you want changed, not just bullet points. The more context you give about tone, audience, and structure, the better the result.

Sample prompt

The following is a real example using remote-gui.md. Copy and adapt it for any page you want to update.

---

I need you to update the AnyLog documentation page for the Remote GUI.

File to update (raw URL): https://raw.githubusercontent.com/AnyLog-co/anylog-docs.github.io/refs/heads/main/_docs/Tools%20%26%20UI/remote-gui.md

Example file to match in style and structure (raw URL): https://raw.githubusercontent.com/AnyLog-co/anylog-docs.github.io/refs/heads/main/_docs/getting-started.md

Required front matter — keep this exactly at the top of the file:

---
title: Remote GUI
description: Architecture and developer reference for the AnyLog Remote GUI.
layout: page
---

What to change:

The current page reads like internal notes — it's dense and assumes the reader already knows the codebase. Rewrite it so a new developer joining the project can follow it from top to bottom. The architecture diagram and key terminology table are good and should stay, but the surrounding prose needs more context.

The "Running locally" section currently has two terminal blocks with commands that aren't explained — add a sentence before each block describing what it does and why. The uvicorn command in particular looks like it may have a path issue (CLI.local-cli-backend.main:app uses dots but the cd above already entered the subdirectory); please flag that or correct it.

The "Plugin system" section is the most important part for contributors — expand the intro paragraph to explain when someone would want to build a plugin versus modifying a core feature. Keep the code examples as-is.

Use relative links where linking to other pages in _docs/. Any link to an external repo or external site should use <a href="URL" target="_blank"> format. Do not change any section headings — the navigation relies on them.

---

Adjust the URLs, front matter, and the description of changes to match whatever page you are working on.

---

Local Development with Docker

The easiest way to preview the docs locally is via Docker — no Ruby or Jekyll installation required.

Prerequisites: Docker and Docker Compose

git clone https://github.com/AnyLog-co/anylog-docs.github.io.git
cd anylog-docs.github.io
docker compose up -d

Once running, open your browser to http://localhost:4000.

The container mounts your local _docs/ directory, so edits are reflected live — no restart needed. To stop:

docker compose down

Troubleshooting: If the container exits immediately with a bundle write permissions error (There was an error while trying to write to /srv/bundle), run:

docker compose down -v
docker compose up -d

The -v flag removes the cached volume so it gets recreated with the correct permissions.