Project 4: The Markdown Re-Sequencer (Line Operations)

Restructure a Markdown outline using linewise operators and Ex commands without copy/paste.

Quick Reference

Attribute	Value
Difficulty	Level 1: Beginner
Time Estimate	4-8 hours
Main Programming Language	Markdown
Alternative Programming Languages	Plain text
Coolness Level	Level 1: Workflow builder
Business Potential	2: Docs speedup
Prerequisites	Basic Vim motions and Normal mode
Key Topics	Linewise ops, Ex commands, formatting

---

1. Learning Objectives

By completing this project, you will:

1. Reorder list items and sections using linewise operators.
2. Move and copy lines with Ex commands (:m, :t).
3. Reflow paragraphs using gq and textwidth.
4. Reduce dependence on visual selection for structural edits.
5. Build a repeatable workflow for doc editing.

---

2. All Theory Needed (Per-Concept Breakdown)

2.1 Linewise Operators and Registers

Fundamentals

Linewise operators act on full lines rather than character ranges. dd deletes the current line, yy yanks it, and p or P pastes it. This is perfect for Markdown because headings and list items are line-structured. When you use linewise operations, you avoid partial edits that can break list indentation.

Registers matter because deletes and yanks overwrite the default register. If you need to reuse a line repeatedly, store it in a named register ("a), then paste it multiple times without losing it. This allows you to duplicate headings or list items safely.

Deep Dive into the concept

Linewise behavior is triggered in two ways: using linewise operators directly (dd, yy) or doubling an operator (cc, dd, >>). This matters when you are working with Markdown because a single line often represents a semantic unit (a heading or a list item). By staying linewise, you preserve the structural intent of the document.

Register management becomes important when you are reorganizing sections. If you yank a section into a named register and then delete other lines, the named register remains intact. This lets you move content without losing it. The deeper skill is knowing when to use the unnamed register versus a named register to avoid surprises.

How this fits on projects

• You will use dd, yy, and p to reorder list items.
• You will store reusable snippets in named registers.

Definitions & key terms

• Linewise operator: An operator that acts on whole lines.
• Register: A storage slot for yanked or deleted text.
• Unnamed register: The default register that is overwritten often.

Mental model diagram (ASCII)

Line -> dd (cut) -> register -> p (paste)

How it works (step-by-step)

1. Yank or delete the line (yy or dd).
2. Move to the destination line.
3. Paste with p (after) or P (before).
4. Repeat as needed.

Minimal concrete example

dd     " delete line
P      " paste before current line
"ayy  " yank line into register a
"ap   " paste from register a

Common misconceptions

• “Linewise operations are crude”: They are ideal for structured text.
• “Registers are only for macros”: They are essential for safe copy/paste.
• “p and P are the same”: One pastes after, the other before.

Check-your-understanding questions

1. What does yy do?
2. How do you paste a line above the current line?
3. Why use a named register?

Check-your-understanding answers

1. It yanks the current line.
2. Use P.
3. To preserve content across other deletes/yanks.

Real-world applications

• Reordering bullet lists in release notes.
• Moving sections in Markdown docs.
• Copying recurring snippets (like headers).

Where you’ll apply it

• See Section 3.2 Functional Requirements and Section 5.10 Implementation Phases in this project.
• Also used in: Project 6: HTML Tag Wrapper.

References

• :help dd
• “Learning the vi and Vim Editors” Ch. 2

Key insights

Linewise edits match the structure of Markdown.

Summary

When text is structured by lines, linewise operators are the safest and fastest approach.

Homework/Exercises to practice the concept

1. Move the third bullet to the top using dd and P.
2. Yank a heading into register a and paste it twice.

Solutions to the homework/exercises

1. dd, move to top, P.
2. "ayy then "ap twice.

---

2.2 Ex Commands: Move, Copy, and Sort

Fundamentals

Ex commands provide line-level control without visual selection. :m moves a line or range, :t copies it, and :sort orders lines alphabetically. These commands operate on explicit line numbers or ranges, which makes them precise and repeatable. In Markdown, you can use them to reorder lists or move sections without messing up indentation.

Deep Dive into the concept

Ex commands work with ranges like :2,5m10 (move lines 2-5 after line 10). This is more precise than manual cut and paste. You can also use marks or search patterns to define ranges. This is powerful for docs because you can treat a section as a block and move it in one command.

Sorting is useful for alphabetizing lists or headings. Combined with visual mode or line ranges, :sort can quickly normalize unordered lists. The deeper insight is that Ex commands are programmable, and your editing becomes scriptable even within Vim.

How this fits on projects

• You will use :m and :t to reorder sections.
• You will use :sort to alphabetize lists if needed.

Definitions & key terms

• Ex command: A command entered with : that operates on line ranges.
• Range: A set of lines specified by numbers, marks, or patterns.
• Move (:m): Relocates lines to a target position.

Mental model diagram (ASCII)

Lines 2-4 --:m 10--> after line 10

How it works (step-by-step)

1. Identify the range to move or copy.
2. Use :m or :t with a target line number.
3. Verify indentation and spacing.
4. Use :sort if list order matters.

Minimal concrete example

:2m1    " move line 2 below line 1
:3,5t8  " copy lines 3-5 after line 8
:sort   " sort selected lines

Common misconceptions

• “Ex commands are outdated”: They are precise and fast.
• “You must count lines manually”: Relative numbers and marks help.
• “Sort always works”: You need the correct range.

Check-your-understanding questions

1. What does :m do?
2. How do you copy a line without deleting it?
3. How do you sort only selected lines?

Check-your-understanding answers

1. Moves the specified line or range.
2. Use :t or y + p.
3. Select lines visually then run :sort.

Real-world applications

• Reordering changelog entries.
• Organizing Markdown headings.
• Sorting lists alphabetically.

Where you’ll apply it

• See Section 3.4 Example Usage / Output and Section 5.8 Hints in Layers in this project.
• Also used in: Project 10: Search-Replace Master.

References

• :help :move
• :help :copy

Key insights

Ex commands give you deterministic, script-like control over lines.

Summary

Line moves and copies are safer and faster when you can specify ranges directly. Ex commands turn text editing into repeatable operations.

Homework/Exercises to practice the concept

1. Move line 5 above line 2 using :m.
2. Copy a heading to another section using :t.

Solutions to the homework/exercises

1. :5m1 moves line 5 after line 1 (above line 2).
2. :t with the appropriate line numbers.

---

2.3 Formatting with gq and Textwidth

Fundamentals

Markdown paragraphs often need reflowing to keep line lengths readable. Vim’s gq operator formats text based on textwidth and formatting settings. gqap formats the current paragraph, while gqq formats a single line. This is more reliable than manual line breaks.

Deep Dive into the concept

gq uses format options that depend on filetype. In Markdown, it respects comment leaders and blank lines as paragraph boundaries. Setting textwidth (for example, set textwidth=80) makes the formatting deterministic. The deeper skill is to treat gq as a formatting operator you can combine with motions (gqip for inner paragraph) and repeat with ..

How this fits on projects

• You will format long Markdown paragraphs with gqap.
• You will set textwidth for consistent wrapping.

Definitions & key terms

• gq: Format operator that reflows text.
• textwidth: Maximum line length used by formatting.
• Paragraph: In Vim, text separated by blank lines.

Mental model diagram (ASCII)

Long line -> gqap -> wrapped at textwidth

How it works (step-by-step)

1. Set textwidth (e.g., 80).
2. Place cursor in paragraph.
3. Run gqap to reflow.
4. Repeat with . for other paragraphs.

Minimal concrete example

:set textwidth=72
:gqap

Common misconceptions

• “gq is for code”: It is ideal for prose and Markdown.
• “Line breaks are manual”: gq handles them automatically.
• “textwidth is optional”: Without it, formatting is inconsistent.

Check-your-understanding questions

1. What does gqap do?
2. Why set textwidth?
3. How do you format a single line?

Check-your-understanding answers

1. It formats the current paragraph.
2. It defines the target line width.
3. Use gqq or gq..

Real-world applications

• Wrapping release notes.
• Cleaning up README files.
• Formatting long bullet points.

Where you’ll apply it

• See Section 3.4 Example Usage / Output and Section 5.10 Implementation Phases in this project.
• Also used in: Project 1: No-HJKL Navigator.

References

• :help gq
• :help textwidth

Key insights

Formatting is an operator, not a manual process.

Summary

gq makes Markdown cleanup reliable. With textwidth set, formatting becomes a one-command operation.

Homework/Exercises to practice the concept

1. Set textwidth=72 and reflow a paragraph.
2. Format three paragraphs using gqap and ..

Solutions to the homework/exercises

1. :set textwidth=72, then gqap.
2. Use gqap once, then j . for the next paragraphs.

---

3. Project Specification

3.1 What You Will Build

You will take a messy Markdown outline and reorder it into a clean, structured document using linewise operators, Ex commands, and formatting operations. The deliverable is a before/after file plus a short command log.

3.2 Functional Requirements

1. Input File: Create release_notes.md with at least 30 lines.
2. Reorder List: Move at least 5 list items into correct order.
3. Duplicate Sections: Copy at least one heading using :t or registers.
4. Format Paragraphs: Reflow at least two long paragraphs with gq.
5. Command Log: Record the commands used for each transformation.

3.3 Non-Functional Requirements

• Readability: Output is clearly structured and readable.
• Repeatability: Commands are deterministic and documented.
• Minimal Visual Mode: Use linewise commands whenever possible.

3.4 Example Usage / Output

Before:
- Added feature B
- Added feature A

Commands:
:2m1

After:
- Added feature A
- Added feature B

3.5 Data Formats / Schemas / Protocols

Markdown file with headings and lists. Example structure:

# Release Notes

## Added
- Feature B
- Feature A

## Fixed
- Bug C

3.6 Edge Cases

• Moving a list item across section boundaries.
• Reflowing a paragraph that contains inline code.
• Sorting list items with mixed case.

3.7 Real World Outcome

You will have a clean, reordered Markdown file that reads correctly and is formatted consistently.

3.7.1 How to Run (Copy/Paste)

vim release_notes.md

3.7.2 Golden Path Demo (Deterministic)

1. Move line 3 above line 2: :3m1.
2. Format paragraph: gqap.

Expected output:

- Added feature A
- Added feature B

3.7.3 Failure Demo (Deterministic)

If you visually select the wrong range, you may move partial lines and break list indentation.

3.7.4 If CLI

Not applicable.

3.7.5 If Web App

Not applicable.

3.7.6 If API

Not applicable.

3.7.7 If Library

Not applicable.

3.7.8 If TUI

+----------------------------------+
| release_notes.md                 |
| ## Added                         |
| - Added feature B                |
| - Added feature A                |
|                                  |
| -- NORMAL --                     |
+----------------------------------+

Key interactions:

• dd / p for moving lines
• :m / :t for precise moves and copies
• gqap for reflow

---

4. Solution Architecture

4.1 High-Level Design

+------------------+    +-------------------+    +--------------------+
| Markdown Draft   | -> | Linewise Editing  | -> | Final Outline       |
+------------------+    +-------------------+    +--------------------+

4.2 Key Components

Component	Responsibility	Key Decisions
Markdown file	Provide messy outline	Include unordered lists
Command log	Document edits	Keep per-change notes
Formatting settings	Define wrap width	Set textwidth to 72 or 80

4.3 Data Structures (No Full Code)

EditStep:
- line_range
- command
- expected_result

4.4 Algorithm Overview

Key Algorithm: Reorder and Reflow

1. Identify the lines to move.
2. Move with :m or dd/p.
3. Reflow paragraphs with gq.

Complexity Analysis:

• Time: O(k) keystrokes per move
• Space: O(1)

---

5. Implementation Guide

5.1 Development Environment Setup

vim --version

5.2 Project Structure

markdown-resequencer/
|-- release_notes.md
|-- release_notes_after.md
`-- command_log.md

5.3 The Core Question You’re Answering

“How do I restructure text without copy/paste?”

5.4 Concepts You Must Understand First

1. Linewise operators (dd, yy, p)
2. Ex move/copy (:m, :t)
3. Formatting with gq

5.5 Questions to Guide Your Design

1. Is this edit best done with linewise commands or Ex commands?
2. Do I need to preserve indentation?
3. Should I reflow this paragraph after moving it?

5.6 Thinking Exercise

Move the third list item to the top using one Ex command.

5.7 The Interview Questions They’ll Ask

1. “What does :m do?”
2. “How do you reflow a paragraph?”
3. “What is the difference between p and P?”

5.8 Hints in Layers

Hint 1: Use linewise moves dd then p.

Hint 2: Use Ex for precision :3m1 moves line 3 below line 1.

Hint 3: Format with gq gqap reflows paragraphs.

Hint 4: Repeat Use . to repeat formatting.

5.9 Books That Will Help

Topic	Book	Chapter
Line ops	“Learning the vi and Vim Editors”	Ch. 2
Ex commands	“Practical Vim”	Ch. 5

5.10 Implementation Phases

Phase 1: Draft Setup (1-2 hours)

Goals:

• Create a messy outline.

Tasks:

1. Write a Markdown file with unordered lists out of order.
2. Add a long paragraph that needs reflow.

Checkpoint: File contains at least 30 lines.

Phase 2: Reordering (2-3 hours)

Goals:

• Move list items and sections.

Tasks:

1. Reorder at least 5 list items.
2. Copy a heading using :t.

Checkpoint: List order matches the intended order.

Phase 3: Reflow and Polish (1-2 hours)

Goals:

• Format paragraphs for readability.

Tasks:

1. Set textwidth=72.
2. Reflow two paragraphs using gqap.

Checkpoint: Paragraphs wrap cleanly.

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Move method	dd/p vs :m	:m for precision	Avoids mis-paste
Wrap width	72 / 80 / 100	80	Standard readability
Sorting	Manual / :sort	Use :sort when needed	Fast and consistent

---

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Structure	Verify order	Read outline top-to-bottom
Formatting	Verify wrap	Check line length
Repeatability	Confirm commands	Reproduce with log

6.2 Critical Test Cases

1. Move a list item across sections.
2. Reflow a paragraph with inline code.
3. Duplicate a heading without breaking list structure.

6.3 Test Data

- Added feature B
- Added feature A

---

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall	Symptom	Solution
Wrong line moved	List order wrong	Use :set rnu and :m
Broken indentation	List renders incorrectly	Use linewise ops, not charwise
Paragraph not formatted	Lines still long	Ensure cursor in paragraph before gqap

7.2 Debugging Strategies

• Use :set list to visualize whitespace.
• Undo and retry with linewise moves.

7.3 Performance Traps

• Overusing visual mode for line moves.
• Manually rewrapping paragraphs.

---

8. Extensions & Challenges

8.1 Beginner Extensions

• Reorder headings using :m only.
• Use dd/p to rearrange bullet items.

8.2 Intermediate Extensions

• Sort a list alphabetically using :sort.
• Reflow multiple paragraphs with ..

8.3 Advanced Extensions

• Use global commands to reorder sections by pattern.
• Create a macro that moves and formats a section.

---

9. Real-World Connections

9.1 Industry Applications

• Editing release notes quickly before publishing.
• Reordering documentation sections in large docs.

9.2 Related Open Source Projects

• Markdown-heavy repos (docs sites, READMEs).
• Vim itself for doc maintenance.

9.3 Interview Relevance

• Shows ability to manipulate structured text efficiently.

---

10. Resources

10.1 Essential Reading

• “Learning the vi and Vim Editors” Ch. 2
• “Practical Vim” Ch. 5

10.2 Video Resources

• Vim linewise operations tutorials

10.3 Tools & Documentation

• :help :move
• :help gq

10.4 Related Projects in This Series

• Project 1: No-HJKL Navigator
• Project 10: Search-Replace Master

---

11. Self-Assessment Checklist

11.1 Understanding

• I can explain the difference between p and P.
• I can use :m and :t confidently.
• I can explain what gqap does.

11.2 Implementation

• Markdown file reordered correctly.
• Paragraphs reflowed to target width.
• Command log is complete.

11.3 Growth

• I can apply the same workflow to another doc file.
• I can teach linewise operations to someone else.

---

12. Submission / Completion Criteria

Minimum Viable Completion:

• Reordered 5 list items without visual mode.
• Reformatted two paragraphs with gq.
• Logged the commands used.

Full Completion:

• All minimum criteria plus:
• Used :m or :t for at least three moves.
• Applied . to repeat formatting.

Excellence (Going Above & Beyond):

• Reorganized a real README or changelog.
• Produced a clean, publish-ready Markdown doc.