Markdown and MD files

Back to the Codex learning hub

Goal and preparation

Markdown is a plain-text formatting syntax, commonly saved with .md. Editors read and write the text; preview tools render its hashes, stars and brackets as structure. Renaming a Word document to .md does not convert it. Opening a preview also does not execute commands in code blocks. Distinguish source text from presentation before editing.

Step 1: create plain-text files

Open a new codex-md-lab folder in VS Code and create README.md and notes.md in Explorer. Keep exact names and capitalization on all OSes, avoiding README.md.txt. Other editors are fine if they save plain text as UTF-8; check the full filename if .txt is added automatically. Use a new folder rather than overwrite a production README.

Copy the complete sample into README.md and save. This website's outer code frame is a display container, not another wrapper to type. The triple backticks inside the sample are part of the file and must remain. Shared English sample text and filenames let all five language versions compare the same result.

# Small Steps notebook

## Purpose

Keep a short record of this practice project.

## Working steps

1. Read the request.
2. Make one focused change.
3. Verify the result.

- Keep original files.
- Record checks that have not run.

[Open task notes](./notes.md)

## Example command

```sh
node --version
```

> This command is an example, not a record of execution.

Save the next sample in notes.md at the same folder level. ./notes.md resolves relative to README's folder, and ./README.md points back from the notes. This creates a small index-and-article relationship without a database or website routing.

# Task notes

[Back to the notebook](./README.md)

## Accepted result

- **Completed** shows only finished tasks.
- `Read` is the sample task title.
- Empty titles must be rejected.

## Pending checks

The browser check has not run yet.

Step 2: understand six common forms

A hash followed by a space marks a main heading; two hashes mark the next level. Use one main title here and organize sections beneath it. Making every sentence a large heading loses structure. After renaming headings, check any links to them; generated heading anchors can vary by renderer.

Numbered lists suit steps; dash lists suit parallel conditions. Blank lines separate paragraphs in source and preview. Double stars emphasize Completed, and single backticks mark inline code such as Read. Formatting does not grant a word special authority in Codex. A > quote distinguishes a note or excerpt, not verified evidence.

Links put the visible label in brackets and the destination in parentheses. This example uses relative file paths; websites use complete HTTPS URLs. Your private C:\Users path is not a shareable destination for everyone, and a nonexistent notes.md is not a completed document. Labels can differ, but target names and case must be exact.

Fenced code has opening and closing backtick fences; sh labels the language for rendering. Keep node --version inside and the quote below outside. A missing closing fence can render the rest as code. Restore the delimiter rather than reinstalling anything. Preserve ASCII command characters and backticks instead of replacing them with ordinary quotes.

Show a Markdown fence as an example

Append the complete fragment below to notes.md and save. Its outer four backticks are file content too: they display the inner three-backtick fence literally. In the preview, the three-backtick opening with sh and the three-backtick closing should remain visible, followed by a paragraph outside the block. This nesting follows GitHub's documentation.

## Show the Markdown source

````markdown
```sh
node --version
```
````

This paragraph is outside the example.

If the final paragraph remains inside the block, check that the outer closing fence has four backticks; three cannot close a four-backtick opening. Fix only that ending and preview again. To undo this extension, remove the added section while keeping both original documents and their links.

Step 3: preview, follow links and test a failure

Open README.md in VS Code and run Markdown: Open Preview, or Ctrl+Shift+V on Windows/Linux and Command+Shift+V on macOS. Source and preview are two views of one file. Save first, then check the main title, steps, two conditions and code block.

Personal settings or extensions may remap shortcuts. If preview does not open, find Markdown: Open Preview in the Command Palette and inspect its local binding or run it directly. Do not guess from a different shortcut chart; platforms not personally used remain documented, not tested.

Follow Open task notes to the same-folder notes.md and return with Back to the notebook. If the tool opens an editor tab, open preview for that file. Matching titles alone are insufficient. Change README's destination to ./missing.md, save and try it to observe the missing target, then restore ./notes.md and verify both directions.

For another test, back up README.md, remove only the closing code fence, observe the quote becoming code, then restore the fence and compare the backup. Change one thing at a time rather than paths, headings and fences together. This small failure exercise also introduces debugging.

Step 4: ask Codex to read the documents

Open codex-md-lab in desktop, CLI or the IDE extension, verify the directory and send this request. Read and compare only; do not execute README's example command. A visible filename is not proof of reading. Ask for specific file attribution and pending checks.

Read README.md and notes.md in this practice folder. Explain the purpose, the accepted result, and the checks explicitly still pending. Identify each source file. Verify both relative file links point to existing files. Do not edit anything or execute the example command.

A passing answer identifies README's workflow and notes' Completed, Read and blank-title criteria, while preserving that the browser check has not run. If it claims the example command executed, request correction and evidence. Written commands and acceptance criteria are not execution records. Keep the reading result and your independent link checks.

Ordinary .md files and AGENTS.md

This exercise creates no AGENTS.md, so it does not establish automatic rule loading. Continue to AGENTS.md for scope and validation, or SKILL.md for skills. Markdown makes text readable; tool-specific discovery and use are separate rules. This also avoids treating someone else's project notes as your own instructions.

Finish with two real .md files, bidirectional links, correct code formatting, a repaired missing-link or fence failure, and an answer that distinguishes written criteria from unrun checks. Fonts and spacing may vary; structure, content and destinations should agree. VS Code preview/link behavior is documentation-checked. The original samples also receive compiler/copy checks for nested fences and unchanged code across languages.

Back to the Codex learning hub

Read the full description

Plain text to README.md to Preview

• AI tools
• Tutorials
• Codex