Project 1: The No-HJKL Navigator

Build a navigation drill workflow that reaches visible targets in 1-3 commands without arrow keys.

Quick Reference

Attribute Value
Difficulty Beginner
Time Estimate 4-8 hours
Main Programming Language Plain text
Alternative Programming Languages N/A
Coolness Level Level 1: Foundation
Business Potential Level 2: Productivity Multiplier
Prerequisites Basic terminal use, Open/save/quit in Vim, Normal vs Insert mode
Key Topics Motions and Text Units, Search and Find Motions, Modal Editing and the State Machine

1. Learning Objectives

By completing this project, you will:

  1. Execute the core workflow for The No-HJKL Navigator without Visual mode.
  2. Apply motion-based edits to achieve a measurable output.
  3. Explain the reasoning behind each key command you used.
  4. Validate results against a deterministic outcome.

2. All Theory Needed (Per-Concept Breakdown)

Fundamentals Modal editing means the same keys do different things depending on mode. In Vim, Normal mode is the default, Insert mode is for typing text, Visual mode is for selection, and Command-line mode is for Ex commands and searches. This design turns editing into a deliberate act: first you decide the action, then you execute it. Instead of constantly typing characters, you spend most time in Normal mode planning edits with small commands. This is why Esc is central: it is the exit door back to power. Understanding modes prevents accidental edits and reduces mental friction, because your hands can focus on intent rather than cursor micromanagement.

Another way to view modes is as a safety system: Normal mode protects the buffer from accidental input, Insert mode is for deliberate text, and Visual/Command-line are for scoped operations. Building the habit of returning to Normal after each change reduces errors and creates consistent command history for repeatability. This habit is more important than raw speed.

Deep Dive Think of Vim as a state machine with a small number of stable states and explicit transitions. Normal mode is the hub because it is where navigation, operators, and composition live. Insert mode is intentionally narrow: its job is to capture text, not to decide structure. Visual mode is a bridge for selection when a precise motion is difficult or when you want to see the selection. Command-line mode is a miniature language that applies batch operations. Replace mode is a specialized insert variant. The key insight is that Vim optimizes for editing intent, not for continuous typing. This architecture reduces the need to hold mental state about selections because selections can be reconstructed by motions. A modal editor also makes the keyboard a dense command surface: you do not need chords for common tasks because the same key can mean different commands in different modes. The cost is the learning curve and the requirement to explicitly manage state.

The state machine model explains common failures. If you accidentally insert when you meant to delete, you were in the wrong state. If a command does nothing, you are likely in the wrong mode. This is why Vim shows mode indicators and why :set showmode or a statusline is helpful. Practically, you should build a reflex: after any change, return to Normal mode unless you are actively typing. This supports repeatability and dot command usage, because the last change is captured cleanly when it starts and ends in Normal mode.

Modal editing also reshapes your editing strategy. Instead of “select then act,” Vim encourages “act on a motion.” That mental shift is the cornerstone of speed. If you are used to GUI editors, Visual mode will feel natural at first, but it is a crutch; over time, you should prefer operator + motion because it is more repeatable. This does not mean Visual mode is useless; it is a tool for irregular selections and for learning. The long-term goal is to reduce reliance on it. Modes also create a clean mental boundary for automation: macros and repeatability assume you start in Normal mode. A macro recorded from the wrong mode often fails on replay.

The state machine can be made explicit in your workflow. For example, when you need to make a change, you can silently say: “Normal mode, operator, motion, return.” When you need to enter data, you can say: “Insert mode, type, exit.” This is not just pedagogy; it mirrors how your hands should operate. The repeat key, search, and jump list all assume you return to Normal, and they become consistent when you do. Finally, modal editing is why Vim feels fast over a remote connection: the commands are short and the mode switches are deterministic. You send small commands rather than large selections, which reduces bandwidth and cognitive load.

