Éđîţ çöñţéñţ îñ àñý ƒöŕḿàţ, ƒàîţĥƒüļļý

Ĝöàļ: éđîţ ţĥé ţéẋţ îñšîđé à ƒîļé ŵîţĥöüţ ţöüçĥîñĝ îţš šţŕüçţüŕé (à Ŵöŕđ đöçüḿéñţ, à ĴŠÖÑ çàţàļöĝ, à Ḿàŕķđöŵñ ĝüîđé, öŕ àñý öţĥéŕ ƒöŕḿàţ ķàþî ŕéàđš). Ţĥé ŕéšüļţ îš ţĥé šàḿé ƒîļé (šàḿé ķéýš, šàḿé šţýļéš, šàḿé îñļîñé çöđéš) ŵîţĥ öñļý ţĥé þŕöšé çĥàñĝéđ. Ýöü (öŕ ýöüŕ àššîšţàñţ) đö ţĥé ŕéŵŕîţîñĝ; ķàþî þàŕšéš ţĥé ƒöŕḿàţ, éñƒöŕçéš à ƒàîţĥƒüļ ŕöüñđ-ţŕîþ, àñđ ŵŕîţéš ţĥé ŕéšüļţ ƃàçķ. ķàþî šéñđš ñö çöñţéñţ ţö à ḿöđéļ ƒöŕ ţĥé ŕéŵŕîţé, àñđ ýöü ñééđ ñö þŕöĵéçţ, þŕöṽîđéŕ öŕ çŕéđéñţîàļ.

▶

Walkthrough videoPending recording

À šĥöŕţ ŵàļķţĥŕöüĝĥ îñšþéçţîñĝ à ƒîļé'š ƃļöçķš, þŕéṽîéŵîñĝ àñ éđîţ àš à đ, àþþļýîñĝ îţ îñ þļàçé, àñđ ṽéŕîƒýîñĝ ţĥé ŕéšüļţ ŵîţĥ à çĥéçķ, šĥöŵîñĝ ĥöŵ öñļý ţĥé ļéàƒ ţéẋţ çĥàñĝéš ŵĥîļé ţĥé ƒöŕḿàţ ŕöüñđ-ţŕîþš.

View scene script ↗

Đéšķţöþ

1. Ŕéàđ ţĥé ƃļöçķš. Öþéñ ţĥé ƒîļé îñ ýöüŕ þŕöĵéçţ: Ƃļöçķš ļîšţš éàçĥ ţéẋţ ƃļöçķ àš ţĥé éñĝîñé ŕéàđš îţ; Þŕéṽîéŵ šĥöŵš ţĥé ŕéñđéŕéđ đöçüḿéñţ ŵîţĥ ţĥé šöüŕçé ↔ ţàŕĝéţ ţöĝĝļé.
2. Éđîţ à ƃļöçķ îñ þļàçé. Îñ Þŕéṽîéŵ, çļîçķ à ƃļöçķ àñđ çĥööšé Éđîţ. Ƒöŕḿàţţîñĝ àñđ þļàçéĥöļđéŕš šţàý àš çĥîþš ýöü ţýþé àŕöüñđ, àñđ šàṽîñĝ ŵŕîţéš ţĥé ƒîļé ţĥŕöüĝĥ îţš ƒöŕḿàţ, ļéàṽîñĝ éṽéŕý öţĥéŕ ƃýţé àš îţ ŵàš.
3. Éđîţ ţŕàñšļàţéđ ţéẋţ îñ Ŕéṽîéŵ. Ƒöŕ ţàŕĝéţ-ļàñĝüàĝé ƃļöçķš ýöü çàñ àļšö éđîţ îñ ţĥé Ŕéṽîéŵ ǫüéüé, ţĥéñ àþþŕöṽé; ţĥé ŵŕîţé ĝöéš ţĥŕöüĝĥ ţĥé šàḿé ŕöüñđ-ţŕîþ.
4. Ŕéŵŕîţé ḿàñý ƃļöçķš àţ öñçé ŵîţĥ apply. Đŕîṽé ţĥé îñšþéçţ → apply ļööþ ƒŕöḿ ţĥé ÇĻÎ ţàƃ öŕ à çöññéçţéđ àššîšţàñţ. Ţĥéñ ŕéöþéñ Þŕéṽîéŵ ţö šéé ţĥàţ ĥéàđîñĝš, šţýļéš àñđ îñļîñé çöđéš àŕé îñţàçţ, àñđ çļîçķ Ŕüñ öñ éṽéŕýţĥîñĝ öñ ţĥé þŕöĵéçţ'š Öṽéŕṽîéŵ ţö çöñƒîŕḿ ţĥé ĝàţé.

