Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops import lines, so imported components are not available.
Custom components let trusted project plugins lower into the shared content pipeline.
Navigation and breadcrumbs are configured site features. Their guides live under Customize.
Reading and layout
- Callouts — notes, tips, important messages, warnings, and cautions.
- Badges — short inline labels for statuses, platforms, and versions.
- Keyboard shortcuts — key names inside instructions.
- Short definitions — brief definitions that readers expand with a click, tap, or keyboard.
- Tooltips — supporting text shown on hover or keyboard focus.
- Progress — a bounded count with visible text and a bar.
- Definition lists — terms and rich explanations in semantic HTML.
- Action links — prominent next-step and download links.
- Math — inline and display LaTeX expressions rendered to MathML.
- File trees — nested files, folders, icons, and links.
- Steps — numbered procedures with titles and full instructions.
- Timelines — milestone progress with a current stage and completion bar.
- Collapsibles — individual disclosures and compact groups for optional detail.
- Tabs — alternate views and their child panels.
- Code blocks — fenced examples, filenames, and copy behavior.
- Images — responsive images, captions, width limits, and expanded viewing.
- Diagrams — D2 and Mermaid source rendered to SVG with Markdown source preserved.
- Only — a short block for HTML or Markdown alone.
- Tables — optional row filtering and sticky headings for long tables.
- Walkthroughs — code explained step by step beside a scrolling code pane.
- Hero — a landing page opener with a title, tagline, and action buttons.
- Section — a full-width band on a splash page.
- ThemePreview — a live switcher for trying presets, palettes, and color modes.
- ReaderSection, ReaderChoice, and ReaderFilter — marked sections, choice buttons, and in-page filter controls.
- FrontmatterReference — publish this project's built-in and declared page fields as a live reference.
Links and reading paths
- DocLink — a link by stable document ID.
- DocCard, DocCards, and DocCollection — document previews, curated lists, and filtered collections.
- CookbookChooser — choose among custodian-approved sets of prebuilt recipes.
- RelatedReading — authored relationships as links or cards.
Reuse and API content
- Snippet and Var — shared content and typed values.
- ApiExample and ApiSchema — named OpenAPI samples and schemas.
- Fields — authored field lists that match schema formatting.
Code highlighting explains Shiki, theme selection, plain output, and custom adapters. Tabs and collapsibles accept ordinary Markdown and supported MDX components in their bodies; their subpages explain the exact nesting rules.