Two practical details help during training: Ctrl-[ is an alternative to <Esc> and is useful on compact keyboards, and :set showmode or a statusline makes state visible. A common failure mode is recording a macro while still in Insert mode, which makes replays diverge. Always ensure you are in Normal mode before starting a macro or repeatable change to keep state transitions clean.

How this fit on projects Every project assumes you can intentionally switch modes, operate in Normal by default, and return to Normal after actions.

Definitions & key terms

  • Normal mode: command and navigation mode
  • Insert mode: text input mode
  • Visual mode: selection mode
  • Command-line mode: Ex and search input
  • Replace mode: overwrite characters while typing

Mental model diagram

Normal
  | i/a/o  -> Insert
  | v/V/Ctrl-v -> Visual
  | : / ? -> Command-line
  | R -> Replace
  | <Esc> from anywhere -> Normal

Vim modes map

How it works

  1. Vim starts in Normal mode.
  2. You enter a mode to express intent (insert, select, search, command-line).
  3. You perform a change or navigation.
  4. You return to Normal mode to plan the next change.

Minimal concrete example

iHello<Esc>
A world<Esc>
vj>

Common misconceptions

  • “Insert mode is the main mode.” (Normal is the default.)
  • “Visual selection is required to edit.” (Operators usually beat visual.)
  • “Esc is a waste of time.” (It is the reset button.)

Check-your-understanding questions

  1. What mode are you in after ci"?
  2. Which key returns to Normal from any mode?
  3. Why is Normal mode the default?

Check-your-understanding answers

  1. Insert mode (after the change).
  2. <Esc> (or Ctrl-[).
  3. Most commands and navigation occur there.

Real-world applications

  • Editing over SSH without a mouse
  • Refactoring code with repeatable edits
  • Navigating large logs in terminal sessions

Where you’ll apply it Projects 1-10.

References

  • Vim :help mode
  • Vim :help visual-mode
  • “Practical Vim” - Ch. 2-4

Key insights Normal mode is where you design edits; other modes are temporary tools.

Summary Modal editing converts editing into a small number of intentional states, making complex changes predictable and repeatable.

Homework/Exercises to practice the concept

  1. Switch between i, Esc, a, Esc, o, Esc for 2 minutes.
  2. Use Visual line and block modes to select and indent blocks.

Solutions to the homework/exercises

  1. Focus on returning to Normal immediately after each insert.
  2. V selects lines, Ctrl-v selects columns.

Motions and Text Units

Fundamentals Motions are the nouns of Vim. They define how Vim divides text into units: characters, words, WORDs, sentences, paragraphs, lines, and file boundaries. When you choose a motion, you are describing what kind of unit you care about. This is more powerful than counting characters because it scales across different file types and layouts. Motions are also composable with operators and counts, which means a single motion can drive navigation, deletion, selection, and formatting. Internalizing the difference between word and WORD, sentence and paragraph, line and screen line makes your movement precise.

Motions are also selections: any motion can be used after an operator to define the range. This means learning motions doubles as learning selection, so the same vocabulary controls navigation and editing.

Deep Dive Motions exist in multiple layers. At the smallest level are character motions (h, l, 0, $) and within-line motions like f, t, ;, and ,. These are surgical tools. Above that are word motions. Vim distinguishes between word (letters, digits, underscore, and configurable characters) and WORD (any non-blank sequence). This distinction matters because code often contains punctuation. For example, foo.bar is two words but one WORD. When you use w and W, you control whether punctuation is a separator or part of the token. This also interacts with the iskeyword option, which can redefine what Vim considers a word. Understanding this helps you tune behavior for different languages.

Next are sentence and paragraph motions () and }) which are not just text formatting concepts; they are semantic chunks. A paragraph is typically separated by a blank line or defined by a macro, which means it often aligns with logical blocks in prose, comments, or documentation. In code, paragraphs can correspond to logical sections or groups of statements. The motion keys for sentences and paragraphs let you move across these blocks without counting lines. Above that are screen-relative motions (H, M, L) and file-level motions (gg, G, %). Screen-relative motions help when the visible context matters more than the absolute line number; they are faster when you see the target but do not want to count lines. File-level motions are essential for jumping to file boundaries and structural markers.

