How to show indentation guides on Mac
You can do this with Note My, and here is where the toggle lives, what each of the ten guide styles looks like, and which one to reach for.
You are eight levels deep in a config file, or in a function whose closing braces all landed in the same column, and you cannot tell by eye which block a line belongs to. Vertical indentation guides fix that: one faint line per level, down the left of the block. Here is how to turn them on in Note My, how to choose between the ten styles, and why your file itself stays exactly as you wrote it.
Indentation guides are on by default. If you have never touched the setting, the file in front of you already has them, drawn in the default Dots style.
What indentation guides are for
Guides are a reading aid, not a formatting tool. They mark each level of indentation so a deep block stays readable, and they sit purely in the view. Nothing is written into your document, not one character is added, and turning them on or off never marks a file as changed. It all happens on your Mac: no upload, no account, and the file never leaves the machine.
That is worth separating from the two neighbouring features, because they are often confused:
- Guides draw vertical markers at each indent level. Display only.
- Show Invisibles draws the whitespace characters themselves —
·for a space,→for a tab, and line-ending labels. Four independent toggles, all off by default. Also display only. - Indent, the toolbar button beside Guides, opens the Indentation sheet and rewrites the actual indentation of your file when you press Apply. That one does change the document.
Turn the guides on
-
Click Guides in the toolbar
The toolbar is icon-only. Guides is the indented-list glyph, sitting between Indent and Smart Edit near the right-hand end of the bar. Hover it and the tooltip reports the current state — "Indentation guides: OFF — click to show" when they are off.
When guides are on the button latches into a solid accent disc with a white glyph rather than a bordered rectangle, so a glance at the bar tells you the current state without opening anything.
-
Or use the Guides pane in Settings
Press ⌘, and choose Guides in the sidebar. It is one of fourteen panes, grouped with Ruler and Invisibles. The pane has its own enable switch and the style picker.
The toolbar button and the Settings switch control the same thing, so there is never a second state to keep in step — flip either one and the other follows immediately, including the toolbar glyph. Use whichever is closer to hand.
-
Pick a style
The picker in Settings ▸ Guides offers ten tiles. Each tile shows the style at full size, so you can compare all ten without closing the pane. What you see on the tile is what you get in the document, at the same weight and the same colour. Leave the pane open and click through a few — the change lands in the file behind it as you pick.
Keep the Guides button where you can see it. It sits in the toolbar with its state on show, so one click flips the guides on or off while you are reading, and Settings ▸ Guides is there when you want the style picker as well.
The ten styles
Every style marks the same levels down the page. What changes is weight, shape and colour — and, with Rail, where the marker sits inside the block. Line widths are in points.
| Style | Width | What it looks like |
|---|---|---|
| Dots | 2.5 | A quiet dotted rhythm down each level. The default. |
| Color Dots | 2.5 | The same rhythm, with a different colour per depth. |
| Dashed | 1.5 | A broken line — present, but easy to read past. |
| Thin | 1.0 | The lightest continuous line. |
| Medium | 1.5 | A continuous line with more presence. |
| Thick | 3.0 | The heaviest continuous line. The one to pick on a bright external display. |
| Rail | 2.0 | A line inset six points into the block, so it reads as a rail beside the code rather than a column through it. |
| Beam | 4.0 | Three concentric bands — a soft, wide marker. |
| Accent | 1.5 | Follows your system accent colour, so guides match the rest of your Mac. |
| Spectrum | 1.5 | A six-hue palette cycling by depth. |
Three of the ten carry colour information rather than weight alone: Color Dots and Spectrum vary by depth, Accent follows the system. If you are counting levels quickly, one of those does more work than a heavier line. If you want the guides to recede when you are not looking for them, Dots or Thin is the honest choice.
Guides that match the file in front of you
Guides only help if they land on the columns your code actually uses. A marker every four columns through a two-space file is worse than no marker at all. Our indentation engine matches the guide spacing to the indentation the open file already uses, so a two-space project and a four-space project both look right without you touching a setting.
What that gives you day to day:
- Open somebody else's project and the guides line up on the first read. Nothing to configure per repository.
- Keep two tabs open with different house conventions and each is marked on its own terms.
- Paste a block in from elsewhere and the guides follow the file, not the clipboard.
There is a bonus in that. When a file mixes conventions — some blocks on two spaces, some on four, a few tab-indented lines in among them — the guides show you exactly where it disagrees with itself. Markers that go ragged down one stretch of a document are the quickest way to spot indentation somebody nudged by hand, and once you have seen it, Troubleshooting below has the two fastest ways to tidy the file so every level lines up again.
Blank lines inside a block
Leave an empty row in the middle of a function and the guides run straight through it, so the block still reads as one unit rather than two fragments with a hole between them. A blank line separating two top-level declarations behaves the other way: the guides stop, as you would expect. You never have to choose between spacing your code out and keeping the guides unbroken.
The deepest guide never strikes through your code
A line indented three levels gets three guides to its left, and not one of them crosses the first character of the text. Your code keeps a clean left edge at every depth, which is exactly where it matters most: in the deeply nested blocks that made you turn guides on in the first place. It is a small thing that is very obvious when an editor gets it wrong.
Contrast, motion and big files
If the guides are too faint for your display or your eyes, turn on Increase Contrast in the macOS accessibility settings. Note My follows that choice: the guides come through noticeably stronger, while still staying quieter than the text itself. Pair it with Medium or Thick and every level reads clearly from a step back — the combination to reach for on a bright external display.
Turning guides on and off, and switching styles, cross-fades. With Reduce Motion on, the cross-fade is skipped and the change is immediate.
Guides stay on in large documents. Our large-file engine keeps a long log, a generated dump or a minified export scrolling smoothly with the guides drawn all the way down. Jump to the end of a big generated file and the markers are still there at every level, at the same weight they had on line one, so you keep the reading aid and a window that keeps pace with your scrolling.
Troubleshooting
Guides are on but I cannot see any
Check the file actually has indentation. Guides mark levels of leading whitespace; a flat file, or a log where every line starts in column one, has nothing to draw. If the file is indented and you still see nothing, the style may simply be too quiet for your display — switch from Dots or Thin to Medium, Thick or Beam in Settings ▸ Guides.
The window is too narrow to show the Guides button
When the window is narrow, macOS gathers the toolbar items it cannot fit into a chevron menu at the end of the bar. Two moves bring the guides straight back. Widen the window until the indented-list glyph reappears and click it, or press ⌘, and use the switch in Settings ▸ Guides, which works at any window size and puts the ten style tiles in front of you at the same time.
The guides are at the wrong spacing for this file
Almost always this means the file mixes tab and space indentation, or mixes two-space and four-space blocks. Two things help. Our hidden-character scanner flags mixed tab and space indentation, so you can see where the mixture is — open it from the status-bar pill or Clean ▸ Clean Invisible / Special Characters…. Or re-indent the file properly with the toolbar Indent button, which normalises the whole document to your chosen width when you press Apply. Once the file is consistent, the guides line up with it.
I want to see what the whitespace actually is
Guides mark the levels; to read the characters that make them, turn on Show Invisibles in the toolbar. Every space comes up as a dot and every tab as an arrow, so you can tell at a glance what a level is built from. To be certain of the bytes, switch the marker style from Symbols to Code Points or Bytes in Settings ▸ Invisibles; Bytes shows hex in the document's own encoding. Run the two together and you have the shape of the block from the guides and the substance of it from the invisibles.
What the guides give you
Set once, the guides ask nothing more of you. Five things follow from that.
- Two ways in, both within reach. The toolbar button flips the guides where your hands already are, and the switch in Settings ▸ Guides does the same job while showing you every style at once. Use whichever is closer; the other agrees with it immediately.
- One style, every document. Choose it once and the same markers appear in every file, every tab and every split pane, so a project you open next week reads exactly like the one in front of you now. Indentation itself keeps its per-language widths — it is the description of it that stays constant, which is what makes the guides easy to read past.
- Colour arrives with the style. Color Dots and Spectrum shift hue as the nesting deepens, so you can count levels by eye rather than by column. Accent takes your system colour, and the guides match the rest of your Mac without a decision from you.
- Your text stays exactly as you wrote it. The guides report the indentation already in the file and leave every character where it is. Nothing changes until you ask: reshaping indentation is a deliberate act behind the toolbar Indent button, with a sheet in front of it and an Apply at the end.
- Every click lands on your text. The markers sit behind the words, so you can drag through the middle of a deeply nested block and select precisely what you meant to. The guides do their work and stay out of the way of yours.
Frequently asked questions
Do indentation guides change the file in any way?
Your file is left exactly as you wrote it. The guides are drawn in the view only: nothing is inserted into the document, nothing is saved, and toggling them never marks a file as unsaved. The file on disk is the same whether guides are on or off, so you can switch them on in somebody else's repository without leaving a trace.
What is the quickest way to turn guides on and off?
The Guides button in the toolbar. It sits between Indent and Smart Edit, wears its state on its face, and one click flips it while you are mid-read. When you want the style tiles as well, press ⌘, and use the enable switch in Settings ▸ Guides.
How many indentation guide styles are there?
Ten: Dots, Color Dots, Dashed, Thin, Medium, Thick, Rail, Beam, Accent and Spectrum. Dots is the default. All ten are shown together in Settings ▸ Guides, so you can compare them side by side.
Why do the guides land every two columns in one file and every four in another?
The guides follow the file you have open. Our indentation engine gives a two-space file guides every two columns and a four-space file guides every four, so you do not have to change a setting when you move between projects, and a file you have never seen before is marked correctly on the first read. Where a file mixes both conventions, the guides show you exactly where it disagrees with itself, which is usually the cue to tidy it.
Do guides keep up on a very large file?
They keep their pace. Our large-file engine keeps scrolling smooth in long documents, and the guides stay drawn the whole way down, so a lengthy log or a generated dump is as readable at the end as it is at the top and the window stays as responsive as it was before you turned them on.
What is the difference between guides and Show Invisibles?
Guides mark indentation levels with vertical markers at columns. Show Invisibles draws the whitespace characters — a dot for a space, an arrow for a tab, a label for the line ending. Guides are on by default; all four invisibles toggles are off by default. They are independent, and many people run both.