Code Blocks and Code Groups
Choose between `Code` and `CodeGroup` based on delivery intent, not just by dropping in code.
The easiest part of technical docs to make messy is commands, config, and sample code. Anydocs gives you two main structures: `Code` for a single example, and `CodeGroup` for multiple equivalent ways to do the same thing. Choosing the right structure improves both reader clarity and AI consumption quality.
Steps
- Decide whether you have one example or a set of equivalent examples
- Give each code block a clear language or tab meaning
- Make the code and prose form a complete loop
- Consider reader presentation together with theme settings
Decide whether you have one example or a set of equivalent examples
If you have one shell command, one config snippet, or one API call example, use `Code`. If you want to show npm / pnpm / yarn, or JavaScript / Python / curl equivalents, use `CodeGroup`. Do not force unrelated examples into the same code group.
Give each code block a clear language or tab meaning
Single code blocks should map to a clear language such as `bash`, `json`, `ts`, or `python`. Code groups should keep tab meaning stable, for example by package manager, SDK language, or runtime environment. Do not make one tab a command and another tab a result dump.
Make the code and prose form a complete loop
Every code example should have at least a small amount of surrounding prose explaining what problem it solves, where it should run, and what readers should expect. One of the worst technical-doc patterns is piling up commands without context.
Consider reader presentation together with theme settings
Reader syntax-highlighting theme comes from `site.theme.codeTheme` in project settings. That does not change code content, but it affects readability. Multi-language code groups especially benefit from consistent indentation, naming, and comment style across tabs so they still feel like one coherent example.