Motions also include searches. /pattern and ?pattern are motion commands that move the cursor to the next or previous match. This is powerful because the search pattern can be as specific as you need, effectively creating a temporary motion for your current problem. You can combine search with operators to turn a search into a deletion or change, e.g., d/ or c?. This reduces the need for visual selection and opens the door to repeatable edits: search once, then repeat with n and .. Understanding that search is a motion is critical; it changes how you structure edits.

Another important layer is text-object-aware motions like % for matching pairs. % understands parentheses, brackets, and braces, which makes it ideal for code. This is a motion that depends on structure, not characters. Combined with operators, it becomes a structural editor. There are also jumps that create entries in the jump list, like searching, using G, or moving between files. These motions are navigation memory, not just movement. When you realize that motions define not just location but history, you will use them more carefully to create return points.

Motions have inclusive and exclusive behavior. For example, dw deletes up to the start of the next word, but de deletes through the end of the current word. This subtlety affects your results when combined with operators. The key is to pick the motion that matches your intent. When in doubt, choose the motion that aligns with your semantic unit rather than your visual estimate. Over time, your brain will pick the right motion automatically, which is where Vim speed appears.

Screen-line motions like gj and gk move by display lines when wrapping is enabled, which is useful in long prose. Similarly, ^ moves to the first non-blank character, which matters when indentation is significant. The more you align motions with structure (indent, punctuation, paragraphs), the less you need to count.

How this fit on projects Projects 1, 3, 4, 6, and 10 rely on word, sentence, paragraph, and search motions.

Definitions & key terms

  • word: letters/digits/underscore or defined by iskeyword
  • WORD: any non-blank sequence separated by whitespace
  • Sentence: ends with ., !, or ? followed by space or end-of-line
  • Paragraph: separated by blank lines or paragraph macros
  • Screen line: line as it appears on screen with wrapping

Mental model diagram

[chars] -> [word] -> [WORD] -> [sentence] -> [paragraph] -> [section]

Text unit hierarchy

How it works

  1. Decide which unit you want to move across.
  2. Choose the motion for that unit.
  3. Add a count if you want to scale the move.
  4. Combine with an operator if you want to act on it.

Minimal concrete example

w/W
b/B
e/E
{ }
gg/G

Common misconceptions

  • “WORD is just a bigger word.” (It treats punctuation as part of the WORD.)
  • “w always stops at punctuation.” (Depends on iskeyword.)
  • “Paragraphs only mean blank lines.” (Macros can define boundaries.)

Check-your-understanding questions

  1. What is the difference between w and W on foo.bar?
  2. Why does cw behave like ce sometimes?
  3. How do you jump to the start of a file?

Check-your-understanding answers

  1. w stops at punctuation; W treats foo.bar as one WORD.
  2. cw is special-cased to change to end of word.
  3. gg.

Real-world applications

  • Navigating tokens vs full strings in code
  • Skipping across sentences in Markdown
  • Jumping between sections in long files

Where you’ll apply it Projects 1, 3, 4, 6, 10.

References

  • Vim :help word-motions
  • Vim :help sentence
  • Vim :help paragraph
  • “Learning the vi and Vim Editors” - Ch. 3

Key insights Picking the right unit is faster than counting characters.

Summary Motions are semantic. Learn word vs WORD, sentence vs paragraph, and line vs screen.

Homework/Exercises to practice the concept

  1. In a code file, practice w vs W on identifiers with punctuation.
  2. Move by paragraphs using { and } in a Markdown file.

Solutions to the homework/exercises

  1. Use w to stop at _ or ., use W to jump whole tokens.
  2. { moves backward, } moves forward.

Search and Find Motions

