--- title: Embed focused code samples description: "Scope :symbol fences to one member, strip declaration noise with bodyonly, and refactor long methods into named helpers so each section of a walkthrough shows one idea." canonical_url: https://usepennington.net/how-to/code-samples/focused-code-samples/ sidecar_url: https://usepennington.net/how-to/code-samples/focused-code-samples.md content_hash: sha256:266f1f8942382d9e11cb61bf009fbeac975ad7f6ba2f8b375bbf2ca7fbc26be3 tokens: 4882 uid: how-to.code-samples.focused-code-samples reading_time_minutes: 6 --- Guides # Embed focused code samples Scope :symbol fences to one member, strip declaration noise with bodyonly, and refactor long methods into named helpers so each section of a walkthrough shows one idea. To limit a code fence to the one member a walkthrough discusses — rather than dumping the whole enclosing file with every sibling member — use the `:symbol` preprocessor's member-scoped form. The recipes below scope a fence to one member, strip declaration noise with `,bodyonly`, carry the file's imports with `,imports`, walk a multi-phase method through named helpers, outline a type's shape with `,signatures`, diff two implementations with `symbol-diff`, and embed a whole file with a bare path. Address a member by its **name path** (`Type.Member`) rather than a hard-coded line range — a name path survives the line shifts that silently break a range. For the fence grammar itself, see [Code-block argument reference](https://usepennington.net/reference/markdown/code-block-args.md). ## Before you begin - An existing Pennington site (see [Create your first Pennington site](https://usepennington.net/tutorials/getting-started/first-site.md) if not), with `Pennington.TreeSitter` wired through `AddTreeSitter` and `ContentRoot` pointing at the root that holds the source to fence. - Comfort authoring markdown code fences — the techniques on this page are all info-string changes on a `csharp:symbol` fence. For a working setup, see [examples/FocusedCodeSamplesExample](https://github.com/usepennington/pennington/tree/main/examples/FocusedCodeSamplesExample). `MonolithWordCounter` carries one long `CountWords` method; `ModularWordCounter` splits the same logic into `Tokenize`, `Tally`, and `Format`. Both are referenced by the fences below. --- ## Fence one member, not the whole type When the surrounding prose is about one method, reach for `Type.Method` instead of a bare `Type`. A member path shrinks the fence to the member the reader cares about; a `Type` reference (or a bare file path with no `>`) pulls the full type or file. The wide form, which lands on a page that only discusses `CountWords`: ````markdown ```csharp:symbol examples/FocusedCodeSamplesExample/MonolithWordCounter.cs > MonolithWordCounter ``` ```` The narrow form, scoped to the method under discussion: ````markdown ```csharp:symbol examples/FocusedCodeSamplesExample/MonolithWordCounter.cs > MonolithWordCounter.CountWords ``` ```` Which renders as: ```csharp:symbol public static string CountWords(string text, int topN) { // Tokenize: split on whitespace, lowercase, strip surrounding punctuation. var words = new List(); foreach (var raw in text.Split([' ', '\t', '\n', '\r'], StringSplitOptions.RemoveEmptyEntries)) { var word = raw.Trim('.', ',', '!', '?', ';', ':', '"', '\'').ToLowerInvariant(); if (word.Length > 0) { words.Add(word); } } // Tally: count occurrences and rank by frequency desc, then alphabetically. var counts = new Dictionary(); foreach (var w in words) { counts[w] = counts.GetValueOrDefault(w, 0) + 1; } var ranked = counts .OrderByDescending(kv => kv.Value) .ThenBy(kv => kv.Key) .Take(topN) .ToList(); // Format: header line plus one word-count row per entry. var sb = new StringBuilder(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } return sb.ToString(); } ``` The name-path grammar — `Type`, `Type.Member`, nested `Type.Inner.Member` — is listed in [Code-block argument reference](https://usepennington.net/reference/markdown/code-block-args.md). ## Strip declaration noise with `,bodyonly` Even a member-scoped fence still carries the signature and any leading doc comment. When the prose has already named the method and summarized what it does, both are redundant. Appending `,bodyonly` renders only the body between the braces. ````markdown ```csharp:symbol,bodyonly examples/FocusedCodeSamplesExample/MonolithWordCounter.cs > MonolithWordCounter.CountWords ``` ```` Which renders as: ```csharp:symbol,bodyonly // Tokenize: split on whitespace, lowercase, strip surrounding punctuation. var words = new List(); foreach (var raw in text.Split([' ', '\t', '\n', '\r'], StringSplitOptions.RemoveEmptyEntries)) { var word = raw.Trim('.', ',', '!', '?', ';', ':', '"', '\'').ToLowerInvariant(); if (word.Length > 0) { words.Add(word); } } // Tally: count occurrences and rank by frequency desc, then alphabetically. var counts = new Dictionary(); foreach (var w in words) { counts[w] = counts.GetValueOrDefault(w, 0) + 1; } var ranked = counts .OrderByDescending(kv => kv.Value) .ThenBy(kv => kv.Key) .Take(topN) .ToList(); // Format: header line plus one word-count row per entry. var sb = new StringBuilder(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } return sb.ToString(); ``` `,bodyonly` also works on types (members between the braces, skipping the type header) and properties (the `get`/`set` accessors). ## Carry the imports with `,imports` A member-scoped fence drops the file's `using` / `import` / `require` lines, so a reader can't see where the types resolve from. Append `,imports` to prepend the file's top-of-file imports above the snippet, separated by a blank line. ````markdown ```csharp:symbol,imports examples/FocusedCodeSamplesExample/MonolithWordCounter.cs > MonolithWordCounter.CountWords ``` ```` Which renders as: ```csharp:symbol,imports using System.Text; public static string CountWords(string text, int topN) { // Tokenize: split on whitespace, lowercase, strip surrounding punctuation. var words = new List(); foreach (var raw in text.Split([' ', '\t', '\n', '\r'], StringSplitOptions.RemoveEmptyEntries)) { var word = raw.Trim('.', ',', '!', '?', ';', ':', '"', '\'').ToLowerInvariant(); if (word.Length > 0) { words.Add(word); } } // Tally: count occurrences and rank by frequency desc, then alphabetically. var counts = new Dictionary(); foreach (var w in words) { counts[w] = counts.GetValueOrDefault(w, 0) + 1; } var ranked = counts .OrderByDescending(kv => kv.Value) .ThenBy(kv => kv.Key) .Take(topN) .ToList(); // Format: header line plus one word-count row per entry. var sb = new StringBuilder(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } return sb.ToString(); } ``` `,imports` prepends every import at the top of the file, not only the ones the member references. It composes with `,bodyonly` — the imports lead, the body follows — and is a no-op for whole-file embeds and for languages with no syntactic import statement (Ruby's `require` is a method call, not a declaration). ## Walk a multi-phase method through named helpers When the target method runs 25+ lines across distinct phases, fence each phase as its own helper instead of fencing the monolith. `ModularWordCounter` is the same logic as `MonolithWordCounter` split into three helpers — `Tokenize`, `Tally`, and `Format` — orchestrated by a short `CountWords`. A whole-type fence gives the reader the full picture in one place: ````markdown ```csharp:symbol examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter ``` ```` Which renders as: ```csharp:symbol public static class ModularWordCounter { /// /// Returns a column-aligned report of the most /// frequent words in by orchestrating the three /// helpers below. /// /// Free-form text to analyse. /// Number of top-frequency words to include. /// A multi-line string suitable for console output. public static string CountWords(string text, int topN) { var words = Tokenize(text); var ranked = Tally(words, topN); return Format(ranked); } /// /// Splits on whitespace, lower-cases every token, /// and strips surrounding punctuation. Empty tokens are dropped. /// public static List Tokenize(string text) { var words = new List(); foreach (var raw in text.Split([' ', '\t', '\n', '\r'], StringSplitOptions.RemoveEmptyEntries)) { var word = raw.Trim('.', ',', '!', '?', ';', ':', '"', '\'').ToLowerInvariant(); if (word.Length > 0) { words.Add(word); } } return words; } /// /// Groups , counts occurrences, and returns the /// top ranked by frequency descending then /// alphabetically. /// public static List> Tally(List words, int topN) { var counts = new Dictionary(); foreach (var w in words) { counts[w] = counts.GetValueOrDefault(w, 0) + 1; } return counts .OrderByDescending(kv => kv.Value) .ThenBy(kv => kv.Key) .Take(topN) .ToList(); } /// /// Renders as a header line plus one /// column-aligned row per entry. /// public static string Format(List> ranked) { var sb = new StringBuilder(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } return sb.ToString(); } /// /// Same output as , but rents its /// from /// instead of allocating a fresh one each call. Exists to pair with /// inside an xmldocid-diff fence so the /// delta is small and focused on one mechanical change. /// public static string FormatV2(List> ranked) { var sb = StringBuilderPool.Get(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } var result = sb.ToString(); StringBuilderPool.Return(sb); return result; } } ``` In a walkthrough, fence each helper separately so each section carries one idea: ````markdown ```csharp:symbol,bodyonly examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter.CountWords ``` ```csharp:symbol,bodyonly examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter.Tokenize ``` ```csharp:symbol,bodyonly examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter.Tally ``` ```csharp:symbol,bodyonly examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter.Format ``` ```` The orchestrator renders as a three-liner that reads top-to-bottom as the outline for the walkthrough: ```csharp:symbol,bodyonly var words = Tokenize(text); var ranked = Tally(words, topN); return Format(ranked); ``` `Tokenize`: ```csharp:symbol,bodyonly var words = new List(); foreach (var raw in text.Split([' ', '\t', '\n', '\r'], StringSplitOptions.RemoveEmptyEntries)) { var word = raw.Trim('.', ',', '!', '?', ';', ':', '"', '\'').ToLowerInvariant(); if (word.Length > 0) { words.Add(word); } } return words; ``` `Tally`: ```csharp:symbol,bodyonly var counts = new Dictionary(); foreach (var w in words) { counts[w] = counts.GetValueOrDefault(w, 0) + 1; } return counts .OrderByDescending(kv => kv.Value) .ThenBy(kv => kv.Key) .Take(topN) .ToList(); ``` `Format`: ```csharp:symbol,bodyonly var sb = new StringBuilder(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } return sb.ToString(); ``` `:symbol` resolves a member by name path within the file, so give each helper a distinct name — overloads resolve to the first declaration and can't be told apart. ## Show a type's shape with `,signatures` When the point is a type's public members — what it exposes, not how each member works — append `,signatures`. Every member body collapses to `{ … }`, leaving the declarations, signatures, doc comments, and member order intact for an at-a-glance outline. ````markdown ```csharp:symbol,signatures examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter ``` ```` Which renders as: ```csharp:symbol,signatures public static class ModularWordCounter { /// /// Returns a column-aligned report of the most /// frequent words in by orchestrating the three /// helpers below. /// /// Free-form text to analyse. /// Number of top-frequency words to include. /// A multi-line string suitable for console output. public static string CountWords(string text, int topN) { … } /// /// Splits on whitespace, lower-cases every token, /// and strips surrounding punctuation. Empty tokens are dropped. /// public static List Tokenize(string text) { … } /// /// Groups , counts occurrences, and returns the /// top ranked by frequency descending then /// alphabetically. /// public static List> Tally(List words, int topN) { … } /// /// Renders as a header line plus one /// column-aligned row per entry. /// public static string Format(List> ranked) { … } /// /// Same output as , but rents its /// from /// instead of allocating a fresh one each call. Exists to pair with /// inside an xmldocid-diff fence so the /// delta is small and focused on one mechanical change. /// public static string FormatV2(List> ranked) { … } } ``` `,signatures` works on a single member too, rendering only its signature over an elided body. It targets brace-delimited languages (C#, Java, TypeScript, Go, Rust); Python and Ruby suites collapse to a best-effort `…`. As the inverse of `,bodyonly`, the two don't combine — `,signatures` wins when both are set. ## Show a delta with `symbol-diff` When the article's point is that one version replaces another — a small refactor, a migration, a perf tweak — fence both versions with `symbol-diff`. The preprocessor emits a unified diff so the reader sees the two or three lines that moved rather than comparing two fences by eye. The form works best when the delta is small; whole-method rewrites render every line as changed and bury the point. `ModularWordCounter.FormatV2` is deliberately a one-change variant of `Format`. It rents its `StringBuilder` from a pool instead of constructing a fresh one, and returns the builder at the end. Everything else is identical, so the diff collapses to those lines. ````markdown ```csharp:symbol-diff,bodyonly examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter.Format examples/FocusedCodeSamplesExample/ModularWordCounter.cs > ModularWordCounter.FormatV2 ``` ```` Which renders as: ```csharp:symbol-diff,bodyonly var sb = new StringBuilder(); var sb = StringBuilderPool.Get(); sb.AppendLine($"Top {ranked.Count} words:"); foreach (var kv in ranked) { sb.Append(kv.Key.PadRight(12)); sb.Append(' '); sb.AppendLine(kv.Value.ToString()); } return sb.ToString(); var result = sb.ToString(); StringBuilderPool.Return(sb); return result; ``` The fence body must hold exactly two references, one per line, in before → after order. `,bodyonly` applies to both sides, so the diff compares implementations without declaration boilerplate drowning out the change. ## Embed a whole file with a bare path Top-level-statement `Program.cs` files, `.razor` components, markdown or YAML fixtures, and JSON / TOML / config files have no member to scope to. A bare `` reference with no `> member` embeds the entire file: ````markdown ```csharp:symbol examples/FocusedCodeSamplesExample/Program.cs ``` ```` Which renders as: ```csharp:symbol using FocusedCodeSamplesExample; const string sample = """ the quick brown fox jumps over the lazy dog the fox was quick and the dog was lazy """; Console.WriteLine("=== MonolithWordCounter ==="); Console.WriteLine(MonolithWordCounter.CountWords(sample, topN: 3)); Console.WriteLine("=== ModularWordCounter ==="); Console.WriteLine(ModularWordCounter.CountWords(sample, topN: 3)); ``` --- ## Verify - Rebuild the site with `dotnet run --project docs/Pennington.Docs -- build` and reload the page — each fence renders at the scope its info string declares, with no carry-over of enclosing-type members. A member-scoped fence (`> Type.Member`) shows only that member; a `,bodyonly` fence drops the signature; the whole-file fence shows every line of `Program.cs`. - Rename `Tokenize` to `Split` in `examples/FocusedCodeSamplesExample/ModularWordCounter.cs` and rebuild — the build report surfaces an unresolved `ModularWordCounter.Tokenize` reference rather than silently rendering nothing. ## Related - Reference: [Markdown extensions catalog](https://usepennington.net/reference/markdown/extensions.md) — the full fence grammar including `symbol`, `symbol,bodyonly`, and `symbol-diff`. - Reference: [Code-block argument reference](https://usepennington.net/reference/markdown/code-block-args.md) — info-string parser details and the full list of suffix forms. - How-to: [Annotate code blocks](https://usepennington.net/how-to/code-samples/code-annotations.md) — per-line `[!code highlight]` / `[!code ++]` directives that compose with the fence forms on this page. [Previous Group adjacent code fences into a tabbed sample](https://usepennington.net/how-to/code-samples/tabbed-code.md)[Next Add a colored callout for a note, tip, warning, or caution](https://usepennington.net/how-to/rich-content/alerts.md)