# Move a docs repo into PlaybookOps

> Import a folder of Markdown files into playbooks and folders, keeping titles, tags and links between documents. Safe to run again.

This recipe moves a Git repository of Markdown, like `docs/` or an agent-context repo, into PlaybookOps. Each top-level folder becomes a playbook, each subfolder becomes a folder inside it, and each `.md` file becomes a document. The script can run as often as you like: it only sends files that changed, and it never overwrites an edit someone made in the app.

### Make a key

Make a Custom key named "Docs import" with **Playbooks and documents** set to **Read and change**, and nothing else. The playbooks and documents will show it as their author, so use your own account or the account that should own them.

```bash
export PLAYBOOKOPS_API_KEY="pbo_live_…"
pip install httpx pyyaml
```

### Run the import

Save this as `import_docs.py` and run `python import_docs.py path/to/docs`. To put a folder into a playbook you already have, add it to `PLAYBOOKS`; every other top-level folder gets a new playbook named after it.

```python
"""Import a folder of Markdown files into PlaybookOps.

Each top-level folder becomes a playbook (or goes into the one mapped to it
below), and subfolders become folders. Running it again sends only the files
that changed since the last run.
"""
import hashlib
import json
import os
import posixpath
import re
import sys
import time
import uuid
from pathlib import Path
from urllib.parse import urlparse

import httpx
import yaml

# Top-level folder -> an existing playbook's id. "." is for files at the root.
# Anything not listed gets a new playbook.
PLAYBOOKS = {
    # "runbooks": "PLAYBOOK_ID",
}
MAX_FOLDER_DEPTH = 6
DOCUMENT_TYPES = {
    "sop", "process", "training", "policy", "procedure", "manual", "workflow",
    "internal_document", "job_description", "project_plan", "proven_process", "general",
}
STATE_FILE = Path(".playbookops-import.json")

FRONT_MATTER = re.compile(r"\A---\n(.*?)\n---\n?", re.S)
TITLE = re.compile(r"\A#\s+(.+)\n*")
MD_LINK = re.compile(r"\]\((?!https?:|mailto:|#)([^)\s]+?\.md)(#[^)\s]*)?\)")
LOCAL_IMAGE = re.compile(r"!\[[^\]]*\]\((?!https:)[^)]+\)")

api = httpx.Client(
    base_url="https://developers.playbookops.ai/v1",
    headers={"Authorization": f"Bearer {os.environ['PLAYBOOKOPS_API_KEY']}"},
    timeout=60,
)

def call(method: str, path: str, body: dict, key: str) -> dict:
    """Send one change, waiting out rate limits. The key makes retries safe."""
    while True:
        res = api.request(method, path, json=body, headers={"Idempotency-Key": key})
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", "5")))
            continue
        if res.is_error:
            raise RuntimeError(res.json()["error"]["message"])
        return res.json()

def nice(name: str) -> str:
    name = name.replace("-", " ").replace("_", " ").strip()
    return name[:1].upper() + name[1:]

def playbook_for(top: str, name: str, state: dict) -> str:
    """The playbook for a top-level folder, made the first time it's needed."""
    if top in PLAYBOOKS:
        return PLAYBOOKS[top]
    playbooks = state.setdefault("_playbooks", {})
    if top not in playbooks:
        made = call("POST", "/playbooks", {"name": nice(name), "description": f"Imported from {name}/"}, str(uuid.uuid4()))
        playbooks[top] = made["id"]
        print(f"playbook {made['name']}")
    return playbooks[top]

def folder_for(playbook_id: str, rel: str, state: dict) -> str | None:
    """The folder matching a file's subfolders, made as needed."""
    folders = state.setdefault("_folders", {})
    parts = rel.split("/")
    parent = None
    for depth in range(1, min(len(parts) - 1, MAX_FOLDER_DEPTH + 1)):
        path = "/".join(parts[: depth + 1])
        if path not in folders:
            body = {"name": nice(parts[depth]), "parent_folder_id": parent}
            folders[path] = call("POST", f"/playbooks/{playbook_id}/folders", body, str(uuid.uuid4()))["id"]
        parent = folders[path]
    return parent

def parse(rel: str, text: str) -> dict:
    """A document from a Markdown file: front matter for details and the
    first heading as the title."""
    meta = {}
    if found := FRONT_MATTER.match(text):
        meta = yaml.safe_load(found.group(1)) or {}
        text = text[found.end():]
    text = text.strip()
    title = meta.get("title")
    if heading := TITLE.match(text):
        title = title or heading.group(1).strip()
        text = text[heading.end():]  # the app shows the title above the body
    kind = meta.get("type", "general")
    return {
        "title": str(title or nice(posixpath.basename(rel)[:-3]))[:300],
        "description": str(meta.get("description") or "")[:2000],
        "document_type": kind if kind in DOCUMENT_TYPES else "general",
        "tags": [str(t) for t in meta.get("tags") or []][:20],
        "content": text,
    }

def import_file(root: Path, rel: str, text: str, state: dict) -> None:
    top = rel.split("/")[0] if "/" in rel else "."
    doc = parse(rel, text)
    digest = hashlib.sha256(json.dumps(doc, sort_keys=True).encode()).hexdigest()
    known = state.get(rel)
    if known and known["digest"] == digest:
        return
    playbook_id = playbook_for(top, root.resolve().name if top == "." else top, state)
    doc["folder_id"] = folder_for(playbook_id, rel, state)
    key = str(uuid.uuid5(uuid.NAMESPACE_URL, f"{rel}:{digest}"))
    if known:
        changes = {k: doc[k] for k in ("title", "description", "tags", "folder_id")}
        if doc["content"]:
            changes["content"] = doc["content"]
        try:
            # base_version: if someone edited it in the app since, leave it alone
            saved = call("PATCH", f"/documents/{known['id']}", {**changes, "base_version": known["version"]}, key)
        except RuntimeError as error:
            return print(f"kept     {rel}: {error}")
        print(f"updated  {rel}")
    else:
        saved = call("POST", f"/playbooks/{playbook_id}/documents", doc, key)
        print(f"created  {rel}")
    if LOCAL_IMAGE.search(text):
        print(f"         {rel} has images with local paths; give them https links")
    state[rel] = {"id": saved["id"], "version": saved["version"], "url": saved["url"], "digest": digest}

def link_file(rel: str, text: str, state: dict) -> None:
    """Point links to other imported files at their documents in the app."""
    known = state.get(rel)
    if not known or known.get("linked") == known["digest"]:
        return

    def to_document(match: re.Match) -> str:
        target = state.get(posixpath.normpath(posixpath.join(posixpath.dirname(rel), match.group(1))))
        if not target:
            return match.group(0)
        url = urlparse(target["url"])
        return f"]({url.path}?{url.query})"

    content = parse(rel, text)["content"]
    linked = MD_LINK.sub(to_document, content)
    if linked != content:
        key = str(uuid.uuid5(uuid.NAMESPACE_URL, f"{rel}:{known['digest']}:links"))
        try:
            saved = call("PATCH", f"/documents/{known['id']}", {"content": linked, "base_version": known["version"]}, key)
        except RuntimeError as error:
            return print(f"kept     {rel}: {error}")
        known["version"] = saved["version"]
        print(f"linked   {rel}")
    known["linked"] = known["digest"]

def main(root: Path) -> None:
    state = json.loads(STATE_FILE.read_text()) if STATE_FILE.exists() else {}
    files = {p.relative_to(root).as_posix(): p.read_text(encoding="utf-8") for p in sorted(root.rglob("*.md"))}
    try:
        for rel, text in files.items():
            import_file(root, rel, text, state)
        for rel, text in files.items():
            link_file(rel, text, state)
    finally:
        STATE_FILE.write_text(json.dumps(state, indent=2))

if __name__ == "__main__":
    main(Path(sys.argv[1]))
```