Fundamentals Search is a motion. Find (f, t) is a precision tool on the current line. Together they allow you to jump to targets by pattern rather than by counting. Search motions (/, ?) move the cursor to the next match and can be combined with operators to delete, change, or yank through a match. Find motions (f, t, F, T) move to or just before a character on the current line and can be repeated with ; or ,. Mastering these motions removes the need for repeated j/k and makes edits scalable across large files.

Search is more efficient when you can see the matches. Options like hlsearch and incsearch provide immediate feedback, which reduces mistakes. Find motions are best for visible, single-line targets.

Deep Dive Search is the most flexible motion because the target can be defined by a pattern rather than a fixed distance. When you type /pattern, Vim searches forward; ?pattern searches backward. This motion becomes a selection when combined with an operator: d/pattern deletes up to the match, c?pattern changes text backward to the match. Unlike raw motions, search adapts to different file structures because the pattern is content-based. The n and N keys repeat the search in the same or opposite direction, creating a fast loop: search, change, repeat. This is essential for repeated edits across a file.

Find motions are line-scoped and quick. f jumps to a character; t jumps before it. This is perfect for editing delimited fields like CSV, function arguments, or log lines. The repeat keys ; and , allow you to move to the next or previous occurrence of the same character without retyping. These motions are also operator-friendly: dt, deletes up to the next comma, leaving the comma intact; df) deletes through the next closing parenthesis. The distinction between f and t matters because inclusive versus exclusive deletion determines whether delimiters remain.

Search patterns are regular expressions in Vim’s flavor. This means you can target complex structures, but it also introduces complexity. For example, you can use \v (very magic) to reduce escaping, or \c for case-insensitive matches. The key is to choose the simplest pattern that uniquely identifies the target. Overly complex patterns are slow and hard to debug. The hlsearch and incsearch options make search more visible and interactive, which improves accuracy and confidence. In projects, you should use these options to see your matches before you act on them.

Search is also a navigation tool for larger structures. You can search for function names, error codes, or log prefixes. Combined with the jump list, search becomes a navigation memory: you can use Ctrl-O to return to previous positions. This means search is not just about reaching the next target, it is also about creating return points. In a workflow, you can search to jump, perform an edit, then jump back. This reduces the cognitive load of “where was I?”

Find motions are best when the target is visible and the line is short. Search is best when the target is repeated or located beyond the current line. Knowing when to use each is part of Vim mastery. A good rule: if the target is on the current line and visible, use f or t. If the target is elsewhere, use / or ?. Both motions are more powerful when combined with operators and the dot command. If your edit is repeatable, the combination of search + change + n + . becomes a fast pipeline for repetitive tasks.

The * and # commands search for the word under the cursor forward and backward, which is faster than typing the pattern. g* and g# do the same but allow partial matches. Search behavior is also controlled by ignorecase and smartcase, which let lowercase patterns be case-insensitive while uppercase patterns stay case-sensitive. These settings make search predictable across code and prose and are worth enabling in a motion-focused setup.

How this fit on projects Projects 1, 3, 5, and 10 rely on search and find to target edits precisely.

Definitions & key terms

  • Search (/, ?): forward or backward pattern search
  • Find (f, t, F, T): find a character on the current line
  • Repeat search (n, N): move to next/previous match
  • Repeat find (;, ,): move to next/previous find target

Mental model diagram

Search = anywhere in file
Find   = on this line

How it works

  1. Choose search or find based on scope.
  2. Execute the motion (/pattern, f,).
  3. Repeat with n or ;.
  4. Combine with operators for changes.

Minimal concrete example

/Timeout<Enter>
ndt,
f)

Common misconceptions

  • “Search is only for navigation.” (It is also a motion for edits.)
  • “t equals f.” (t stops before the character.)
  • “You must retype the search.” (n repeats it.)

Check-your-understanding questions

  1. What does dt) do?
  2. What does ; repeat?
  3. How do you search backward for a word?

Check-your-understanding answers

  1. Deletes until ) but not including it.
  2. The last f/t search.
  3. ?word.