Àĝéñţ (Çļàüđé)

Ŵîţĥ ķàþî ŵîŕéđ àš àñ ḾÇÞ šéŕṽéŕ öŕ ţĥŕöüĝĥ ţĥé Àĝéñţ Šķîļļ, àšķ:

Šîḿþļîƒý ţĥé šéţüþ šéçţîöñ öƒ guide.md: šĥöŕţéŕ šéñţéñçéš, šàḿé ḿéàñîñĝ, ķééþ éṽéŕý ļîñķ.

Ţĥé àššîšţàñţ đŕîṽéš ţĥé ļööþ ţĥŕöüĝĥ šţŕüçţüŕéđ çàļļš: read_blocks ţö ŕéàđ ƃļöçķš, apply_edits ţö ŵŕîţé ţĥé çĥàñĝé šéţ ƃàçķ, check_file ţö çöñƒîŕḿ ţĥé ĝàţé. Ţĥé àššîšţàñţ îš ţĥé ŵŕîţéŕ; ķàþî éñƒöŕçéš ţĥé ŕöüñđ-ţŕîþ, ŕéƒüšéš àñ éđîţ ţö à ƃļöçķ ţĥàţ çĥàñĝéđ šîñçé ţĥé àššîšţàñţ ŕéàđ îţ, àñđ ŕéĵéçţš àñ éđîţ ţĥàţ ŵöüļđ çöŕŕüþţ îñļîñé ḿàŕķüþ. Ñö ḿöđéļ îš çàļļéđ ƒöŕ ţĥé ŵŕîţé îţšéļƒ.

ÇĻÎ

Ŕéàđ ţĥé ƃļöçķš. kapi inspect ŕéţüŕñš öñé ŕéçöŕđ þéŕ çöñţéñţ ƃļöçķ: îţš ŕéƒéŕéñçé (ref), ţĥé ŕéṽîšîöñ öƒ îţš ţéẋţ (rev), ţĥé text, ţĥé îñļîñé çöđéš îţ ĥöļđš, ţĥé öþéŕàţîöñš îţ àççéþţš, àñđ îţš šţŕüçţüŕàļ ŕöļé:

kapi inspect guide.md --jsonl        # one JSON object per line

{"ref":{"doc":"guide.md","block":"setup/p"},"rev":"r:5e10a2b3c4d5e6f7","text":"See the <x id=\"1\"/>dashboard<x id=\"/1\"/>.","codes":{"1":{"kind":"paired","type":"link:hyperlink","attrs":{"href":"/dashboard"}}},"ops":["set_content","replace_text"]}

Ţĥŕéé ƒîéļđš àñçĥöŕ àñ éđîţ. ref ñàḿéš ţĥé ƃļöçķ; çöþý îţ îñţö ţĥé éđîţ. rev îš ţĥé ŕéṽîšîöñ ýöü ŕéàđ; šéñđ îţ ƃàçķ àš if_match šö ķàþî çàñ ţéļļ ţĥé ƃļöçķ îš šţîļļ ŵĥàţ ýöü ŕéàđ. text ŕéñđéŕš îñļîñé çöđéš àš <x id="…"/> ţöķéñš; ķééþ éṽéŕý ţöķéñ îñ ýöüŕ éđîţéđ ţéẋţ (à þļàçéĥöļđéŕ îš <x id="1/"/>, à þàîŕéđ šþàñ öþéñš ŵîţĥ <x id="1"/> àñđ çļöšéš ŵîţĥ <x id="/1"/>). À çĥàŕàçţéŕ ŕéƒéŕéñçé ţĥé šöüŕçé šþéļļš öüţ, šüçĥ àš & îñ ĤŢḾĻ, šĥöŵš àš îţš çĥàŕàçţéŕ; ķééþ éàçĥ öñé ŵĥéŕé îţ îš, àñđ îţ ķééþš îţš šþéļļîñĝ. inspect ŕéàđš à ƒîļé ŵîţĥ ţĥé šàḿé ŕéàđéŕ apply ŵŕîţéš îţ ƃàçķ ţĥŕöüĝĥ, šö éṽéŕý ref àñđ rev îţ þŕîñţš îš öñé apply ŕéšöļṽéš.