The script works in two passes. The first creates or updates each document. The second points links between files, like `[deploys](../runbooks/deploy.md)`, at the new documents in the app.

```text
playbook Runbooks
created  runbooks/deploy.md
created  runbooks/rollback.md
playbook Engineering
created  engineering/conventions/python.md
linked   runbooks/deploy.md
```

### Check the result

Open the playbooks in the app. New playbooks can be seen by everyone in the organization, so limit access on any that should be private. Documents arrive as drafts: read through them and publish them when they're right. `engineering/conventions/python.md` is in the **Conventions** folder of the **Engineering** playbook.

## What carries over

| From the file | Becomes |
| --- | --- |
| `title` in the front matter, or else the first `# Heading`, or else the file name | The title. The heading is taken out of the body, since the app shows the title above it. |
| `description` | The one-line summary shown in lists |
| `type`, if it's one of the [document types](https://developers.playbookops.ai/guides/documents#create-a-document) | `document_type`. Anything else becomes `general`. |
| The top-level folder | A playbook |
| Subfolders | Folders in the playbook, up to six levels deep. Deeper files go in the sixth. |
| `tags` | `tags`, up to 20 |
| Links to other `.md` files | Links to their documents in the app |
| Everything else | The body, as [Markdown](https://developers.playbookops.ai/guides/markdown) |

Images need public `https` links, and the script lists files whose images use local paths. Mermaid diagrams stay as code blocks; for a diagram people can edit, make a flowchart in the playbook and link to it.

## Running it again

`.playbookops-import.json` remembers each file's document, version and contents, and the playbooks and folders it made, so a second run only sends files that changed. If someone edited a document in the app since the last run, the script leaves it alone and prints `kept`, because its `base_version` no longer matches. That's the point at which PlaybookOps becomes the place to edit: change it there, not in the repo.

While both exist, you can run the import from CI on every push to the repo's main branch, with the key in a CI secret and `.playbookops-import.json` committed. When the team has moved over, replace the repo's README with a link to the playbooks, or turn it around and [mirror the playbooks into the repo](https://developers.playbookops.ai/cookbooks/sync-to-files).

## Next

- [Give coding agents your playbooks](https://developers.playbookops.ai/cookbooks/coding-agents) so they look things up instead of reading a docs folder.
- [Writing in Markdown](https://developers.playbookops.ai/guides/markdown) covers callouts, checklists, toggles and mentions, which most docs repos don't use yet.
