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
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
Run the import
Save this as
import_docs.pyand runpython import_docs.py path/to/docs. To put a folder into a playbook you already have, add it toPLAYBOOKS; 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
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.mdis 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 | 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 |
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
- Give coding agents your playbooks so they look things up instead of reading a docs folder.
- Writing in Markdown covers callouts, checklists, toggles and mentions, which most docs repos don't use yet.