Éṽéŕýţĥîñĝ éļšé îñ text îš ţéẋţ, àñđ ķàþî éñçöđéš îţ ƒöŕ ţĥé ƒîļé'š ƒöŕḿàţ: îñ ĤŢḾĻ à < öŕ & ýöü ţýþé îš ŵŕîţţéñ àš à çĥàŕàçţéŕ ŕéƒéŕéñçé. Ḿàŕķđöŵñ, ḾĐẊ àñđ ÀšçîîĐöç ķééþ šöḿé öƒ ţĥéîŕ öŵñ šýñţàẋ îñ text, šüçĥ àš à ƃàçķšļàšĥ éšçàþé, àñ ḾĐẊ {expression} öŕ àñ ÀšçîîĐöç +++ þàššţĥŕöüĝĥ. Šýñţàẋ ţĥé ƃļöçķ àļŕéàđý ĥöļđš šţàýš àš ýöü ķééþ îţ, àñđ šýñţàẋ ýöü àđđ (à ţàĝ, à ļîñķ, àñ éẋþŕéššîöñ, àñ import ļîñé, à ḿàçŕö) îš éšçàþéđ šö ţĥé þàĝé šĥöŵš ţĥé çĥàŕàçţéŕš ýöü ţýþéđ.

Éđîţ, ţĥéñ àþþļý. Ŵŕîţé à çĥàñĝé šéţ ŵîţĥ öñé öþéŕàţîöñ þéŕ çĥàñĝéđ ƃļöçķ: set_content ŵîţĥ ţĥé ñéŵ text, öŕ replace_text ţö çĥàñĝé ŵöŕđš îñšîđé îţ àñđ ķééþ éṽéŕýţĥîñĝ àŕöüñđ ţĥéḿ:

{"ops": [
  {"op": "set_content", "at": {"doc": "guide.md", "block": "setup/p"}, "if_match": "r:5e10a2b3c4d5e6f7",
   "text": "Open the <x id=\"1\"/>dashboard<x id=\"/1\"/>."},
  {"op": "replace_text", "at": {"doc": "guide.md", "block": "setup/p#2"}, "if_match": "r:0d71f30c75e4a087",
   "edits": [{"find": "utilize", "text": "use"}]}
]}

kapi inspect guide.md --jsonl > blocks.jsonl
# write the operations for the blocks you change (keeping every <x id="…"/>
# token) to edits.json (you do this; no command)
kapi apply edits.json --dry-run           # check it and print a diff per document, write nothing
kapi apply edits.json                     # apply in place
kapi apply edits.json --in-place=.bak     # apply, keeping a .bak

Ṽéŕîƒý. kapi check çöñƒîŕḿš ţĥé ŕéšüļţ ḿééţš ýöüŕ çöñţéñţ ŕüļéš: đéţéŕḿîñîšţîç, ŕéàđ-öñļý, éẋîţ 0 þàšš àñđ 3 öñ ĝàţé ƒàîļüŕé:

kapi check guide.md --max-chars 500 --forbid "utilize"

Ŵĥàţ ŕéƒüšéš àñ éđîţ

apply ŵŕîţéš à çĥàñĝé šéţ öñļý ŵĥéñ éṽéŕý öþéŕàţîöñ îñ îţ ĥöļđš. Ŵĥéñ öñé îš ŕéƒüšéđ, ñöţĥîñĝ îñ ţĥé çĥàñĝé šéţ îš ŵŕîţţéñ, ţĥé ŕéƒüšéđ öþéŕàţîöñ ñàḿéš ŵĥý, àñđ ţĥé öţĥéŕš ŕéþöŕţ not_applied:

• stale: ţĥé ƃļöçķ'š ŕéṽîšîöñ đéŕš ƒŕöḿ ţĥé if_match ýöü šéñţ; îţ çĥàñĝéđ šîñçé ýöü ŕéàđ îţ. Ţĥé ŕéšüļţ çàŕŕîéš ţĥé çüŕŕéñţ ŕéṽîšîöñ àñđ ţéẋţ ţö ŕéƃàšé öñ.
• guard: àñ éđîţéđ text ţĥàţ đŕöþš, îñṽéñţš, đüþļîçàţéš, öŕ üñƃàļàñçéš àñ <x id="…"/> ţöķéñ, öŕ ƒļàţ ţéẋţ îñ þļàçé öƒ à ƃļöçķ ĥöļđîñĝ à þļüŕàļ öŕ šéļéçţ. Éđîţ öñé ƃŕàñçĥ öƒ à þļüŕàļ ŵîţĥ ţĥé path ţĥàţ inspect ļîšţš üñđéŕ structures.
• not_found: ţĥé ŕéƒéŕéñçé ñàḿéš ñö đöçüḿéñţ öŕ ƃļöçķ, öŕ à find ḿàţçĥéš ñöţĥîñĝ; ţĥé ƃļöçķ ḿàý ĥàṽé ƃééñ ŕéḿöṽéđ öŕ ŕéñàḿéđ šîñçé ýöü ŕéàđ îţ.
• unsupported: ţĥé ƃļöçķ ţàķéš ñö éđîţ, šüçĥ àš à Ḿàŕķđöŵñ çöđé ƃļöçķ, ŵĥîçĥ inspect ļîšţš ŵîţĥ ñö ops.

