Refresh docs guidance and pin DocFX builds

[Copilot]

This updates the docs to better reflect the library’s two builder types: ValueStringBuilder as the default path, and FixedSizeValueStringBuilder as the specialized no-growth option. It also tightens the DocFX setup so published docs and local/CI builds use a consistent toolchain.

• Clarify builder selection

  • Reworked the README and docs landing flow to make the recommended entry point obvious.
  • Added a dedicated guide for choosing between ValueStringBuilder, stack-backed ValueStringBuilder, FixedSizeValueStringBuilder, and System.Text.StringBuilder.
  • Expanded the fixed-size guidance to show when to stay fixed and when to move into a growable builder.

• Improve agent-friendly documentation

  • Added a root llms.txt entry point with direct links to the canonical markdown sources and key rendered pages.
  • Updated DocFX resource handling so the published site includes machine-friendly text assets alongside HTML docs.

• Keep docs examples executable

  • Added unit tests that compile and exercise the documented samples from the README and docs.
  • Tightened the fixed-size fallback samples so they demonstrate the actual overflow-to-growable transition.

• Stabilize DocFX usage

  • Pinned DocFX to 2.80.1 in the docs workflow and local helper script.
  • Added the DocFX schema to docfx.json and made the search-index post-processor explicit.

const int userId = 42;
const string userName = "Ada";
const string suffix = " name=";

var builder = new FixedSizeValueStringBuilder(stackalloc char[12]);
builder.Append("id=");
builder.Append(userId);

if (builder.Remaining < suffix.Length + userName.Length)
{
    using var grown = builder.MoveToValueStringBuilder();
    grown.Append(suffix);
    grown.Append(userName);
    return grown.ToString();
}

builder.Append(suffix);
builder.Append(userName);
return builder.ToString();

[Copilot]

Copilot review overview

🟡 Changes recommended

Moderate issues remain in the DocFX helper and documentation sample tests, with additional examples needing correction.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 4

Open (5)

• Constants never test the fitting tail path · New
• Fixed constants never exercise the allocation-free path · New
• Fixed constants always bypass the allocation-free path · New
• Fallback still allocates the returned string · New
• Overflow guidance does not match canonical documentation examples · New

What changed in this PR

This pull request refreshes builder-selection documentation, adds executable samples and agent-friendly docs, and pins DocFX 2.80.1 for local and CI builds.

Changes:

• Clarifies builder selection and fixed-size fallback behavior.
• Adds llms.txt, navigation updates, and machine-friendly DocFX resources.
• Adds documentation sample tests and standardizes DocFX tooling.

File	Summary and final review notes
tests/​LinkDotNet.StringBuilder.UnitTests/​DocumentationSamplesTests.cs	Adds sample tests. Moderate: culture-dependent float assertion and untested fit path.
README.md	Updates builder guidance. Nit: constants never demonstrate the allocation-free path.
docs/​site/​llms.txt	Adds agent-oriented links and guidance. Nit: overflow guidance is broader than the examples.
docs/​site/​index.md	Refreshes documentation landing guidance.
docs/​site/​docfx.json	Configures schema, text resources, and search indexing.
docs/​site/​articles/​toc.yml	Adds the builder-selection guide to navigation.
docs/​site/​articles/​getting_started.md	Clarifies recommended entry points.
docs/​site/​articles/​choosing_builder.md	Adds builder-selection guidance. Nits: dead overflow paths and overstated allocation-free behavior.
docs/​serve_docs.cmd	Pins local DocFX usage. Moderate: downgrade handling may fail for newer installed versions.
.github/​workflows/​docs.yml	Pins DocFX in CI.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.