Chapter C46 · Interactive Course
Files and Markdown without mystery
Read and edit the small text files agents work from.
Core Learning Concept
Repair the supplied project note without running its displayed commands. Follow the heading hierarchy, resolve each link from the note’s folder, and check that literal examples are fenced. Compare the source text with its preview. The exercise teaches how to read project files before an agent asks to change them.
What You’ll Learn in This Chapter
-
A file has a name and contents
Separate an extension from the bytes inside a file.
A file stores content under a name. The extension, such as .md or .json, suggests how software should interpret that content. Changing “notes.txt” to “notes.pdf” changes the name, not the underlying format. Converting a file requires a program to rewrite its contents into the intended format.
-
A path tells you where to look
Resolve a relative path from an explicit starting folder.
A path gives directions to a file. An absolute path starts from the storage root; a relative path begins from your current folder. Always identify the starting folder first before following any relative path.
-
Markdown is plain text with formatting marks
Recognize .md as a common Markdown extension.
Markdown is readable plain text with marks that a viewer interprets as formatting. For example, two asterisks around a word can display it in bold. The source and the preview are two views of the same content. Editing Markdown changes the text file, not a separate hidden document.
-
Headings and lists organize a note
Use hierarchy to make instructions readable.
Headings express a document’s structure. A single # introduces a top-level heading; ## introduces a section beneath it. Lists group related items or show steps. Use the hierarchy to tell readers what belongs together, rather than selecting heading levels only for their visual size.
-
Links point to other material
Distinguish link label from destination.
A Markdown link has a visible label and a destination: [guide](docs/guide.md). The label can say anything, so inspect where it leads. For a relative file link, begin from the containing document’s folder unless the host documents another rule. Moving the document can therefore break its links.
-
Code fences display literal examples
Recognize a displayed command as text until execution.
A code fence marks text to display literally using backticks. The displayed command has not run; executing it requires a separate shell action. Inspect example commands carefully before deciding whether, where, and how to run them.
-
Renderers support different extras
Distinguish core formatting from host extensions.
A renderer is the software that turns Markdown into a formatted view. Different renderers support different extensions, such as tables or footnotes. Literal formatting marks in a preview may indicate unsupported syntax. Check the destination renderer rather than assuming every editor and website interprets the file identically.
-
Repair a project note
Fix a note's heading hierarchy, relative link and code fence, then compare source with its rendered preview.