À ŕéƒüšàļ éẋîţš ŵîţĥ çöđé 3, đîšţîñçţ ƒŕöḿ àñ öþéŕàţîöñàļ éŕŕöŕ: ŕéàđ ţĥé àƒƒéçţéđ ƃļöçķš àĝàîñ àñđ ŕéšéñđ ŵîţĥ ƒŕéšĥ ŕéṽîšîöñš. À çĥàñĝé šéţ ţĥàţ đöéš ñöţ đéçöđé éẋîţš 2 ƃéƒöŕé àñýţĥîñĝ îš ŕéàđ. Ŕéšéñđîñĝ à çĥàñĝé šéţ ţĥàţ ļàñđéđ ŵŕîţéš ñöţĥîñĝ: ţĥé ŕéṽîšîöñš îţ ñàḿéš ĥàṽé ḿöṽéđ, šö îţ îš ŕéƒüšéđ àš šţàļé ŵîţĥ éàçĥ ƃļöçķ'š çüŕŕéñţ ţéẋţ. Àñ öþéŕàţîöñ ŵĥöšé ŕéṽîšîöñ šţîļļ ĥöļđš àñđ ŵĥöšé ţéẋţ ţĥé ƃļöçķ àļŕéàđý ĥàš ŕéþöŕţš unchanged. Ţĥé šàḿé çĥàñĝé šéţ çàñ çàŕŕý à ţéŕḿ öŕ à çöñţéñţ ḿéḿöŕý þàîŕ (Çŕéàţé çöñţéñţ) öŕ à ŕéṽîéŵ đéçîšîöñ (Ţĥé ķàþî ļööþ), àþþļîéđ àƒţéŕ ţĥé çöñţéñţ; kapi apply --schema þŕîñţš éṽéŕý öþéŕàţîöñ.

Ŵĥàţ "ƒàîţĥƒüļļý" ḿéàñš

Öñļý ţĥé éẋţŕàçţéđ þŕöšé çĥàñĝéš; éṽéŕýţĥîñĝ öüţšîđé îţ (.docx çĥàŕàçţéŕ šţýļéš àñđ ţàƃļé ƃöŕđéŕš, ĴŠÖÑ ķéýš àñđ ñöñ-šţŕîñĝ ṽàļüéš, Ḿàŕķđöŵñ ĥéàđîñĝš àñđ ƒéñçéš) îš ŕéþŕöđüçéđ ƃýţé ƒöŕ ƃýţé. Šö ýöü çàñ éđîţ ƃîñàŕý öƒƒîçé ƒöŕḿàţš (.docx, .pptx) šàƒéļý; kapi formats ḿàŕķš šüçĥ ƒöŕḿàţš faithful îñ îţš Éđîţ çöļüḿñ.

Îñ à þŕöĵéçţ

Îñ à ķàþî þŕöĵéçţ, kapi inspect àñđ kapi check ŕüñ àĝàîñšţ ţĥé ŕéçîþé'š đéçļàŕéđ çöñţéñţ ŵîţĥ ñö ƒîļé àŕĝüḿéñţ. inspect ñàḿéš éàçĥ đöçüḿéñţ ƃý îţš þŕöĵéçţ-ŕéļàţîṽé þàţĥ àñđ ļîšţš éàçĥ ţŕàñšļàţîöñ àḿöñĝ à ƃļöçķ'š editions, àñđ kapi apply ŕéšöļṽéš ţĥöšé ŕéƒéŕéñçéš îñ ţĥé šàḿé þŕöĵéçţ.

Ñéẋţ

• Çĥéçķš: ŕüļé ƒàḿîļîéš, þŕöƒîļéš, šçöŕîñĝ, àñđ ţĥé ĝàţé éẋîţ çöđéš.
• Çŕéàţé çöñţéñţ: ţĥé àüţĥöŕ → þàŕšé → çĥéçķ ļööþ àñđ ţĥé ḿîẋéđ çĥàñĝé-šéţ.
• Ƒééđ çöñţéñţ ţö ýöüŕ ÀÎ: ţĥé šàḿé àñçĥöŕéđ ƃļöçķš àš àñ îñĝéšţîöñ šţŕéàḿ.