Real-world applications

  • Editing CSV fields or log entries
  • Jumping between error lines
  • Repeating edits across matching patterns

Where you’ll apply it Projects 1, 3, 5, 10.

References

  • Vim :help search
  • Vim :help f
  • “Learning the vi and Vim Editors” - Ch. 3

Key insights Search is a motion, not just a navigation tool.

Summary Search and find are the fastest ways to target text without counting.

Homework/Exercises to practice the concept

  1. Use dt, to delete until commas in a CSV line.
  2. Use /TODO then n + . to fix multiple TODOs.

Solutions to the homework/exercises

  1. dt, deletes up to the comma.
  2. /TODO, edit once, then n. repeatedly.

3. Project Specification

3.1 What You Will Build

A repeatable navigation drill file and a checklist of target-finding strategies (find, search, screen-relative motions).

Included:

  • Large practice file
  • Target list with coordinates
  • Keystroke count worksheet

Excluded:

  • Plugins
  • GUI navigation

3.2 Functional Requirements

  1. Core workflow: Open the drill file and reach 20 specified targets using motions and search
  2. Repeatability: Record keystroke counts for each target and reduce them over time
  3. Validation: Use both search and find motions intentionally based on target position

3.3 Non-Functional Requirements

  • Performance: Targets should be reached in 1-3 commands after practice.
  • Reliability: Edits should not modify the drill file content.
  • Usability: Checklist and target markers are clear and repeatable.

3.4 Example Usage / Output

Use `/pattern`, `f;`, `H/M/L`, and `gg/G` to reach marked targets and log the keystroke counts.

3.5 Data Formats / Schemas / Protocols

  • Drill file lines: [timestamp] [level] [message]
  • Target list: line number + target token

3.6 Edge Cases

  • Duplicate targets on a line
  • Wrapped lines
  • Very long lines

3.7 Real World Outcome

This is the deterministic output you can compare against directly.

3.7.1 How to Run (Copy/Paste)

  • vim navigation_practice.txt

3.7.2 Golden Path Demo (Deterministic)

Reach 10 targets in under 3 commands each, no arrow keys, then repeat with lower keystroke counts.

3.7.3 If CLI: provide an exact terminal transcript

$ vim navigation_practice.txt
# Use /Timeout<Enter> then f; to land on the semicolon
# Verify cursor position with | marker in notes

4. Solution Architecture

4.1 High-Level Design

Input file -> Vim workflow plan -> Verification checklist

4.2 Key Components

Component Responsibility Key Decisions
Input File Provides deterministic data Keep it stable and versioned
Vim Workflow Plan Documents motions and operators Prefer repeatable sequences
Verification Checklist Confirms correctness Use before/after snapshots

4.4 Data Structures (No Full Code)

  • Entry: a structured line or block with fields relevant to the task
  • Target: the specific token or structure you will move to or edit
  • Checklist: steps to verify the output

4.4 Algorithm Overview

Key Algorithm: Motion-First Editing Loop

  1. Identify the target structure (word, field, block, or line).
  2. Choose a motion or text object that selects it safely.
  3. Apply the operator or edit and verify the result.

Complexity Analysis:

  • Time: O(n) over lines edited
  • Space: O(1) additional space

5. Implementation Guide

5.1 Development Environment Setup

vim --version
vimtutor

5.2 Project Structure

project-root/
|-- input/
|   `-- sample.txt
|-- notes/
|   `-- keystrokes.md
`-- outputs/
    `-- expected.txt

5.3 The Core Question You’re Answering

“Build a navigation drill workflow that reaches visible targets in 1-3 commands without arrow keys.”

5.4 Concepts You Must Understand First

Stop and research these before editing:

  • Basic terminal use
  • Open/save/quit in Vim
  • Normal vs Insert mode

5.5 Questions to Guide Your Design

  1. Which motion or text object targets the structure directly?
  2. Can the change be repeated with dot or a macro?
  3. How will you verify correctness after the change?

