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.

  1. 1

    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.

    export PLAYBOOKOPS_API_KEY="pbo_live_…"
    pip install httpx pyyaml
    
  2. 2

    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.

    """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.

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

    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 fileBecomes
title in the front matter, or else the first # Heading, or else the file nameThe title. The heading is taken out of the body, since the app shows the title above it.
descriptionThe one-line summary shown in lists
type, if it's one of the document typesdocument_type. Anything else becomes general.
The top-level folderA playbook
SubfoldersFolders in the playbook, up to six levels deep. Deeper files go in the sixth.
tagstags, up to 20
Links to other .md filesLinks to their documents in the app
Everything elseThe body, as 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.

Next