5.6 Thinking Exercise

Before editing, sketch the steps needed to complete the task on paper.

5.7 The Interview Questions They’ll Ask

  1. “Which motion did you choose and why?”
  2. “How did you ensure the edit was repeatable?”
  3. “What is the risk of using Visual mode here?”
  4. “How did you validate the output?”

5.8 Hints in Layers

Hint 1: Start with a stable cursor position Use 0, ^, or a search to align before editing.

Hint 2: Choose the smallest safe unit If a word is enough, use a word object; if not, use a larger object.

Hint 3: Make it repeatable Design the first change so . works on the next target.

Hint 4: Validate Check before/after snapshots after each batch of edits.

5.9 Books That Will Help

Topic Book Chapter
Core workflow “Practical Vim” Ch. 1-4
Motions “Practical Vim” Ch. 8
Editing language “Learning the vi and Vim Editors” Ch. 3

5.10 Implementation Phases

Phase 1: Foundation (4-8 hours)

Goals:

  • Load the input file and identify targets
  • Verify core motions and search behavior

Tasks:

  1. Create a short checklist of target patterns
  2. Practice on 3-5 lines

Checkpoint: You can complete the smallest edit without mistakes.

Phase 2: Core Functionality (4-8 hours)

Goals:

  • Execute the main workflow end-to-end
  • Keep edits repeatable

Tasks:

  1. Apply the main edit sequence to the full file
  2. Record keystrokes or a macro if needed

Checkpoint: Output matches the golden path demo.

Phase 3: Polish & Edge Cases (4-8 hours)

Goals:

  • Handle edge cases
  • Document the workflow

Tasks:

  1. Test edge cases from section 3.6
  2. Write a short summary of decisions

Checkpoint: Edge cases are handled or documented.

5.11 Key Implementation Decisions

Decision Options Recommendation Rationale
Targeting strategy Search vs find vs motion Choose the most stable Stability beats speed early on
Repeatability Dot vs macro Use dot first Lower complexity
Verification Visual check vs checklist Use a checklist Prevents silent errors

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Manual Checks Validate edits Before/after snapshots
Repeatability Tests Ensure dot/macro works Run on 3+ targets
Edge Case Tests Handle boundary conditions Missing fields or empty lines

6.2 Critical Test Cases

  1. Nominal case: Apply the workflow to a standard line.
  2. Duplicate target: Handle two targets on the same line.
  3. Irregular line: Verify behavior when a field is missing.

6.3 Test Data

Use the provided sample input file and create 3 additional lines with variations.

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
Over-using Visual mode Changes are hard to repeat Use operator + motion
Wrong motion choice Target missed Use a larger text object
No validation step Silent errors Use a checklist

7.2 Debugging Strategies

  • Replay slowly: Step through the workflow one command at a time.
  • Use undo: Roll back and re-apply with a clearer motion.

7.3 Performance Traps

Overusing j/k on large files instead of search can make the workflow slow.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Repeat the workflow on a smaller file
  • Document the exact keystroke sequence

8.2 Intermediate Extensions

  • Apply the workflow to a real project file
  • Reduce keystroke count by 20%

8.3 Advanced Extensions

  • Build a macro to automate the workflow
  • Create a custom mapping to speed up a frequent step

9. Real-World Connections

9.1 Industry Applications

  • Remote server editing: Vim is common on production systems
  • Incident response: quick log edits without GUI tools
  • Vim: core editor reference
  • Neovim: modernized modal editor
  • Universal Ctags: tag generation tool

9.3 Interview Relevance

  • Motion grammar questions
  • Repeatability and macro questions
  • Command-line editing scenarios

10. Resources

10.1 Essential Reading

  • “Practical Vim” by Drew Neil - focus on motion and change workflows
  • “Learning the vi and Vim Editors” - foundational navigation

10.2 Video Resources

  • “Vim as a Language” talk (searchable title)
  • “Practical Vim” author talks (searchable title)